shorewall_code/Shorewall/releasenotes.txt

Shorewall 3.1.4

Note to users upgrading from Shorewall 2.x or 3.0

   Most problems associated with upgrades come from two causes:

   - The user didn't read and follow the migration considerations in these
     release notes.

   - The user mis-handled the /etc/shorewall/shorewall.conf file during
     upgrade. Shorewall is designed to allow the default behavior of
     the product to evolve over time. To make this possible, the design
     assumes that you will not replace your current shorewall.conf file
     during upgrades. If you feel absolutely compelled to have the latest
     comments and options in your shorewall.conf then you must proceed
     carefully.

   While you are at it, if you have a file named /etc/shorewall/rfc1918 then
   please check that file. If it has addresses listed that are NOT in one of
   these three ranges, then please rename the file to /etc/shorewall/rfc1918.old.

	10.0.0.0 - 10.255.255.255
	172.16.0.0 - 172.31.255.255
	192.168.0.0 - 192.168.255.255

   Please see the "Migration Considerations" below for additional upgrade
   information.

Problems Corrected in 3.1.4

1) "shorewall check" generates an error if there are entries in
   /etc/shorewall/massq.

New Features added in 3.1.4

1) The /etc/shorewall/maclist file has a new column layout. The first column is
   now DISPOSITION. This column determines what to do with matching packets and
   can have the value ACCEPT or DROP (if MACLIST_TABLE=filter, it can also
   contain REJECT). This change is upward compatible so your existing maclist
   file can still be used.

2) Shorewall has always been very noisy (lots of messages). No more. The default
   is now to be very quiet and you get more detail using the -v option (or -vv if
   you want the old noisy behavior). The -q option is still supported but only
   reverses the effect of -v. So "shorewall start -qqvv" is still completely quiet
   while "shorewall start -vv" gives the same amount of output as the old "shorewall
   start" did.

Migration Considerations:

None.

New Features:

1)  A new 'shorewall generate' command has been added.

	shorewall generate [ -q ] [ -e ] [ <config directory> ] <script file>

    where:

	-q                    Suppresses many of the progress messages
	-e                    Generates an error if the configuration used
	                      an option that would prevent the generated
	                      script from running on a system other than
	                      where the 'generate' command is running (see
	                      additional consideration a) below).
	                      Also allows the generated script to run
	                      on a system without Shorewall installed.
	-p                    Generate a complete program that can start,
	                      stop, restart, clear and status the firewall
	<config directory>    Is an optional directory to be searched for
	                      configuration files prior to those listed
	                      in CONFIG_DIR in /etc/shorewall/shorewall.conf.
	<script file>         Is the name of the output file.

    The 'generate' command processes the configuration and writes a script file
    which may then be executed (either directly or using the 'shorewall restore'
    command) to configure the firewall.

    'compile' is a synonym for 'generate':

	shorewall compile [ -q ] [ -e ] [ <config directory> ] <script file>

    The generated script contains error checking and will terminate if an
    important command fails. Before terminating:

    a) The script will check for the existence of the restore script specified
       by the RESTOREFILE variable in shorewall.conf. If that restore script
       exists, it is executed.

    b) If the restore script doesn't exist but Shorewall appears to be installed
       on the system, an "/sbin/shorewall stop" command is executed.

    Some additional considerations:

    a) It is possible to run 'generate' ('compile') on one system and then
       run the generated script on another system but there are certain
       limitations.

       1) The same version of Shorewall must be running on the remote system
          unless you use the "-e" option when you compile the script.
       2) The 'detectnets' interface option is not allowed.

    b) If you have extension scripts, they may need modification. The scripts
       will be run at generation time, rather than when the generated script
       is executed. The standard functions like 'run_iptables' and
       'log_rule_limit' will write the iptables command to the script file
       rather than executing the command. As always, you can check $COMMAND
       to determine which shorewall command is being executed.

    In addition to 'generate', a 'shorewall reload' command has been added.

	shorewall [ -q ] reload [ <config directory> ]

    where -q and <config directory> are as above.

    The 'reload' command creates a script using 'generate' and if there are
    no errors, it then restores that script. It is equivalent to:

    if shorewall generate /var/lib/shorewall/.reload; then restore .reload; fi

    The advantage of using reload over restart is that reload results in new
    connections being dropped for a much shorter time. Here are the results of
    tests that I conducted on my own firewall:

    A) shorewall -q restart

	real    0m17.540s
	user    0m5.956s
	sys     0m10.737s

    B) shorewall -q restore foo # foo created using "shorewall generate"

	real    0m3.505s
	user    0m1.332s
	sys     0m2.164s


    C) shorewall -q restore # Restores from file generated by "shorewall save"

	real    0m1.164s
	user    0m0.556s
	sys     0m0.608s

    The time difference from B to C reflects the difference between
    "iptables-restore" and multiple executions of "iptables". The system is a
    1.4Ghz Celeron with 512MB RAM.

    The "-p' option creates a complete program. This program is suitable for
    installation into /etc/init.d and, when generated with the "-e" option
    can serve as your firewall on a system that doesn't even have Shorewall
    installed.

2)  You may now repeat the -q option to cause Shorewall to be extra quiet.

    Example:

	gateway:~ # shorewall -qq reload
	Shorewall configuration compiled to /var/lib/shorewall/.reload
	Restoring Shorewall...
	Shorewall restored from /var/lib/shorewall/.reload
	gateway:~ #