auto-generate firewall rule options

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
-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
@@ -79,6 +79,10 @@ all: pve-admin-guide.html
 	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 $@

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);

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.
+

pve-firewall.adoc

@@ -130,32 +130,40 @@ in addition to the general 'Enable Firewall' option in the 'Options' tab.
 Firewall Rules
 ~~~~~~~~~~~~~~
 
-Any firewall rule consists of a direction (`IN` or `OUT`) and an
+Firewall rules consists of a direction (`IN` or `OUT`) and an
-action (`ACCEPT`, `DENY`, `REJECT`). Additional options can be used to
+action (`ACCEPT`, `DENY`, `REJECT`). You can also specify a macro
-refine rule matches. Here are some examples:
+name. Macros contain predifined sets of rules and options. Rules can be disabled by prefixing them with '|'.
 
+.Firewall rules syntax
 ----
 [RULES]
 
-#TYPE ACTION [OPTIONS]
+DIRECTION ACTION [OPTIONS]
-#TYPE MACRO(ACTION) [OPTIONS]
+|DIRECTION ACTION [OPTIONS] # disabled rule
 
-# -i      <INTERFACE>
+DIRECTION MACRO(ACTION) [OPTIONS] # use predefined macro
-# -source <SOURCE>
+----
-# -dest   <DEST>
-# -p      <PROTOCOL>
-# -dport  <DESTINATION_PORT>
-# -sport  <SOURCE_PORT>
 
+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 -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 +mynetgroup   # accept ssh for ipset mynetgroup
+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 myserveralias #accept ssh for alias myserveralias
 
 |IN SSH(ACCEPT) -i net0 # disabled rule
+
+IN  DROP # drop all incoming packages
+OUT ACCEPT # accept all outgoing packages
 ----
 
 Security Groups