Implement ?COMMENT directive

Signed-off-by: Tom Eastep <teastep@shorewall.net>

Shorewall/Macros/macro.A_AllowICMPs

@@ -9,7 +9,7 @@
 #ACTION		SOURCE	DEST	PROTO	DEST	SOURCE	RATE	USER/
 #					PORT(S)	PORT(S)	LIMIT	GROUP
 
-COMMENT Needed ICMP types
+?COMMENT Needed ICMP types
 
 A_ACCEPT       -	-	icmp	fragmentation-needed
 A_ACCEPT       -	-	icmp	time-exceeded

Shorewall/Macros/macro.A_DropDNSrep

@@ -9,6 +9,6 @@
 #ACTION	SOURCE	DEST	PROTO	DEST	SOURCE	RATE	USER/
 #				PORT(S)	PORT(S)	LIMIT	GROUP
 
-COMMENT Late DNS Replies
+?COMMENT Late DNS Replies
 
 A_DROP	-	-	udp	-	53

Shorewall/Macros/macro.A_DropUPnP

@@ -9,6 +9,6 @@
 #ACTION	SOURCE	DEST	PROTO	DEST	SOURCE	RATE	USER/
 #				PORT(S)	PORT(S)	LIMIT	GROUP
 
-COMMENT UPnP
+?COMMENT UPnP
 
 A_DROP	-	-	udp	1900

Shorewall/Macros/macro.AllowICMPs

@@ -9,7 +9,7 @@
 #ACTION	SOURCE	DEST	PROTO	DEST	SOURCE	RATE	USER/
 #				PORT(S)	PORT(S)	LIMIT	GROUP
 
-COMMENT Needed ICMP types
+?COMMENT Needed ICMP types
 
 DEFAULT ACCEPT
 PARAM	-	-	icmp	fragmentation-needed

Shorewall/Macros/macro.DropDNSrep

@@ -9,7 +9,7 @@
 #ACTION	SOURCE	DEST	PROTO	DEST	SOURCE	RATE	USER/
 #				PORT(S)	PORT(S)	LIMIT	GROUP
 
-COMMENT Late DNS Replies
+?COMMENT Late DNS Replies
 
 DEFAULT DROP
 PARAM	-	-	udp	-	53

Shorewall/Macros/macro.DropUPnP

@@ -9,7 +9,7 @@
 #ACTION	SOURCE	DEST	PROTO	DEST	SOURCE	RATE	USER/
 #				PORT(S)	PORT(S)	LIMIT	GROUP
 
-COMMENT UPnP
+?COMMENT UPnP
 
 DEFAULT DROP
 PARAM	-	-	udp	1900

Shorewall/Perl/Shorewall/Config.pm

@@ -495,6 +495,7 @@ our $file_format;            # Format of configuration file.
 my  $max_format;             # Max format value
 our $comment;                # Current COMMENT
 my  @comments;
+my  $comments_allowed;
 my $warningcount;
 
 my $shorewall_dir;           # Shorewall Directory; if non-empty, search here first for files.
@@ -915,6 +916,7 @@ sub initialize( $;$$) {
     $currentlinenumber = 0;   # Line number
     $first_entry = 0;         # Message to output or function to call on first non-blank file entry
     $max_format  = 1;
+    $comments_allowed = 0;
 
     $shorewall_dir = '';      #Shorewall Directory
 
@@ -1989,15 +1991,16 @@ sub do_open_file( $ ) {
     $currentfilename   = $fname;
 }
 
-sub open_file( $;$ ) {
+sub open_file( $;$$ ) {
     my $fname = find_file $_[0];
 
     assert( ! defined $currentfile );
 
     if ( -f $fname && -s _ ) {
-	$first_entry = 0;
+	$first_entry      = 0;
-	$file_format = 1;
+	$file_format      = 1;
-	$max_format  = supplied $_[1] ? $_[1] : 1;
+	$max_format       = supplied $_[1] ? $_[1] : 1;
+	$comments_allowed = supplied $_[2] ? $_[2] : 0;
 	do_open_file $fname;;
     } else {
 	$ifstack = @ifstack;
@@ -2037,8 +2040,7 @@ sub close_file() {
 
 	fatal_error "SHELL Script failed" unless $result;
 
-	$first_entry = 0;
+	$first_entry      = 0;
-
     }
 }
 
@@ -2163,7 +2165,7 @@ sub process_compiler_directive( $$$$ ) {
 
     print "CD===> $line\n" if $debug;
 
-    directive_error( "Invalid compiler directive ($line)" , $filename, $linenumber ) unless $line =~ /^\s*\?(IF\s+|ELSE|ELSIF\s+|ENDIF|SET\s+|RESET\s+|FORMAT\s+)(.*)$/i;
+    directive_error( "Invalid compiler directive ($line)" , $filename, $linenumber ) unless $line =~ /^\s*\?(IF\s+|ELSE|ELSIF\s+|ENDIF|SET\s+|RESET\s+|FORMAT\s+|COMMENT\s*)(.*)$/i;
 
     my ($keyword, $expression) = ( uc $1, $2 );
 
@@ -2218,7 +2220,7 @@ sub process_compiler_directive( $$$$ ) {
 		       } ,
 
 		       SET => sub() {
-			   if ( ! $omitting ) {
+			   unless ( $omitting ) {
 			       directive_error( "Missing SET variable", $filename, $linenumber ) unless supplied $expression;
 			       ( my $var , $expression ) = split ' ', $expression, 2;
 			       directive_error( "Invalid SET variable ($var)", $filename, $linenumber) unless $var =~ /^\$?([a-zA-Z]\w*)$/;
@@ -2230,7 +2232,7 @@ sub process_compiler_directive( $$$$ ) {
 		       } ,
 
 		       FORMAT => sub() {
-			   if ( ! $omitting ) {
+			   unless ( $omitting ) {
 			       directive_error( "Missing format",                           $filename, $linenumber ) unless supplied $expression;
 			       directive_error( "Invalid format ($expression)",             $filename, $linenumber ) unless $expression =~ /^\d+$/;
 			       directive_error( "Format must be between 1 and $max_format", $filename, $linenumber ) unless $expression && $expression <= $max_format;
@@ -2239,7 +2241,7 @@ sub process_compiler_directive( $$$$ ) {
 		       } ,
 
 		       RESET => sub() {
-			   if ( ! $omitting ) {
+			   unless ( $omitting ) {
 			       my $var = $expression;
 			       directive_error( "Missing RESET variable", $filename, $linenumber)        unless supplied $var;
 			       directive_error( "Invalid RESET variable ($var)", $filename, $linenumber) unless $var =~ /^\$?([a-zA-Z]\w*)$/;
@@ -2250,7 +2252,23 @@ sub process_compiler_directive( $$$$ ) {
 				   directive_warning( "Variable $1 does not exist", $filename, $linenumber );
 			       }
 			   }
+		       } ,
+
+		       COMMENT => sub() {
+			   unless ( $omitting ) {
+			       if ( $comments_allowed ) {
+				   if ( have_capability( 'COMMENTS' ) ) {
+				       ( $comment = $line ) =~ s/^\s*\?COMMENT\s*//;
+				       $comment =~ s/\s*$//;
+				   } else {
+				       directive_warning( "COMMENTs ignored -- require comment support in iptables/Netfilter" , $filename, $linenumber ) unless $warningcount++;
+				   }
+			       } else {
+				   directive_error ( "?COMMENT is not allowed in this file", $filename, $linenumber );
+			       }
+			   }
 		       }
+
 		     );
 
     if ( my $function = $directives{$keyword} ) {
@@ -2535,7 +2553,7 @@ sub push_open( $;$ ) {
     push @openstack, \@a;
     @includestack = ();
     $currentfile = undef;
-    open_file( $file , $max );
+    open_file( $file , $max, $comments_allowed );
 }
 
 sub pop_open() {
@@ -2866,7 +2884,7 @@ sub read_a_line($) {
 	    #
 	    # Handle conditionals
 	    #
-	    if ( /^\s*\?(?:IF|ELSE|ELSIF|ENDIF|SET|RESET|FORMAT)/i ) {
+	    if ( /^\s*\?(?:IF|ELSE|ELSIF|ENDIF|SET|RESET|FORMAT|COMMENT)/i ) {
 		$omitting = process_compiler_directive( $omitting, $_, $currentfilename, $. );
 		next;
 	    }

Shorewall/Perl/Shorewall/Misc.pm

@@ -675,7 +675,7 @@ sub process_stoppedrules() {
     my $fw = firewall_zone;
     my $result;
 
-    if ( my $fn = open_file 'stoppedrules' ) {
+    if ( my $fn = open_file 'stoppedrules' , 1, 1 ) {
 	first_entry "$doing $fn...";
 
 	while ( read_a_line( NORMAL_READ ) ) {
@@ -683,7 +683,7 @@ sub process_stoppedrules() {
 	    $result = 1;
 
 	    my ( $target, $source, $dest, $proto, $ports, $sports ) = 
-		split_line1 'stoppedrules file', { target => 0, source => 1, dest => 2, proto => 3, dport => 4, sport => 5 }, { COMMENT => 0, FORMAT => 2 };
+		split_line1 'stoppedrules file', { target => 0, source => 1, dest => 2, proto => 3, dport => 4, sport => 5 }, { COMMENT => 0 };
 
 	    fatal_error( "Invalid TARGET ($target)" ) unless $target =~ /^(?:ACCEPT|NOTRACK)$/;
 
@@ -1208,7 +1208,7 @@ sub setup_mac_lists( $ ) {
 	    }
 	}
 
-	if ( my $fn = open_file 'maclist' ) {
+	if ( my $fn = open_file 'maclist', 1, 1 ) {
 
 	    first_entry "$doing $fn...";
 

Shorewall/Perl/Shorewall/Nat.pm

@@ -282,7 +282,7 @@ sub process_one_masq( )
 #
 sub setup_masq()
 {
-    if ( my $fn = open_file 'masq' ) {
+    if ( my $fn = open_file( 'masq', 1, 1 ) ) {
 
 	first_entry( sub { progress_message2 "$doing $fn..."; require_capability 'NAT_ENABLED' , 'a non-empty masq file' , 's'; } );
 
@@ -379,7 +379,7 @@ sub do_one_nat( $$$$$ )
 #
 sub setup_nat() {
 
-    if ( my $fn = open_file 'nat' ) {
+    if ( my $fn = open_file( 'nat', 1, 1 ) ) {
 
 	first_entry( sub { progress_message2 "$doing $fn..."; require_capability 'NAT_ENABLED' , 'a non-empty nat file' , 's'; } );
 
@@ -415,7 +415,7 @@ sub setup_nat() {
 #
 sub setup_netmap() {
 
-    if ( my $fn = open_file 'netmap' ) {
+    if ( my $fn = open_file 'netmap', 1, 1 ) {
 
 	first_entry "$doing $fn...";
 

Shorewall/Perl/Shorewall/Raw.pm

@@ -213,7 +213,7 @@ sub setup_conntrack() {
 
     for my $name ( qw/notrack conntrack/ ) {
 
-	my $fn = open_file( $name, 3 );
+	my $fn = open_file( $name, 3 , 1 );
 
 	if ( $fn ) {
 

Shorewall/Perl/Shorewall/Rules.pm

@@ -1472,7 +1472,7 @@ sub process_actions() {
     $targets{$_} = new_action( $_ , ACTION + BUILTIN, 1, 0 ) for @builtins;
 
     for my $file ( qw/actions.std actions/ ) {
-	open_file $file;
+	open_file( $file, 2, 1 );
 
 	while ( read_a_line( NORMAL_READ ) ) {
 	    my ( $action, $options ) = split_line 'action file' , { action => 0, options => 1 };
@@ -2744,7 +2744,7 @@ sub process_rules( $ ) {
     #
     $section = 'BLACKLIST';
 
-    my $fn = open_file 'blrules';
+    my $fn = open_file( 'blrules', 1, 1 );
 
     if ( $fn ) {
 	first_entry( sub () {
@@ -2782,7 +2782,7 @@ sub process_rules( $ ) {
     #
     setup_zone_mss;
 
-    $fn = open_file 'rules';
+    $fn = open_file( 'rules', 1, 1 );
 
     if ( $fn ) {
 

Shorewall/Perl/Shorewall/Tc.pm

@@ -225,6 +225,7 @@ sub process_tc_rule( ) {
     }
 
     if ( $originalmark eq 'FORMAT' ) {
+	format_warning;
 	if ( $source =~ /^([12])$/ ) {
 	    $file_format = $1;
 	    return;
@@ -1877,7 +1878,7 @@ sub process_tcinterfaces() {
 #
 sub process_tcpri() {
     my $fn  = find_file 'tcinterfaces';
-    my $fn1 = open_file 'tcpri';
+    my $fn1 = open_file 'tcpri', 1,1;
 
     if ( $fn1 ) {
 	first_entry
@@ -2412,7 +2413,7 @@ sub setup_tc() {
 				    }
 		      );
 
-	if ( my $fn = open_file( 'tcrules' , 2 ) ) {
+	if ( my $fn = open_file( 'tcrules' , 2, 1 ) ) {
 
 	    first_entry "$doing $fn...";
 
@@ -2422,7 +2423,7 @@ sub setup_tc() {
 
 	}
 
-	if ( my $fn = open_file 'secmarks' ) {
+	if ( my $fn = open_file( 'secmarks', 1, 1 ) ) {
 
 	    first_entry "$doing $fn...";
 

Shorewall/Perl/Shorewall/Tunnels.pm

@@ -285,7 +285,7 @@ sub setup_tunnels() {
     #
     # Setup_Tunnels() Starts Here
     #
-    if ( my $fn = open_file 'tunnels' ) {
+    if ( my $fn = open_file( 'tunnels', 1, 1 ) ) {
 
 	first_entry "$doing $fn...";
 

Shorewall/manpages/shorewall-accounting.xml

@@ -182,7 +182,7 @@
         <term><emphasis role="bold">ACTION</emphasis> - {<emphasis
         role="bold">COUNT</emphasis>|<emphasis
         role="bold">DONE</emphasis>|<emphasis>chain</emphasis>[:<emphasis
-        role="bold">{COUNT</emphasis>|JUMP}]|ACCOUNT(<replaceable>table</replaceable>,<replaceable>network</replaceable>)|COMMENT
+        role="bold">{COUNT</emphasis>|JUMP}]|ACCOUNT(<replaceable>table</replaceable>,<replaceable>network</replaceable>)|[?]COMMENT
         <emphasis>comment</emphasis>}</term>
 
         <listitem>
@@ -323,7 +323,7 @@
             </varlistentry>
 
             <varlistentry>
-              <term><emphasis role="bold">COMMENT</emphasis></term>
+              <term><emphasis role="bold">[?]COMMENT</emphasis></term>
 
               <listitem>
                 <para>The remainder of the line is treated as a comment which
@@ -331,6 +331,11 @@
                 found or until the end of the file is reached. To stop adding
                 comments to rules, use a line with only the word
                 COMMENT.</para>
+
+                <note>
+                  <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                  for COMMENT and is preferred.</para>
+                </note>
               </listitem>
             </varlistentry>
           </variablelist>

Shorewall/manpages/shorewall-blrules.xml

@@ -46,7 +46,7 @@
         role="bold">NFQUEUE</emphasis>[<emphasis
         role="bold">(</emphasis><emphasis>queuenumber</emphasis><emphasis
         role="bold">)</emphasis>]<emphasis
-        role="bold">|COMMENT</emphasis>|<emphasis>action</emphasis>|<emphasis>macro</emphasis>[<emphasis
+        role="bold">|[?]COMMENT</emphasis>|<emphasis>action</emphasis>|<emphasis>macro</emphasis>[<emphasis
         role="bold">(</emphasis><emphasis>target</emphasis><emphasis
         role="bold">)</emphasis>]}<emphasis
         role="bold">[:</emphasis>{<emphasis>log-level</emphasis>|<emphasis
@@ -182,15 +182,20 @@
             </varlistentry>
 
             <varlistentry>
-              <term><emphasis role="bold">COMMENT</emphasis></term>
+              <term><emphasis role="bold">[?]COMMENT</emphasis></term>
 
               <listitem>
-                <para>the rest of the line will be attached as a comment to
+                <para>The rest of the line will be attached as a comment to
                 the Netfilter rule(s) generated by the following entries. The
                 comment will appear delimited by "/* ... */" in the output of
                 "shorewall show &lt;chain&gt;". To stop the comment from being
                 attached to further rules, simply include COMMENT on a line by
                 itself.</para>
+
+                <note>
+                  <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                  for COMMENT and is preferred.</para>
+                </note>
               </listitem>
             </varlistentry>
 

Shorewall/manpages/shorewall-conntrack.xml

@@ -73,6 +73,11 @@
     the end of the file is reached. To stop adding comments to rules, use a
     line with only the word COMMENT.</para>
 
+    <note>
+      <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym for COMMENT
+      and is preferred.</para>
+    </note>
+
     <para>The columns in the file are as follows (where the column name is
     followed by a different name in parentheses, the different name is used in
     the alternate specification syntax).</para>
@@ -171,10 +176,10 @@
                 </varlistentry>
 
                 <varlistentry>
-                  <term></term>
+                  <term/>
 
                   <listitem>
-                    <para></para>
+                    <para/>
                   </listitem>
                 </varlistentry>
 

Shorewall/manpages/shorewall-masq.xml

@@ -49,7 +49,7 @@
         role="bold">+</emphasis>]<emphasis>interfacelist</emphasis>[<emphasis
         role="bold">:</emphasis>[<emphasis>digit</emphasis>]][<emphasis
         role="bold">:</emphasis>[<emphasis>dest-address</emphasis>[<emphasis
-        role="bold">,</emphasis><emphasis>dest-address</emphasis>]...[<emphasis>exclusion</emphasis>]]|COMMENT}</term>
+        role="bold">,</emphasis><emphasis>dest-address</emphasis>]...[<emphasis>exclusion</emphasis>]]|{?}COMMENT}</term>
 
         <listitem>
           <para>Outgoing <emphasis>interfacelist</emphasis>. This may be a
@@ -118,6 +118,11 @@
           COMMENT line is found or until the end of the file is reached. To
           stop adding comments to rules, use a line with only the word
           COMMENT.</para>
+
+          <note>
+            <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym for
+            COMMENT and is preferred.</para>
+          </note>
         </listitem>
       </varlistentry>
 

Shorewall/manpages/shorewall-nat.xml

@@ -42,7 +42,7 @@
     <variablelist>
       <varlistentry>
         <term><emphasis role="bold">EXTERNAL</emphasis> -
-        {<emphasis>address</emphasis>|COMMENT}</term>
+        {<emphasis>address</emphasis>|[?]COMMENT}</term>
 
         <listitem>
           <para>External IP Address - this should NOT be the primary IP
@@ -56,6 +56,11 @@
 
           <para>To stop the comment from being attached to further rules,
           simply include COMMENT on a line by itself.</para>
+
+          <note>
+            <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym for
+            COMMENT and is preferred.</para>
+          </note>
         </listitem>
       </varlistentry>
 

Shorewall/manpages/shorewall-rules.xml

@@ -266,7 +266,7 @@
             </varlistentry>
 
             <varlistentry>
-              <term><emphasis role="bold">COMMENT</emphasis></term>
+              <term><emphasis role="bold">[?]COMMENT</emphasis></term>
 
               <listitem>
                 <para>the rest of the line will be attached as a comment to
@@ -275,6 +275,11 @@
                 "shorewall show &lt;chain&gt;". To stop the comment from being
                 attached to further rules, simply include COMMENT on a line by
                 itself.</para>
+
+                <note>
+                  <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                  for COMMENT and is preferred.</para>
+                </note>
               </listitem>
             </varlistentry>
 
@@ -856,7 +861,7 @@
             </orderedlist></para>
 
           <blockquote>
-            <para></para>
+            <para/>
 
             <para>Except when <emphasis role="bold">all</emphasis>[<emphasis
             role="bold">+]|[-</emphasis>] is specified, the server may be

Shorewall/manpages/shorewall-secmarks.xml

@@ -76,7 +76,7 @@
             </varlistentry>
 
             <varlistentry>
-              <term>COMMENT</term>
+              <term>[?]COMMENT</term>
 
               <listitem>
                 <para>The remainder of the line is treated as a comment which
@@ -84,6 +84,11 @@
                 found or until the end of the file is reached. To stop adding
                 comments to rules, use a line with only the word
                 COMMENT.</para>
+
+                <note>
+                  <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                  for COMMENT and is preferred.</para>
+                </note>
               </listitem>
             </varlistentry>
           </variablelist>

Shorewall/manpages/shorewall-tcrules.xml

@@ -357,7 +357,7 @@
             </listitem>
 
             <listitem>
-              <para><emphasis role="bold">COMMENT</emphasis> -- the rest of
+              <para><emphasis role="bold">[?]COMMENT</emphasis> -- the rest of
               the line will be attached as a comment to the Netfilter rule(s)
               generated by the following entries. The comment will appear
               delimited by "/* ... */" in the output of <command>shorewall
@@ -365,6 +365,11 @@
 
               <para>To stop the comment from being attached to further rules,
               simply include COMMENT on a line by itself.</para>
+
+              <note>
+                <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                for COMMENT and is preferred.</para>
+              </note>
             </listitem>
 
             <listitem>

Shorewall/manpages/shorewall-tunnels.xml

@@ -41,7 +41,7 @@
         role="bold">ipip</emphasis>|<emphasis
         role="bold">gre</emphasis>|l2tp|<emphasis
         role="bold">pptpclient</emphasis>|<emphasis
-        role="bold">pptpserver</emphasis>|COMMENT|{<emphasis
+        role="bold">pptpserver</emphasis>|[?]COMMENT|{<emphasis
         role="bold">openvpn</emphasis>|<emphasis
         role="bold">openvpnclient</emphasis>|<emphasis
         role="bold">openvpnserver</emphasis>}[:{<emphasis
@@ -110,6 +110,11 @@
           COMMENT line is found or until the end of the file is reached. To
           stop adding comments to rules, use a line with only the word
           COMMENT.</para>
+
+          <note>
+            <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym for
+            COMMENT and is preferred.</para>
+          </note>
         </listitem>
       </varlistentry>
 

Shorewall6/action.A_AllowICMPs

@@ -8,7 +8,7 @@
 ###############################################################################
 #TARGET		SOURCE		DEST	PROTO		DEST
 #							PORT(S)
-COMMENT Needed ICMP types (RFC4890)
+?COMMENT Needed ICMP types (RFC4890)
 
 A_ACCEPT	-		-	ipv6-icmp	destination-unreachable
 A_ACCEPT	-		-	ipv6-icmp	packet-too-big

Shorewall6/action.AllowICMPs

@@ -12,7 +12,7 @@
 ?FORMAT 2
 DEFAULTS ACCEPT
 
-COMMENT Needed ICMP types (RFC4890)
+?COMMENT Needed ICMP types (RFC4890)
 
 $1	-		-	ipv6-icmp	destination-unreachable
 $1	-		-	ipv6-icmp	packet-too-big

Shorewall6/manpages/shorewall6-accounting.xml

@@ -182,7 +182,7 @@
         <term><emphasis role="bold">ACTION</emphasis> - {<emphasis
         role="bold">COUNT</emphasis>|<emphasis
         role="bold">DONE</emphasis>|<emphasis>chain</emphasis>[:<emphasis
-        role="bold">{COUNT|JUMP}</emphasis>]|COMMENT
+        role="bold">{COUNT|JUMP}</emphasis>]|[?]COMMENT
         <replaceable>comment</replaceable>}</term>
 
         <listitem>
@@ -265,7 +265,7 @@
             </varlistentry>
 
             <varlistentry>
-              <term><emphasis role="bold">COMMENT</emphasis></term>
+              <term><emphasis role="bold">[?]COMMENT</emphasis></term>
 
               <listitem>
                 <para>The remainder of the line is treated as a comment which
@@ -273,6 +273,11 @@
                 found or until the end of the file is reached. To stop adding
                 comments to rules, use a line with only the word
                 COMMENT.</para>
+
+                <note>
+                  <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                  for COMMENT and is preferred.</para>
+                </note>
               </listitem>
             </varlistentry>
           </variablelist>

Shorewall6/manpages/shorewall6-blrules.xml

@@ -47,7 +47,7 @@
         role="bold">NFQUEUE</emphasis>[<emphasis
         role="bold">(</emphasis><emphasis>queuenumber</emphasis><emphasis
         role="bold">)</emphasis>]<emphasis
-        role="bold">|COMMENT</emphasis>|<emphasis>action</emphasis>|<emphasis>macro</emphasis>[<emphasis
+        role="bold">|[?]COMMENT</emphasis>|<emphasis>action</emphasis>|<emphasis>macro</emphasis>[<emphasis
         role="bold">(</emphasis><emphasis>target</emphasis><emphasis
         role="bold">)</emphasis>]}<emphasis
         role="bold">[:</emphasis>{<emphasis>log-level</emphasis>|<emphasis
@@ -183,7 +183,7 @@
             </varlistentry>
 
             <varlistentry>
-              <term><emphasis role="bold">COMMENT</emphasis></term>
+              <term><emphasis role="bold">[?]COMMENT</emphasis></term>
 
               <listitem>
                 <para>the rest of the line will be attached as a comment to
@@ -192,6 +192,11 @@
                 "shorewall6 show &lt;chain&gt;". To stop the comment from
                 being attached to further rules, simply include COMMENT on a
                 line by itself.</para>
+
+                <note>
+                  <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                  for COMMENT and is preferred.</para>
+                </note>
               </listitem>
             </varlistentry>
 

Shorewall6/manpages/shorewall6-conntrack.xml

@@ -73,6 +73,11 @@
     the end of the file is reached. To stop adding comments to rules, use a
     line with only the word COMMENT.</para>
 
+    <note>
+      <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym for COMMENT
+      and is preferred.</para>
+    </note>
+
     <para>The columns in the file are as follows (where the column name is
     followed by a different name in parentheses, the different name is used in
     the alternate specification syntax).</para>

Shorewall6/manpages/shorewall6-rules.xml

@@ -225,7 +225,7 @@
             </varlistentry>
 
             <varlistentry>
-              <term><emphasis role="bold">COMMENT</emphasis></term>
+              <term><emphasis role="bold">[?]COMMENT</emphasis></term>
 
               <listitem>
                 <para>the rest of the line will be attached as a comment to
@@ -234,6 +234,11 @@
                 "shorewall show &lt;chain&gt;". To stop the comment from being
                 attached to further rules, simply include COMMENT on a line by
                 itself.</para>
+
+                <note>
+                  <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                  for COMMENT and is preferred.</para>
+                </note>
               </listitem>
             </varlistentry>
 

Shorewall6/manpages/shorewall6-secmarks.xml

@@ -41,7 +41,7 @@
     <variablelist>
       <varlistentry>
         <term><emphasis role="bold">SECMARK -
-        {SAVE|RESTORE|<replaceable>context</replaceable>|COMMENT
+        {SAVE|RESTORE|<replaceable>context</replaceable>|[?]COMMENT
         <replaceable>comment</replaceable>}</emphasis></term>
 
         <listitem>
@@ -76,7 +76,7 @@
             </varlistentry>
 
             <varlistentry>
-              <term>COMMENT</term>
+              <term>[?]COMMENT</term>
 
               <listitem>
                 <para>The remainder of the line is treated as a comment which
@@ -84,6 +84,11 @@
                 found or until the end of the file is reached. To stop adding
                 comments to rules, use a line with only the word
                 COMMENT.</para>
+
+                <note>
+                  <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                  for COMMENT and is preferred.</para>
+                </note>
               </listitem>
             </varlistentry>
           </variablelist>

Shorewall6/manpages/shorewall6-tcrules.xml

@@ -363,7 +363,7 @@
             </listitem>
 
             <listitem>
-              <para><emphasis role="bold">COMMENT</emphasis> -- the rest of
+              <para><emphasis role="bold">[?]COMMENT</emphasis> -- the rest of
               the line will be attached as a comment to the Netfilter rule(s)
               generated by the following entries. The comment will appear
               delimited by "/* ... */" in the output of <command>shorewall6
@@ -371,6 +371,11 @@
 
               <para>To stop the comment from being attached to further rules,
               simply include COMMENT on a line by itself.</para>
+
+              <note>
+                <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym
+                for COMMENT and is preferred.</para>
+              </note>
             </listitem>
 
             <listitem>

Shorewall6/manpages/shorewall6-tunnels.xml

@@ -97,14 +97,19 @@
           role="bold">tcp</emphasis> or <emphasis role="bold">udp</emphasis>
           (6 or 17), then it may optionally be followed by ":" and a port
           number.</para>
-        </listitem>
-      </varlistentry>
 
-      <varlistentry>
+          <para>Comments may be attached to Netfilter rules generated from
-        <term/>
+          entries in this file through the use of COMMENT lines. These lines
+          begin with the word COMMENT; the remainder of the line is treated as
+          a comment which is attached to subsequent rules until another
+          COMMENT line is found or until the end of the file is reached. To
+          stop adding comments to rules, use a line with only the word
+          COMMENT.</para>
 
-        <listitem>
+          <note>
-          <para/>
+            <para>Beginning with Shorewall 4.5.11, ?COMMENT is a synonym for
+            COMMENT and is preferred.</para>
+          </note>
         </listitem>
       </varlistentry>
 

docs/configuration_file_basics.xml

@@ -1116,11 +1116,11 @@ SHELL cat /etc/shorewall/rules.d/*.rules 2&gt; /dev/null || true</programlisting
     the first token. This requires each of the file processors to handle
     FORMAT separately.</para>
 
-    <para>In Shorewall 4.5.11, the ?FORMAT Directive was created to centralize
+    <para>In Shorewall 4.5.11, the ?FORMAT directive was created to centralize
     processing of FORMAT directives. The old entries, while still supported,
     are now deprecated.</para>
 
-    <para>The format directive is as follows:</para>
+    <para>The ?FORMAT directive is as follows:</para>
 
     <variablelist>
       <varlistentry>
@@ -1177,6 +1177,61 @@ SHELL cat /etc/shorewall/rules.d/*.rules 2&gt; /dev/null || true</programlisting
     </informaltable>
   </section>
 
+  <section>
+    <title>?COMMENT Directive</title>
+
+    <para>A number of files allow attaching comments to generated Netfilter
+    rules:</para>
+
+    <simplelist>
+      <member><filename>accounting</filename></member>
+
+      <member><filename>action</filename>.* files</member>
+
+      <member><filename>blrules</filename></member>
+
+      <member><filename>conntrack</filename></member>
+
+      <member><filename>macro</filename>.* files</member>
+
+      <member><filename>masq</filename></member>
+
+      <member><filename>nat</filename></member>
+
+      <member><filename>rules</filename></member>
+
+      <member><filename>secmarks</filename></member>
+
+      <member><filename>tcrules</filename></member>
+
+      <member><filename>tunnels</filename></member>
+    </simplelist>
+
+    <para>Prior to Shorewall 4.5.11, comments were specified by a line having
+    COMMENT as the first token. The remainder of the line is treated as a
+    comment to be attached to rules.</para>
+
+    <para>In Shorewall 4.5.11, the ?COMMENT directive was created to
+    centralize processing of COMMENT directives. The old entries, while still
+    supported, are now deprecated.</para>
+
+    <para>The ?COMMENT directive is as follows:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>COMMENT [ <replaceable>comment</replaceable> ]</term>
+
+        <listitem>
+          <para>If <replaceable>comment</replaceable> is present, it will
+          appear enclosed in /*....*/ in the output of the <command>shorewall
+          show </command>and <command>shorewall dump</command> commands. If no
+          <replaceable>comment</replaceable> is present, the rules generated
+          by following entries will not have comments attached.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
   <section id="CONFIG_PATH">
     <title>CONFIG_PATH</title>
 

docs/upgrade_issues.xml

@@ -35,7 +35,7 @@
 
       <holder>Thomas M. Eastep</holder>
 
-      <holder></holder>
+      <holder/>
     </copyright>
 
     <legalnotice>
@@ -163,7 +163,7 @@
           <para>?ENDIF.</para>
         </blockquote>
 
-        <para></para>
+        <para/>
       </listitem>
 
       <listitem>
@@ -257,6 +257,36 @@
           <member><filename>tcrules</filename></member>
         </simplelist>
       </listitem>
+
+      <listitem>
+        <para>Also beginning with Shorewalll 4.5.11, ?COMMENT is preferred
+        over COMMENT for specifying comments to be attached to generated
+        Netfilter rules in the following files:</para>
+
+        <simplelist>
+          <member><filename>accounting</filename></member>
+
+          <member><filename>action</filename>.* files</member>
+
+          <member><filename>blrules</filename></member>
+
+          <member><filename>conntrack</filename></member>
+
+          <member><filename>macro</filename>.* files</member>
+
+          <member><filename>masq</filename></member>
+
+          <member><filename>nat</filename></member>
+
+          <member><filename>rules</filename></member>
+
+          <member><filename>secmarks</filename></member>
+
+          <member><filename>tcrules</filename></member>
+
+          <member><filename>tunnels</filename></member>
+        </simplelist>
+      </listitem>
     </orderedlist>
   </section>