shorewall_code/Shorewall/releasenotes.txt

Shorewall 3.1.2

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

1) If /etc/shorewall/ipsets exists, it is processed during [re]start but not
   during 'shorewall restore'.

Migration Considerations:

None.

New Features:

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

	shorewall [ -q ] [ -e ] generate [ <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.
	<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 [ -q ] [ -e ] compile [ <config directory> ] <script file>

    WARNING: The generated script HAS ABSOLUTELY NO ERROR CHECKING so if there
             are errors in your configuration files that result in errors when
             the script is run then you may not be able to access your firewall
             or your firewall may have security holes.

    Given the above warning, I recommend that you use 'generate' when making
    simple changes to your configuration but that you continue to use 'restart'
    for complex changes.

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

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:~ #