auto-generate firewall rule options

diff --git a/Makefile b/Makefile
index 6a02c4b182f356af1d7677146f943844feae8e81..dcaacee105ebe6c7769ebeccdc5c43bdc5cf1481 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,7 @@ RELEASE=4.1
 PVESM_SOURCES=attributes.txt pvesm.adoc pvesm.1-synopsis.adoc $(shell ls pve-storage-*.adoc)
 PVEUM_SOURCES=attributes.txt pveum.adoc pveum.1-synopsis.adoc
 VZDUMP_SOURCES=attributes.txt vzdump.adoc vzdump.1-synopsis.adoc
 PVESM_SOURCES=attributes.txt pvesm.adoc pvesm.1-synopsis.adoc $(shell ls pve-storage-*.adoc)
 PVEUM_SOURCES=attributes.txt pveum.adoc pveum.1-synopsis.adoc
 VZDUMP_SOURCES=attributes.txt vzdump.adoc vzdump.1-synopsis.adoc

-PVEFW_SOURCES=attributes.txt pve-firewall.adoc pve-firewall.8-synopsis.adoc
+PVEFW_SOURCES=attributes.txt pve-firewall.adoc pve-firewall-rules-opts.adoc pve-firewall.8-synopsis.adoc

 QM_SOURCES=attributes.txt qm.adoc qm.1-synopsis.adoc
 PCT_SOURCES=attributes.txt pct.adoc pct.1-synopsis.adoc
 PVEAM_SOURCES=attributes.txt pveam.adoc pveam.1-synopsis.adoc
 QM_SOURCES=attributes.txt qm.adoc qm.1-synopsis.adoc
 PCT_SOURCES=attributes.txt pct.adoc pct.1-synopsis.adoc
 PVEAM_SOURCES=attributes.txt pveam.adoc pveam.1-synopsis.adoc


@@ -79,6 +79,10 @@ all: pve-admin-guide.html
        asciidoc ${ADOC_MAN8_HTML_ARGS} -o $@ $*.adoc
        test -z "$${NOVIEW}" && $(BROWSER) $@ &
 
        asciidoc ${ADOC_MAN8_HTML_ARGS} -o $@ $*.adoc
        test -z "$${NOVIEW}" && $(BROWSER) $@ &
 

+pve-firewall-rules-opts.adoc:
+       ./gen-pve-firewall-rules-opts-adoc.pl >$@.tmp
+       mv $@.tmp $@
+

 datacenter.cfg.5-opts.adoc:
        ./gen-datacenter-cfg-opts-adoc.pl >$@.tmp
        mv $@.tmp $@
 datacenter.cfg.5-opts.adoc:
        ./gen-datacenter-cfg-opts-adoc.pl >$@.tmp
        mv $@.tmp $@

diff --git a/gen-pve-firewall-rules-opts-adoc.pl b/gen-pve-firewall-rules-opts-adoc.pl
new file mode 100755 (executable)
index 0000000..ef3b09c
--- /dev/null
+++ b/gen-pve-firewall-rules-opts-adoc.pl
@@ -0,0 +1,28 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+use PVE::RESTHandler;
+use PVE::Firewall;
+
+my $prop = {};
+PVE::Firewall::add_rule_properties($prop);
+
+my $skip = {
+    action => 1,
+    enable => 1,
+    type => 1,
+    digest => 1,
+    macro => 1,
+    pos => 1,
+    comment => 1,
+};
+
+my $filterFn = sub {
+    my ($k, $phash) = @_;
+
+    return $skip->{$k} || 0;
+};
+
+print PVE::RESTHandler::dump_properties($prop, 'asciidoc', 'arg', $filterFn);

diff --git a/pve-firewall-rules-opts.adoc b/pve-firewall-rules-opts.adoc
new file mode 100644 (file)
index 0000000..0a6361d
--- /dev/null
+++ b/pve-firewall-rules-opts.adoc
@@ -0,0 +1,41 @@
+`-dest` `string` ::
+
+Restrict packet destination address. This can refer to a single IP address,
+an IP set ('+ipsetname') or an IP alias definition. You can also specify an
+address range like '20.34.101.207-201.3.9.99', or a list of IP addresses
+and networks (entries are separated by comma). Please do not mix IPv4 and
+IPv6 addresses inside such lists.
+
+`-dport` `string` ::
+
+Restrict TCP/UDP destination port. You can use service names or simple
+numbers (0-65535), as defined in '/etc/services'. Port ranges can be
+specified with '\d+:\d+', for example '80:85', and you can use comma
+separated list to match several ports or ranges.
+
+`-iface` `string` ::
+
+Network interface name. You have to use network configuration key names for
+VMs and containers ('net\d+'). Host related rules can use arbitrary
+strings.
+
+`-proto` `string` ::
+
+IP protocol. You can use protocol names ('tcp'/'udp') or simple numbers, as
+defined in '/etc/protocols'.
+
+`-source` `string` ::
+
+Restrict packet source address. This can refer to a single IP address, an
+IP set ('+ipsetname') or an IP alias definition. You can also specify an
+address range like '20.34.101.207-201.3.9.99', or a list of IP addresses
+and networks (entries are separated by comma). Please do not mix IPv4 and
+IPv6 addresses inside such lists.
+
+`-sport` `string` ::
+
+Restrict TCP/UDP source port. You can use service names or simple numbers
+(0-65535), as defined in '/etc/services'. Port ranges can be specified with
+'\d+:\d+', for example '80:85', and you can use comma separated list to
+match several ports or ranges.
+

diff --git a/pve-firewall.adoc b/pve-firewall.adoc
index aa921cb8dcfc248b250e88ebba9d83bbbde684b9..307966fa13927b6bd9a6ace007f1f89b0e12f283 100644 (file)
--- a/pve-firewall.adoc
+++ b/pve-firewall.adoc
@@ -130,32 +130,40 @@ in addition to the general 'Enable Firewall' option in the 'Options' tab.
 Firewall Rules
 ~~~~~~~~~~~~~~
 
 Firewall Rules
 ~~~~~~~~~~~~~~
 

-Any firewall rule consists of a direction (`IN` or `OUT`) and an
-action (`ACCEPT`, `DENY`, `REJECT`). Additional options can be used to
-refine rule matches. Here are some examples:
+Firewall rules consists of a direction (`IN` or `OUT`) and an
+action (`ACCEPT`, `DENY`, `REJECT`). You can also specify a macro
+name. Macros contain predifined sets of rules and options. Rules can be disabled by prefixing them with '|'.

 
 

+.Firewall rules syntax

 ----
 [RULES]
 
 ----
 [RULES]
 

-#TYPE ACTION [OPTIONS]
-#TYPE MACRO(ACTION) [OPTIONS]
+DIRECTION ACTION [OPTIONS]
+|DIRECTION ACTION [OPTIONS] # disabled rule

 
 

-# -i      <INTERFACE>
-# -source <SOURCE>
-# -dest   <DEST>
-# -p      <PROTOCOL>
-# -dport  <DESTINATION_PORT>
-# -sport  <SOURCE_PORT>
+DIRECTION MACRO(ACTION) [OPTIONS] # use predefined macro
+----
+
+The following options can be used to refine rule matches. 
+
+include::pve-firewall-rules-opts.adoc[]
+
+Here are some examples:

 
 

+----
+[RULES]

 IN SSH(ACCEPT) -i net0
 IN SSH(ACCEPT) -i net0 # a comment
 IN SSH(ACCEPT) -i net0
 IN SSH(ACCEPT) -i net0 # a comment

-IN SSH(ACCEPT) -i net0 -source 192.168.2.192  # only allow SSH from 192.168.2.192
+IN SSH(ACCEPT) -i net0 -source 192.168.2.192 # only allow SSH from 192.168.2.192

 IN SSH(ACCEPT) -i net0 -source 10.0.0.1-10.0.0.10 # accept SSH for ip range
 IN SSH(ACCEPT) -i net0 -source 10.0.0.1,10.0.0.2,10.0.0.3 #accept ssh for ip list
 IN SSH(ACCEPT) -i net0 -source 10.0.0.1-10.0.0.10 # accept SSH for ip range
 IN SSH(ACCEPT) -i net0 -source 10.0.0.1,10.0.0.2,10.0.0.3 #accept ssh for ip list

-IN SSH(ACCEPT) -i net0 -source +mynetgroup   # accept ssh for ipset mynetgroup
-IN SSH(ACCEPT) -i net0 -source myserveralias   #accept ssh for alias myserveralias
+IN SSH(ACCEPT) -i net0 -source +mynetgroup # accept ssh for ipset mynetgroup
+IN SSH(ACCEPT) -i net0 -source myserveralias #accept ssh for alias myserveralias

 
 |IN SSH(ACCEPT) -i net0 # disabled rule
 
 |IN SSH(ACCEPT) -i net0 # disabled rule

+
+IN  DROP # drop all incoming packages
+OUT ACCEPT # accept all outgoing packages

 ----
 
 Security Groups
 ----
 
 Security Groups