shorewall_code/Shorewall-common/releasenotes.txt

Shorewall 4.1 Patch Release 2.

----------------------------------------------------------------------------
               R E L E A S E  4 . 1  H I G H L I G H T S
----------------------------------------------------------------------------
1) Support is included for multiple internet providers through the same
   ethernet interface.

2) Support for NFLOG has been added.

3) Enhanced operational logging

Problems corrected in Shorewall 4.1.2.

1)  If any of the following files was missing, a harmless Perl warning
    was issued:

       accounting
       maclist
       masq
       nat
       netmap
       rfc1918
       routestopped
       tunnels

    This problem was experienced mostly by Debian users and users of
    Debian derivatives such as Ubuntu.

2)  The iptables utility doesn't retry operations that fail due to
    resource shortage. Beginning with this release, Shorewall reruns
    iptables when such a failure occurs.

3)  Previously, Shorewall-perl did not accept log levels in upper case
    (e.g., INFO). Log levels are treated in a case-insensitive manner
    by Shorewall-perl.

4)  The column headers in macro files were not aligned. This has been
    corrected, along with some inaccuracies in the macro.template file.

5)  The shorewall.conf files in the Samples did not contain some
    recently-defined options. They are now up to date.

6)  The names of the Jabber macros were shuffled. They are now named
    correctly.

Other changes in Shorewall 4.1.2.

1)  Shorewall 4.1.2 contains enhanced operational logging capabilities
    through a set of related enhancements to Shorewall-common and
    Shorewall-perl. The enhancements are not supported by
    Shorewall-shell nor are they supported by Shorewall-lite except
    when the script is compiled using Shorewall-perl.

    a)  The STARTUP_LOG option in /etc/shorewall/shorewall.conf gives
        the name of the Shorewall operational log. The log will be
        created if it does not exist.

    b)  The LOG_VERBOSITY option in /etc/shorewall/shorewall.conf gives
        the verbosity at which logging will occur. It uses the same
        value range as VERBOSITY:

	-1    Do not log
	0     Almost quiet
	1     Only major steps
	2     Verbose

    c)  An absolute VERBOSITY may be specified on the command line
        using the -v option followed by -1,0,1 or 2.

	Example:

		shorewall -v2 check

    d)  The /etc/init.d/shorewall script supplied with the
        shorewall.net packages sets '-v0' as the default. This may be
        overridden with the OPTIONS setting in /etc/defaults/shorewall or
        /etc/sysconfig/shorewall.

    Logging occurs on both Shorewall-perl and the generated script when
    the following commands are issued:

	start
	restart
	refresh

    Messages in the log are always timestamped.

    This change implemented two new options to the Shorewall-perl
    compiler (/usr/share/shorewall-perl/compiler.pl).

	     --log=<logfile>
	     --log_verbosity={-1|0-2}

    The --log option is ignored when --log_verbosity is not supplied or
    is supplied with value -1.

    To avoid a proliferation of parameters to
    Shorewall::Compiler::compile(), that function has been changed to
    use named parameters. Parameter names are:

	 object          Object file. If omitted or '', the
			 configuration is syntax checked. 
	 directory       Directory. If omitted or '', configuration
			 files are located using
			 CONFIG_PATH. Otherwise, the directory named by
			 this parameter is searched first.
	 verbosity       Verbosity; range -1 to 2
	 timestamp       0|1 -- timestamp messages.
	 debug           0|1 -- include stack trace in warning/error
			 messages. 
	 export          0|1 -- compile for export.
	 chains          List of chains to be reloaded by 'refresh'.
	 log             File to log compiler messages to.
	 log_verbosity   Log Verbosity; range -1 to 2.

    Those parameters that are supplied must have defined values.

    Defaults are:

	     object		'' ('check' command)
	     directory		''
	     verbosity		1
	     timestamp		0
	     debug		0
	     export		0
	     chains		''
	     log		''
	     log_verbosity	-1
	     

    Example:

    use lib '/usr/share/shorewall-perl/';
    use Shorewall::Compiler;

    compiler( object        => '/root/firewall', 
              log           => '/root/compile.log',
	      log_verbosity => 2 );

2)  Previously, when HIGH_ROUTE_MARKS=Yes, Shorewall allowed non-zero
    mark values < 256 to be assigned in the OUTPUT chain. This has been
    changed so that only high mark values may be assigned
    there. Packet marking rules for traffic shaping of packets
    originating on the firewall must be coded in the POSTROUTING table.

3)  Previously, Shorewall did not range-check the value of the
    VERBOSITY option in shorewall.conf. Beginning with Shorewall 4.1.2:

    a) A VERBOSITY setting outside the range -1 through 2 is rejected.
    b) After the -v and -q options are applied, the resulting value is
       adjusted to fall within the range -1 through 2.

4)  The tcdevices file has been extended to include an OPTIONS
    column. Currently only a single option is defined.

    classify   When specified, you must use explicit CLASSIFY tcrules
	       to classify traffic by class. Shorewall will not create
               any CLASSIFY rules to classify traffic by mark value.

    The 'classify' option should be specified when you want to do all
    classification using CLASSIFY tcrules. Because CLASSIFY is not a
    terminating target, every packet passes through all CLASSIFY
    rules. 'classify' can prevent packets from having to pass through
    useless additional rules.

    Example:

    /etc/shorewall/tcdevices

	#INTERFACE	IN-BANDWITH	OUT-BANDWIDTH	OPTIONS
	$EXT_IF		1300kbit	384kbit		classify

    /etc/shorewall/tcclasses

	#INTERFACE MARK	RATE	  CEIL	    PRIORITY OPTIONS
	$EXT_IF	   10	5*full/10 full	    1	     tcp-ack,tos-minimize-delay
	$EXT_IF	   20	2*full/10 6*full/10 2	     default
	$EXT_IF	   30	2*full/10 6*full/10 3

    /etc/shorewall/tcrules

	#MARK	SOURCE		DEST	PROTO	PORT(S)	SOURCE
	#                                               PORT(S)
	1:110	192.168.0.0/22	$EXT_IF         
	1:130	206.124.146.177 $EXT_IF	tcp     -       873

    This example shows my own simple traffic shaping configuration. I
    have three classes; one for traffic from our local network, one for
    rsync from the master shorewall.net server, and one for all other
    DMZ traffic. I use CLASSIFY rules to assign traffic to the first
    and third class and let the rest default to the second class.

Migration Issues.

1)  Previously, when HIGH_ROUTE_MARKS=Yes, Shorewall allowed non-zero
    mark values < 256 to be assigned in the OUTPUT chain. This has been
    changed so that only high mark values may be assigned
    there. Packet marking rules for traffic shaping of packets
    originating on the firewall must be coded in the POSTROUTING table.

2)  Previously, Shorewall did not range-check the value of the
    VERBOSITY option in shorewall.conf. Beginning with Shorewall 4.1:

    a) A VERBOSITY setting outside the range -1 through 2 is rejected.
    b) After the -v and -q options are applied, the resulting value is
       adjusted to fall within the range -1 through 2.

New Features in Shorewall 4.1.

1)  Shorewall 4.1 contains experimental support for multiple Internet
    providers through a single ethernet interface. Configuring two
    providers through a single interface differs from two providers
    through two interfaces in several ways.

    a) Only ethernet (or ethernet-like) interfaces can be used. For
       inbound traffic, the MAC addresses of the gateway routers is used
       to determine which provider a packet was received through. Note
       that only routed traffic can be categorized using this technique.

    b) You must specify the address on the interface that corresponds to
       a particular provider in the INTERFACE column by following the
       interface name with a colon (":") and the address.
 
    c) Entries in /etc/shorewall/masq must be qualified by the provider
       name (or number).

    d) This feature requires Realm Match support in your kernel and
       iptables. If you use a capabilities file, you need to regenerate
       the file with Shorewall 4.0.6 or Shorewall-lite 4.0.6.
 
    e) You must add route_rules entries for networks that are accessed
       through a particular provider.

    f) If you have additional IP addresses through either provider,
       you must add route_rules to direct traffic FROM each of those
       addresses through the appropriate provider.

     Example:

     Providers Blarg (1) and Avvanta (2) are both connected to
     eth0. The firewall's IP address with Blarg is 206.124.146.176/24
     (gateway 206.124.146.254) and the IP address from Avvanta is
     130.252.144.8/24 (gateway 130.252.144.254). We have a second IP
     address (206.124.146.177) from Blarg.

     /etc/shorewall/providers:

       #PROVIDER   NUMBER  MARK    DUPLICATE INTERFACE            GATEWAY
       Blarg       1       1       main      eth0:206.124.146.176 206.124.146.254 ...
       Avvanta     2       2       main      eth0:130.252.144.8   130.252.144.254 ...

     /etc/shorewall/masq:

       #INTERFACE          SOURCE          ADDRESS
       eth0(Blarg)         130.252.144.8   206.124.146.176
       eth0(Avvanta)       206.124.146.176 130.252.144.8
       eth0(Blarg)         eth1            206.124.146.176
       eth0(Avvanta)       eth1            130.252.144.8

     /etc/shorewall/route_rules:

	#SOURCE		DEST			PROVIDER	PRIORITY
	-		206.124.146.0/24	Blarg		1000
	-		130.252.144.0/24	Avvanta		1000
	206.124.146.177	-			Blarg		26000

2)  You may now include the name of a table (nat, mangle or filter) in
    a 'shorewall refresh' command by following the table name with a
    colon (e.g., mangle:). This causes all non-builtin chains in the
    table to be reloaded.

    Example:

	shorewall refresh nat:

3)  When no chain name is given to the 'shorewall refresh' command, the
    mangle table is refreshed along with the blacklist chain (if
    any). This allows you to modify /etc/shorewall/tcrules and install
    the changes using 'shorewall refresh'.

4)  Support for the NFLOG log target has been added. NFLOG is a
    successor to ULOG. In addition, both ULOG and NFLOG may be followed
    by a list of up to three numbers in parentheses.

    The first number specifies the netlink group (1-32). If omitted
    (e.g., NFLOG(,0,10)) then a value of 1 is assumed.

    The second number specifies the maximum number of bytes to copy. If
    omitted, 0 (no limit) is assumed.

    The third number specifies the number of log messages that should
    be buffered in the kernel before they are sent to user space. The
    default is 1.

    Examples:

    /etc/shorewall/shorewall.conf:

	MACLIST_LOG_LEVEL=NFLOG(1,0,1)

    /etc/shorewall/rules:

	ACCEPT:NFLOG(1,0,1) vpn fw tcp ssh,time,631,8080

5)  Shorewall-perl 4.1.0 implements an alternative syntax for macro
    parameters and for the NFQUEUE queue number. Rather than following
    the macro name (or NFQUEUE) with a slash ("/") and the parameter,
    the parameter may be enclosed in parentheses.

    Examples -- each pair shown below are equivalent:

    DNS/ACCEPT	     DNS(ACCEPT)
    NFQUEUE/3	     NFQUEUE(3)
    
    The old syntax will still be accepted but will cease to be documented
    in some future Shorewall release.