Add Tuomo Soini's WUDO macro

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

Shorewall/Macros/macro.Bitcoin

@@ -0,0 +1,8 @@
+#
+# Shorewall --/usr/share/shorewall/macro.Bitcoin
+#
+# Macro for handling Bitcoin P2P traffic
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp	8333

Shorewall/Macros/macro.BitcoinRPC

@@ -0,0 +1,8 @@
+#
+# Shorewall --/usr/share/shorewall/macro.BitcoinRPC
+#
+# Macro for handling Bitcoin RPC traffic
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp	8332

Shorewall/Macros/macro.BitcoinZMQ

@@ -0,0 +1,9 @@
+#
+# Shorewall --/usr/share/shorewall/macro.BitcoinZMQ
+#
+# Macro for handling Bitcoin ZMQ traffic
+# See https://github.com/bitcoin/bitcoin/blob/master/doc/zmq.md
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp	28332

Shorewall/Macros/macro.ONCRPC

@@ -0,0 +1,8 @@
+#
+# Shorewall -- /usr/share/shorewall/macro.ONCRPC
+#
+# This macro handles ONC RCP traffic (for rpcbind on Linux, etc).
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp,udp	111

Shorewall/Macros/macro.Tor

@@ -0,0 +1,8 @@
+#
+# Shorewall --/usr/share/shorewall/macro.Tor
+#
+# Macro for handling Tor Onion Network traffic
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp	9001	

Shorewall/Macros/macro.TorBrowserBundle

@@ -0,0 +1,8 @@
+#
+# Shorewall --/usr/share/shorewall/macro.TorBrowserBundle
+#
+# Macro for handling Tor Onion Network traffic provided by Tor Browser Bundle
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp	9150

Shorewall/Macros/macro.TorControl

@@ -0,0 +1,8 @@
+#
+# Shorewall --/usr/share/shorewall/macro.TorControl
+#
+# Macro for handling Tor Controller Applications traffic
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp	9051	

Shorewall/Macros/macro.TorDirectory

@@ -0,0 +1,8 @@
+#
+# Shorewall --/usr/share/shorewall/macro.TorDirectory
+#
+# Macro for handling Tor Directory traffic
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp	9030

Shorewall/Macros/macro.TorSocks

@@ -0,0 +1,8 @@
+#
+# Shorewall --/usr/share/shorewall/macro.TorSocks
+#
+# Macro for handling Tor Socks Proxy traffic
+#
+##############################################################################################################################################################
+#ACTION		SOURCE		DEST		PROTO	DPORT	SPORT	ORIGDEST	RATE	USER	MARK	CONNLIMIT	TIME	HEADERS	SWITCH	HELPER
+PARAM		-		-		tcp	9050	

Shorewall/Macros/macro.WUDO

@@ -0,0 +1,9 @@
+
+# Shorewall -- /usr/share/shorewall/macro.WUDO
+#
+# This macro handles WUDO (Windows Update Delivery Optimization)
+#
+###############################################################################
+#ACTION	SOURCE	DEST	PROTO	DPORT	SPORT	ORIGDEST	RATE	USER
+
+PARAM	-	-	tcp	7680

Shorewall/Perl/Shorewall/Chains.pm

@@ -430,13 +430,14 @@ our $VERSION = 'MODULEVERSION';
 #      Untracked       - =<z1-z2>
 #
 our %chain_table;
-our $raw_table;
-our $nat_table;
-our $mangle_table;
-our $filter_table;
-our $export;
-our %renamed;
-our %nfobjects;
+our $raw_table;         # Reference to $chain_table{raw}
+our $nat_table;         # Reference to $chain_table{nat}
+our $mangle_table;      # Reference to $chain_table{mangle}
+our $filter_table;      # Reference to $chain_table{filter}
+
+our $export;            # True if we are compiling for export
+our %renamed;           # Maps chain renaming during optimization
+our %nfobjects;         # Records nfacct objects
 
 #
 # Target Types
@@ -464,10 +465,10 @@ use constant { STANDARD     =>      0x1,       #defined by Netfilter
 	       IPTABLES     => 0x100000,       #IPTABLES or IP6TABLES
 	       TARPIT       => 0x200000,       #TARPIT
 
-	       FILTER_TABLE =>  0x1000000,
-	       MANGLE_TABLE =>  0x2000000,
-	       RAW_TABLE    =>  0x4000000,
-	       NAT_TABLE    =>  0x8000000,
+	       FILTER_TABLE =>  0x1000000,     #Target allowed in the filter table
+	       MANGLE_TABLE =>  0x2000000,     #Target allowed in the mangle table
+	       RAW_TABLE    =>  0x4000000,     #Target allowed in the raw table
+	       NAT_TABLE    =>  0x8000000,     #Target allowed in the nat table
 	   };
 #
 # Valid Targets -- value is a combination of one or more of the above
@@ -686,15 +687,15 @@ our %ipset_exists;
 #
 # The following constants and hash are used to classify keys in a rule hash
 #
-use constant { UNIQUE      => 1,
-	       TARGET      => 2,
-	       EXCLUSIVE   => 4,
-	       MATCH       => 8,
-	       CONTROL     => 16,
-	       COMPLEX     => 32,
-	       NFACCT      => 64,
-	       EXPENSIVE   => 128,
-	       RECENT      => 256,
+use constant { UNIQUE      => 1,       # Simple header matches - only allowed once per rule
+	       TARGET      => 2,       # Rule target or its options
+	       EXCLUSIVE   => 4,       # 'state' or 'conntrack --ctstate'
+	       MATCH       => 8,       # Currently means 'policy ...'
+	       CONTROL     => 16,      # Unsed internally by the compiler - does not contribute to the iptables rule
+	       COMPLEX     => 32,      # Currently means 'contrack --cstate'
+	       NFACCT      => 64,      # nfacct match
+	       EXPENSIVE   => 128,     # Has high rule-processing cost in the kernel
+	       RECENT      => 256,     # recent match
 	   };
 
 our %opttype = ( rule          => CONTROL,
@@ -740,6 +741,9 @@ our %opttype = ( rule          => CONTROL,
 		 targetopts    => TARGET,
 	       );
 
+#
+# These allow the user to specify long option names in raw ip[6]tables input
+#
 our %aliases = ( protocol        => 'p',
 		 source          => 's',
 		 destination     => 'd',
@@ -759,7 +763,7 @@ our %isocodes;
 
 use constant { ISODIR => '/usr/share/xt_geoip/LE' };
 
-our %switches;
+our %switches;   # Recoreds switches (conditions)
 
 #
 # Rather than initializing globals in an INIT block or during declaration,
@@ -785,7 +789,9 @@ sub initialize( $$$ ) {
     $filter_table  = $chain_table{filter};
     %renamed       = ();
     #
-    # Used to sequence chain names in each table.
+    # Used to sequence chain names in each table. $hard is true on the initial call to this function and
+    # false, when this function is called a second time to re-initialize before generating stopped ip[6]tables-
+    # restore input
     #
     %chainseq = () if $hard;
     #
@@ -1745,6 +1751,10 @@ sub add_rule($$;$) {
 #
 # New add_rule implementation
 #
+
+#
+# Push a set of matches into an irule (a rule using the new hash representation)
+#
 sub push_matches {
 
     my $ruleref = shift;
@@ -1911,6 +1921,9 @@ sub compare_values( $$ ) {
     }
 }
 
+#
+# Add an irule with matches but no target
+#
 sub add_irule( $;@ ) {
     my ( $chainref, @matches ) = @_;
 
@@ -2712,6 +2725,12 @@ sub add_expanded_jump( $$$$ ) {
     add_reference( $chainref, $toref ) while --$splitcount > 0;
 }
 
+#
+# Utility function used by add_ijump() and add_ijump_extended().
+# Returns a reference to the added rule. Return may be reference
+# to the dummy rule if the chain was already complete (last rule
+# is a simple jump to a terminating target).
+#
 sub add_ijump_internal( $$$$$;@ ) {
     my ( $fromref, $jump, $to, $expandports, $origin, @matches ) = @_;
 
@@ -2759,16 +2778,26 @@ sub add_ijump_internal( $$$$$;@ ) {
     $expandports ? handle_port_ilist( $fromref, $ruleref, 1 ) : push_irule( $fromref, $ruleref );
 }
 
+#
+# Add an jump to the end of a chain
+#
 sub add_ijump( $$$;@ ) {
     my ( $fromref, $jump, $to, @matches ) = @_;
     add_ijump_internal( $fromref, $jump, $to, 0, '', @matches );
 }
 
+#
+# Like add_ijump() but also accepts an origin of the jump (the config file and line number
+# that caused the jump to be generated).
+#
 sub add_ijump_extended( $$$$;@ ) {
     my ( $fromref, $jump, $to, $origin, @matches ) = @_;
     add_ijump_internal( $fromref, $jump, $to, 0, $origin, @matches );
 }
 
+#
+# Insert a jump at a zero-relative index into a chain.
+#
 sub insert_ijump( $$$$;@ ) {
     my ( $fromref, $jump, $to, $index, @matches ) = @_;
 
@@ -2840,6 +2869,9 @@ sub delete_jumps ( $$ ) {
     }
 }
 
+#
+# Reset the passed flag(s) in the passed chain
+#
 sub reset_optflags( $$ ) {
     my ( $chain, $flags ) = @_;
 
@@ -2852,6 +2884,9 @@ sub reset_optflags( $$ ) {
     $chainref;
 }
 
+#
+# Set the passed flag(s) in the passed chain
+#
 sub set_optflags( $$ ) {
     my ( $chain, $flags ) = @_;
 
@@ -2966,6 +3001,10 @@ sub accounting_chainrefs() {
     grep $_->{accounting} , values %$filter_table;
 }
 
+#
+# Ensure the existance of a chain in the mangle table and return
+# a reference to its chain table entry
+#
 sub ensure_mangle_chain($;$$) {
     my ( $chain, $number, $restriction ) = @_;
 
@@ -2976,6 +3015,10 @@ sub ensure_mangle_chain($;$$) {
     $chainref;
 }
 
+#
+# Ensure the existance of a chain in the nat table and return
+# a reference to its chain table entry
+
 sub ensure_nat_chain($) {
     my $chain = $_[0];
 
@@ -2984,6 +3027,10 @@ sub ensure_nat_chain($) {
     $chainref;
 }
 
+#
+# Ensure the existance of a chain in the raw table and return
+# a reference to its chain table entry
+#
 sub ensure_raw_chain($) {
     my $chain = $_[0];
 
@@ -3007,12 +3054,18 @@ sub new_builtin_chain($$$)
     $chainref;
 }
 
+#
+# Create a chain in the filter table, returning a reference to its chain table entry
+#
 sub new_standard_chain($) {
     my $chainref = new_chain 'filter' ,$_[0];
     $chainref->{referenced} = 1;
     $chainref;
 }
 
+#
+# Create a new action chain, returning a reference to its chain table entry
+#
 sub new_action_chain($$) {
     my $chainref = &new_chain( @_ );
     $chainref->{referenced} = 1;
@@ -3020,12 +3073,18 @@ sub new_action_chain($$) {
     $chainref;
 }
 
+#
+# Create a chain in the nat table, returning a reference to its chain table entry
+#
 sub new_nat_chain($) {
     my $chainref = new_chain 'nat' ,$_[0];
     $chainref->{referenced} = 1;
     $chainref;
 }
 
+#
+# Create a new manual chain, returning a reference to its chain table entry
+#
 sub new_manual_chain($) {
     my $chain = $_[0];
     fatal_error "Chain name ($chain) too long" if length $chain > 29;
@@ -3036,6 +3095,9 @@ sub new_manual_chain($) {
     $chainref;
 }
 
+#
+# Ensure the existance of a manual chain and return a reference to its chain table entry
+#
 sub ensure_manual_chain($) {
     my $chain = $_[0];
     my $chainref = $filter_table->{$chain} || new_manual_chain($chain);
@@ -3045,6 +3107,9 @@ sub ensure_manual_chain($) {
 
 sub log_irule_limit( $$$$$$$$@ );
 
+#
+# Ensure the existance of the blacklist logging chain (blacklog)
+#
 sub ensure_blacklog_chain( $$$$$ ) {
     my ( $target, $disposition, $level, $tag, $audit ) = @_;
 
@@ -3063,6 +3128,9 @@ sub ensure_blacklog_chain( $$$$$ ) {
     'blacklog';
 }
 
+#
+# Ensure the existance of the audited blacklist logging chain (A_blacklog)
+#
 sub ensure_audit_blacklog_chain( $$$ ) {
     my ( $target, $disposition, $level ) = @_;
 
@@ -3084,7 +3152,6 @@ sub ensure_audit_blacklog_chain( $$$ ) {
 #
 # Create and populate the passed AUDIT chain if it doesn't exist. Return chain name
 #
-
 sub ensure_audit_chain( $;$$$ ) {
     my ( $target, $action, $tgt, $table ) = @_;
 
@@ -3121,7 +3188,6 @@ sub ensure_audit_chain( $;$$$ ) {
 #
 # Return the appropriate target based on whether the second argument is 'audit'
 #
-
 sub require_audit($$;$) {
     my ($action, $audit, $tgt ) = @_;
 
@@ -5037,7 +5103,9 @@ sub do_proto( $$$;$ )
     $output;
 }
 
-
+#
+# Generate a mac address match
+#
 sub do_mac( $ ) {
     my $mac = $_[0];
 
@@ -5050,6 +5118,9 @@ sub do_mac( $ ) {
     "-m mac ${invert}--mac-source $mac ";
 }
 
+#
+# Version of do_proto() that generates an irule match rather than an iptables text match
+#
 sub do_iproto( $$$ )
 {
     my ($proto, $ports, $sports ) = @_;
@@ -5245,6 +5316,9 @@ sub do_iproto( $$$ )
     @output;
 }
 
+#
+# Generate a mac address match in irule format.
+#
 sub do_imac( $ ) {
     my $mac = $_[0];
 
@@ -5307,7 +5381,6 @@ sub verify_small_mark( $ ) {
 #
 # Generate an appropriate -m [conn]mark match string for the contents of a MARK column
 #
-
 sub do_test ( $$ )
 {
     my ($testval, $mask) = @_;
@@ -5462,6 +5535,9 @@ sub do_connlimit( $ ) {
     }
 }
 
+#
+# Create a calendar match
+#
 sub do_time( $ ) {
     my ( $time ) = @_;
 
@@ -5500,6 +5576,11 @@ sub do_time( $ ) {
     $result;
 }
 
+#
+# Resolve a user/group name to the appropriate numeric id. Only do the resolution
+# if we are not compiling for export, since remote name->id mapping is likely to
+# be different.
+#
 sub resolve_id( $$ ) {
     my ( $id, $type ) = @_;
 
@@ -5563,8 +5644,6 @@ sub do_user( $ ) {
 #
 # Create a "-m tos" match for the passed TOS
 #
-# This helper is also used during tos file processing
-#
 sub decode_tos( $$ ) {
     my ( $tos, $set ) = @_;
 
@@ -6101,6 +6180,9 @@ sub get_interface_address( $;$ );
 
 sub get_interface_gateway ( $;$$ );
 
+#
+# Verify and record a runtime address variable
+#
 sub record_runtime_address( $$;$$ ) {
     my ( $addrtype, $interface, $protect, $provider ) = @_;
 
@@ -6591,6 +6673,9 @@ sub match_ipsec_in( $$ ) {
     @match;
 }
 
+#
+# Match Dest IPSEC
+#
 sub match_ipsec_out( $$ ) {
     my ( $zone , $hostref ) = @_;
     my @match;
@@ -6615,7 +6700,7 @@ sub match_ipsec_out( $$ ) {
 }
 
 #
-# Handle a unidirectional IPSEC Options
+# Handle unidirectional IPSEC Options
 #
 sub do_ipsec_options($$$)
 {
@@ -6692,7 +6777,7 @@ sub do_ipsec($$) {
 }
 
 #
-# Generate a log message
+# Generate a logging rule
 #
 sub log_rule_limit( $$$$$$$$;$ ) {
     my ($level, $chainref, $chn, $dispo, $limit, $tag, $command, $matches, $origin ) = @_;
@@ -6888,6 +6973,9 @@ sub log_irule_limit( $$$$$$$$@ ) {
     }
 }
 
+#
+# Wrappers for the above that use the global default log limit
+#
 sub log_rule( $$$$ ) {
     my ( $level, $chainref, $disposition, $matches ) = @_;
 
@@ -8475,7 +8563,7 @@ sub add_interface_options( $ ) {
 # We may have to generate part of the input at run-time. The rules array in each chain
 # table entry may contain both rules or shell source, determined by the contents of the 'mode'
 # member. We alternate between writing the rules into the temporary file to be passed to
-# iptables-restore (CAT_MODE) and and writing shell source into the generated script (CMD_MODE).
+# iptables-restore (CAT_MODE) and writing shell source into the generated script (CMD_MODE).
 #
 # The following two functions are responsible for the mode transitions.
 #
@@ -9055,7 +9143,7 @@ sub create_nfobjects() {
 }
 #
 #
-# Generate the netfilter input
+# Generate the input to ip[6]tables-restore or to 'ip[6]tables -R'
 #
 sub create_netfilter_load( $ ) {
     my $test = shift;

Shorewall/Perl/Shorewall/Config.pm

@@ -523,13 +523,17 @@ our %capdesc = ( NAT_ENABLED     => 'NAT',
 		 CAPVERSION      => 'Capability Version',
 		 KERNELVERSION   => 'Kernel Version',
 	       );
-
+#
+# Keeps track of which capabilities were used or required - Key is capability name
+#
 our %used;
 
 use constant {
                USED     => 1,
 	       REQUIRED => 2 };
-
+#
+# Common Protocols
+#
 use constant {
 	       ICMP                => 1,
 	       TCP                 => 6,
@@ -541,7 +545,7 @@ use constant {
 	       UDPLITE             => 136,
 	     };
 #
-# Optimization masks
+# Optimization masks (OPTIMIZE option)
 #
 use constant {
 	       OPTIMIZE_POLICY_MASK    => 0x02 , # Call optimize_policy_chains()
@@ -550,7 +554,9 @@ use constant {
                OPTIMIZE_MASK           => 0x1E , # Do optimizations beyond level 1
 	       OPTIMIZE_ALL            => 0x1F , # Maximum value for documented categories.
 	     };
-
+#
+# Map helpers to protocols
+#
 our %helpers = ( amanda          => UDP,
 		 ftp             => TCP,
 		 irc             => TCP,
@@ -625,7 +631,7 @@ our %config_files = ( #accounting      => 1,
 #
 our @auditoptions = qw( BLACKLIST_DISPOSITION MACLIST_DISPOSITION TCP_FLAGS_DISPOSITION );
 #
-# Directories to search for configuration files
+# Directories to search for configuration files (CONFIG_PATH option)
 #
 our @config_path;
 #
@@ -648,10 +654,12 @@ our %compiler_params;
 # Action parameters
 #
 our %actparams;
-our $parmsmodified;
-our $usedcaller;
-our $inline_matches;
-
+our $parmsmodified;          # True of the current action has modified its parameters
+our $usedcaller;             # True if $CALLER has been acceseed in the current action
+our $inline_matches;         # Inline matches from the current rule
+#
+# File handling
+#
 our $currentline;            # Current config file line image
 our $rawcurrentline;         # Current config file line with no variable expansion
 our $currentfile;            # File handle reference
@@ -669,6 +677,7 @@ our $comments_allowed;       # True if [?]COMMENT is allowed in the current file
 our $nocomment;              # When true, ignore [?]COMMENT in the current file
 our $sr_comment;             # When true, $comment should only be applied to the current rule
 our $warningcount;           # Used to suppress duplicate warnings about missing COMMENT support
+our $ulogcount;              # Used to suppress duplicate warnings about ULOG support
 our $directive_callback;     # Function to call in compiler_directive
 
 our $shorewall_dir;          # Shorewall Directory; if non-empty, search here first for files.
@@ -747,10 +756,11 @@ our $ifstack;
 #    [0] - Keyword (IF, ELSEIF, ELSE or ENDIF)
 #    [1] - True if the outermost IF evaluated to false
 #    [2] - True if the the last unterminated IF evaluated to false
+#    [3] = The line number of the directive
 #
 # From .shorewallrc
 #
-our ( %shorewallrc, %shorewallrc1 );
+our ( %shorewallrc, %shorewallrc1 ); # Shorewallrc setting from local system and from remote firewall respectively
 #
 # read_a_line options
 #
@@ -828,6 +838,7 @@ sub initialize( $;$$$) {
     $comment       = '';
     $sr_comment    = '';
     $warningcount  = 0;
+    $ulogcount     = 0;
     #
     # Misc Globals
     #
@@ -1291,7 +1302,7 @@ sub initialize( $;$$$) {
     $compiletime =~ s/ +/ /g;
 }
 
-my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
+my @moabbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
 
 sub add_ipset( $ ) {
     $ipsets{$_[0]} = 1;
@@ -1391,7 +1402,7 @@ sub info_message
 
     if ( $log ) {
 	@localtime = localtime;
-	printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
     }
 
     if ( $confess ) {
@@ -1419,7 +1430,7 @@ sub warning_message
 
     if ( $log ) {
 	@localtime = localtime;
-	printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
     }
 
     if ( $confess ) {
@@ -1544,7 +1555,7 @@ sub fatal_error	{
 
     if ( $log ) {
 	our @localtime = localtime;
-	printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
 
 	if ( $confess ) {
 	    print $log longmess( "   ERROR: @_$currentlineinfo\n" );
@@ -1567,6 +1578,9 @@ sub fatal_error	{
     }
 }
 
+#
+# This one is used for reporting syntax errors in embedded Perl code
+#
 sub fatal_error1 {
     handle_first_entry if $first_entry;
 
@@ -1574,7 +1588,7 @@ sub fatal_error1 {
 
     if ( $log ) {
 	our @localtime = localtime;
-	printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
 
 	if ( $debug ) {
 	    print $log longmess( "   ERROR: @_\n" );
@@ -1684,7 +1698,7 @@ sub emit {
 
     if ( $script || $debug ) {
 	#
-	# 'compile' as opposed to 'check'
+	# 'compile' (as opposed to 'check') or debugging (CLI 'trace' command)
 	#
 	for ( @_ ) {
 	    unless ( /^\s*$/ ) {
@@ -1845,12 +1859,15 @@ sub progress_message {
 
 	    @localtime = localtime unless $havelocaltime;
 
-	    printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	    printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
 	    print $log "${leading}${line}\n";
 	}
     }
 }
 
+#
+# This one doesn't compress out superfluous white space
+#
 sub progress_message_nocompress {
     my $havelocaltime = 0;
 
@@ -1864,7 +1881,7 @@ sub progress_message_nocompress {
 
 	@localtime = localtime unless $havelocaltime;
 
-	printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
 	print $log "@_\n";
     }
 }
@@ -1885,7 +1902,7 @@ sub progress_message2 {
 
 	@localtime = localtime unless $havelocaltime;
 
-	printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
 	print $log "@_\n";
     }
 }
@@ -1906,7 +1923,7 @@ sub progress_message3 {
 
 	@localtime = localtime unless $havelocaltime;
 
-	printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
 	print $log "@_\n";
     }
 }
@@ -2077,7 +2094,7 @@ sub set_debug( $$ ) {
 #
 sub find_file($)
 {
-    my ( $filename, $nosearch ) = @_;
+    my ( $filename ) = @_;
 
     return $filename if $filename =~ '/';
 
@@ -2094,8 +2111,12 @@ sub find_file($)
     "$config_path[0]$filename";
 }
 
+#
+# Search the CONFIG_PATH for a file that is writable. Ignore directories where sample/default files are installed,
+# because users have a bad habit of including those in the CONFIG_PATH
+#
 sub find_writable_file($) {
-    my ( $filename, $nosearch ) = @_;
+    my ( $filename ) = @_;
 
     return $filename if $filename =~ '/';
 
@@ -2117,6 +2138,9 @@ sub supplied( $ ) {
     defined $val && $val ne '';
 }
 
+#
+# This one is used for determining if an action argument has been passed (excludes '-')
+#
 sub passed( $ ) {
     my $val = shift;
 
@@ -2135,7 +2159,7 @@ sub split_list( $$;$ ) {
 }
 
 #
-# This version handles parenthetical list elements with embedded commas. It removes the parentheses
+# This version handles parenthetical list elements containing embedded commas. It removes the parentheses
 #
 sub split_list1( $$;$ ) {
     my ($list, $type, $keepparens ) = @_;
@@ -2519,7 +2543,7 @@ sub split_line2( $$;$$$ ) {
 }
 
 #
-# Same as above, only it splits the raw current line
+# Same as above, only it splits the raw current line (line prior to variable expansion)
 #
 sub split_rawline2( $$;$$$ ) {
     my $savecurrentline = $currentline;
@@ -2627,6 +2651,7 @@ sub do_open_file( $ ) {
 # - Maximum value allowed in ?FORMAT directives
 # - ?COMMENT allowed in this file
 # - Ignore ?COMMENT in ths file
+# - Default file format
 #
 sub open_file( $;$$$$ ) {
     my ( $fname, $mf, $ca, $nc, $cf ) = @_;
@@ -2719,7 +2744,7 @@ sub clear_currentfilename() {
 }
 
 #
-# Process an ?IF, ?ELSIF, ?ELSE or ?END directive
+# Utility functions for processing compiler directives
 #
 
 #
@@ -2746,7 +2771,7 @@ sub directive_warning( $$$$ ) {
 
 	if ( $log ) {
 	    @localtime = localtime;
-	    printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	    printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
 	    print $log  "   WARNING: $_[0]\n";
 	}
 
@@ -2771,7 +2796,7 @@ sub directive_info( $$$$ ) {
 
 	if ( $log ) {
 	    @localtime = localtime;
-	    printf $log '%s %2d %02d:%02d:%02d ', $abbr[$localtime[4]], @localtime[3,2,1,0];
+	    printf $log '%s %2d %02d:%02d:%02d ', $moabbr[$localtime[4]], @localtime[3,2,1,0];
 	    print $log  "   INFO: $_[0]\n";
 	}
 
@@ -3523,7 +3548,7 @@ sub shorewall {
 # We do this processing in read_a_line() rather than in the higher-level routines because
 # Embedded Shell/Perl scripts are processed out of read_a_line(). If we were to defer announcement
 # until we get back to the caller of read_a_line(), we could issue error messages about parsing and
-# running scripts in the file before we'd even indicated that we are processing it.
+# running scripts in the file before we'd even reported that we are processing it.
 #
 sub first_entry( $ ) {
     $first_entry = shift;
@@ -3700,6 +3725,7 @@ sub push_action_params( $$$$$$ ) {
 # Return:
 #   1 if the popped parameters were modified
 #   2 if the action used @CALLER
+#   3 if both
 #
 sub pop_action_params( $ ) {
     my $oldparms       = shift;
@@ -3710,6 +3736,10 @@ sub pop_action_params( $ ) {
     $return;
 }
 
+#
+# This is called when a DEFAULTS line is found in an action body. It supplies default values
+# for those paramaters that were not passed, or that were passed as '-'.
+#
 sub default_action_params {
     my $action = shift;
     my ( $val, $i );
@@ -3723,6 +3753,9 @@ sub default_action_params {
     fatal_error "Too Many arguments to action $action" if defined $actparams{$i};
 }
 
+#
+# This function allows embedded Perl in actions to retreive the action paramaters
+#
 sub get_action_params( $ ) {
     my $num = shift;
 
@@ -3738,6 +3771,9 @@ sub get_action_params( $ ) {
     @return;
 }
 
+#
+# Helper for A_* actions
+#
 sub setup_audit_action( $ ) {
     my ( $action ) = @_;
 
@@ -3757,26 +3793,44 @@ sub get_action_logging() {
     @actparams{ 'loglevel', 'logtag' };
 }
 
+#
+# Allow embedded Perl in Actions to get the name of the action chain
+#
 sub get_action_chain() {
     $actparams{0};
 }
 
+#
+# Get the action name from an action file
+#
 sub get_action_chain_name() {
     $actparams{chain};
 }
-
+#
+# This allows an action to make subsequent log messages refer to the invoker of the action rather than the 
+# action itself
+#
 sub set_action_name_to_caller() {
     $actparams{chain} = $actparams{caller};
 }
 
+#
+# Get the current action's disposition
+#
 sub get_action_disposition() {
     $actparams{disposition};
 }
 
+#
+# Set the current action disposition for subsequent logging
+#
 sub set_action_disposition($) {
     $actparams{disposition} = $_[0];
 }
 
+#
+# Alter the value of one of the current actions parameters
+#
 sub set_action_param( $$ ) {
     my $i = shift;
 
@@ -3843,6 +3897,9 @@ sub expand_variables( \$ ) {
     }
 }
 
+#
+# Expand variables from shorewallrc in the current passed line
+#
 sub expand_shorewallrc_variables( \$ ) {
     my ( $lineref, $count ) = ( $_[0], 0 );
     #                         $1      $2   $3                  -     $4
@@ -3886,7 +3943,7 @@ sub handle_first_entry() {
 #   - Handle embedded SHELL and PERL scripts
 #   - Expand shell variables from %params and %ENV.
 #   - Handle INCLUDE <filename>
-#   - Handle ?IF, ?ELSE, ?ENDIF
+#   - Handle ?SECTION
 #
 
 sub read_a_line($) {
@@ -4009,6 +4066,9 @@ sub read_a_line($) {
     }
 }
 
+#
+# Process the passed shorewallrc file, populating %shorewallrc
+#
 sub process_shorewallrc( $$ ) {
     my ( $shorewallrc , $product ) = @_;
 
@@ -4029,6 +4089,12 @@ sub process_shorewallrc( $$ ) {
 	fatal_error "Failed to open $shorewallrc: $!";
     }
 
+    #
+    # Older files may contain VARDIR= rather than VARLIB= to specify the directory
+    # where each product maintains its own state directory. This was confusing,
+    # because in the shell context, VARDIR points to the current product's state
+    # directory.
+    #
     if ( supplied $shorewallrc{VARDIR} ) {
 	if ( ! supplied $shorewallrc{VARLIB} ) {
 	    $shorewallrc{VARLIB} =  $shorewallrc{VARDIR};
@@ -4091,12 +4157,19 @@ sub default_yes_no ( $$;$ ) {
     $result;
 }
 
+#
+# This one is used for options that are supported by IPv4 but not IPv6. It issues a
+# warning message if the option is specified in shorewall6.conf.
+#
 sub default_yes_no_ipv4 ( $$ ) {
     my ( $var, $val ) = @_;
     default_yes_no( $var, $val );
     warning_message "$var=Yes is ignored for IPv6" if $family == F_IPV6 && $config{$var};
 }
 
+#
+# This function handles options that have a numeric value.
+#
 sub numeric_option( $$$ ) {
     my ( $option, $default, $min ) = @_;
 
@@ -4114,6 +4187,9 @@ sub numeric_option( $$$ ) {
     $config{$option} = $val;
 }
 
+#
+# Returns a 32-bit value with the low order n bits set, where n is the passed argument.
+#
 sub make_mask( $ ) {
     0xffffffff >> ( 32 - $_[0] );
 }
@@ -4214,6 +4290,10 @@ sub validate_level( $;$ ) {
 	if ( $value =~ /^(NFLOG|ULOG)$/ ) {
 	    my $olevel  = $value;
 
+	    if ( $value eq 'ULOG' ) {
+		warning_message "ULOG is deprecated in favor of NFLOG. Support for ULOG will be removed in a future release" unless $ulogcount++;
+	    }
+
 	    if ( $qualifier =~ /^[(](.*)[)]$/ ) {
 		my @options = split /,/, $1;
 		my $prefix  = lc $olevel;
@@ -4289,7 +4369,7 @@ sub default_log_level( $$ ) {
 }
 
 #
-# Check a tri-valued variable
+# Check a tri-valued option ("on", "of" and "keep")
 #
 sub check_trivalue( $$ ) {
     my ( $var, $default) = @_;
@@ -4425,7 +4505,8 @@ sub determine_kernelversion() {
 }
 
 #
-# Capability Reporting and detection.
+# Capability Reporting and detection. Each of the following functions detect the
+# availability of the related capability.
 #
 sub Nat_Enabled() {
     qt1( "$iptables $iptablesw -t nat -L -n" );
@@ -5140,7 +5221,7 @@ sub have_capability( $;$ ) {
 
     $setting = $capabilities{ $capability } = detect_capability( $capability ) unless defined $setting;
 
-    $used{$capability} = $required ? 2 : 1 if $setting;
+    $used{$capability} = $required ? REQUIRED : USED if $setting;
 
     $setting;
 }
@@ -5337,6 +5418,9 @@ sub ensure_config_path() {
     }
 
     if ( $shorewall_dir ) {
+	#
+	# A directory has been specified -- place it at the front of the CONFIG_PATH
+	#
 	$shorewall_dir = getcwd if $shorewall_dir =~ m|^(\./*)+$|;
 	$shorewall_dir .= '/' unless $shorewall_dir =~ m|/$|;
 	unshift @config_path, $shorewall_dir if $shorewall_dir ne $config_path[0];
@@ -5371,7 +5455,8 @@ sub conditional_quote( $ ) {
 }
 
 #
-# Update the shorewall[6].conf file. Save the current file with a .bak suffix.
+# 'update' default values are sometimes different from the normal defaut value, to provide
+# backward compatibility.
 #
 sub update_default($$) {
     my ( $var, $val ) = @_;
@@ -5392,6 +5477,9 @@ sub transfer_permissions( $$ ) {
     }
 }
 
+#
+# Update the shorewall[6].conf file. Save the current file with a .bak suffix.
+#
 sub update_config_file( $ ) {
     my ( $annotate ) = @_;
 
@@ -5790,7 +5878,7 @@ sub unsupported_yes_no_warning( $ ) {
 }
 
 #
-# Process the params file
+# Process the params file. Actually processing is done by the 'getparams' program in $LIBEXECDIR/shorewall/.
 #
 sub get_params( $ ) {
     my $export = $_[0];
@@ -7196,6 +7284,9 @@ sub generate_aux_config() {
     finalize_aux_config;
 }
 
+#
+# Generate a report of the fwmark layout
+#
 sub dump_mark_layout() {
     sub dumpout( $$$$$ ) {
 	my ( $name, $bits, $min, $max, $mask ) = @_;