Fix release notes

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@5880 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb

Shorewall-common/releasenotes.txt

@@ -1,9 +1,9 @@
 Shorewall 3.9.1
-
+----------------------------------------------------------------------------
-Release Highlights
+                   R E L E A S E  H I G H L I G H T S
-
+----------------------------------------------------------------------------
 1) This is the first Shorewall release that fully integrates the new
-   Shorewall-perl compiler.
+   Shorewall-perl compiler. See the "New Features" section below.
 
 2) You are now offered a choice as to which compiler(s) you install. In
    3.9.1, there are the following packages:
@@ -55,5 +55,202 @@ Migration Considerations:
     the tarball in the expected way; untar the package, and run the
     install.sh script.
 
-New Features in Shorewall 3.9:
+----------------------------------------------------------------------------
+                         N E W  F E A T U R E S
+----------------------------------------------------------------------------
+                          Shorewall-perl 3.9.1
+----------------------------------------------------------------------------
+This companion product to Shorewall 3.4.2 and later includes a complete
+rewrite of the compiler in Perl.
+
+I decided to make Shorewall-perl a separate product for several reasons:
+
+a) Embedded applications are unlikely to adopt Shorewall-perl; even Mini-Perl
+has a substantial disk and Ram footprint.
+
+b) Because of the gross incompatibilities between the new compiler and the
+old (see below), migration to the new compiler must be voluntary.
+
+c) By allowing Shorewall-perl to co-exist with the current Shorewall stable
+release (3.4), I'm hoping that the new compiler will get more testing and
+validation than it would if I were to package it with a new development
+version of Shorewall itself.
+
+d) Along the same vein, I think that users will be more likely to experiment
+with the new compiler if they can easily fall back to the old one if things
+get sticky.
+----------------------------------------------------------------------------
+                  T H E   G O O D   N E W S:
+----------------------------------------------------------------------------
+a) The compiler has a small disk footprint.
+b) The compiler is very fast.
+c) The compiler generates a firewall script that uses iptables-restore;
+   so the script is very fast.
+d) Use of the perl compiler is optional! The old slow clunky
+   Bourne-shell compiler is still available.
+----------------------------------------------------------------------------
+		  T H E   B A D   N E W S:
+----------------------------------------------------------------------------
+There are a number of incompatibilities between the Perl-based compiler
+and the Bourne-shell one. Some of these will probably go away by first
+official release but most will not.
+
+a) The Perl-based compiler requires the following capabilities in your
+   kernel and iptables.
+
+   - addrtype match (may be relaxed later)
+   - multiport match (will not be relaxed)
+
+   These capabilities are in current distributions.
+
+b) Now that Netfilter has features to deal reasonably with port lists,
+   I see no reason to duplicate those features in Shorewall. The
+   Bourne-shell compiler goes to great pain (in some cases) to
+   break very long port lists ( > 15 where port ranges in lists count
+   as two ports) into individual rules. In the new compiler, I'm
+   avoiding the ugliness required to do that. The new compiler just
+   generates an error if your list is too long. It will also produce
+   an error if you insert a port range into a port list and you don't
+   have extended multiport support.
+
+c) BRIDGING=Yes is not supported. The kernel code necessary to
+   support this option was removed in Linux kernel 2.6.20.
+
+d) The BROADCAST column in the interfaces file is essentially unused;
+   if you enter anything in this column but '-' or 'detect', you will
+   receive a warning. This will be relaxed if and when the addrtype
+   match requirement is relaxed.
+
+e) Because the compiler is now written in Perl, your compile-time
+   extension scripts from earlier versions will no longer work. For
+   now, if you want to use extension scripts, you will need to read the
+   Perl code to see how the compiler operates internally. I will
+   produce documentation before the first official release.
+   Compile-time extension scripts are executed using the Perl
+   'do FILE' mechanism.
+
+f) The 'refresh' command is now synonymous with 'restart'.
+
+g) Some run-time extension scripts are no longer supported because they
+   make no sense (iptables-restore instantiates the new configuration
+   atomically).
+
+	continue
+	initdone
+	continue
+	refresh
+	refreshed
+
+h) The /etc/shorewall/tos file now has zone-independent SOURCE and DEST
+   columns as do all other files except the rules and policy files.
+
+   The SOURCE column may be one of the following:
+
+       [all:]<address>[,...]
+       [all:]<interface>[:<address>[,...]]
+       $FW[:<address>[,...]]
+
+   The DEST column may be one of the following:
+       [all:]<address>[,...]
+       [all:]<interface>[:<address>[,...]]
+
+   This is a permanent change. The old zone-based rules have never
+   worked right and this is a good time to replace them. I've tried to
+   make the new syntax cover the most common cases without requiring
+   change to existing files. In particular, it will handle the tos file
+   released with Shorewall 1.4 and earlier.
+
+i) Currently, support for ipsets is untested. That will change with
+   future pre-releases but one thing is certain -- Shorewall is now out
+   of the ipset load/reload business. With scripts generated by the
+   Perl-based Compiler, the Netfilter ruleset is never cleared. That
+   means that there is no opportunity for Shorewall to load/reload your
+   ipsets since that cannot be done while there are any current rules
+   using ipsets.
+
+   So:
+	i)   Your ipsets must be loaded before Shorewall starts. You
+	     are free to try to do that with the following code in
+	     /etc/shorewall/start:
+
+	     if [ "$COMMAND" = start ]; then
+		ipset -U :all: :all:
+		ipset -F
+		ipset -X
+		ipset -R < /my/ipset/contents
+	     fi
+
+	     The file '/my/ipset/contents' (not its real name of
+	     course) will normally be produced using the ipset -S
+	     command.
+
+	     The above will work most of the time but will fail in a
+	     'shorewall stop' - 'shorewall start' sequence if you
+	     use ipsets in your routestopped file (see below).
+
+	ii)  Your ipsets may not be reloaded until Shorewall is stopped or
+	     cleared.
+
+	iii) If you specify ipsets in your routestopped file then
+	     Shorewall must be cleared in order to reload your ipsets.
+
+   As a consequence, scripts generated by the Perl-based compiler will
+   ignore /etc/shorewall/ipsets and will issue a warning if you set
+   SAVE_IPSETS=Yes in shorewall.conf.
+
+j) Because the configuration files (with the exception of
+   /etc/shorewall/params) are now processed by the Perl-based compiler
+   rather than by the shell, only the basic forms of Shell expansion
+   ($variable and ${variable}) are supported. The more exotic forms
+   such as ${variable:=default} are not supported. Both variables
+   defined in /etc/shorewall/params and environmental variables
+   (exported by the shell) can be used in configuration files.
+
+h) USE_ACTIONS=No is not supported. That option is intended to minimize
+   Shorewall's footprint in embedded applications. As a consequence,
+   Default Macros are not supported.
+
+i) DELAYBLACKLISTLOAD=Yes is not supported. The entire ruleset is
+   atomically loaded with one execution of iptables-restore.
+
+j) MAPOLDACTIONS=Yes is not supported. People should have converted to
+   using macros by now.
+
+k) The pre Shorewall-3.0 format of the zones file is not supported;
+   neither is the /etc/shorewall/ipsec file.
+----------------------------------------------------------------------------
+                      P R E R E Q U I S I T E S
+----------------------------------------------------------------------------
+- Perl (I use Perl 5.8.8 but other versions should work fine)
+- Perl Cwd Module
+- Perl File::Basename Module
+- Perl File::Temp Module
+----------------------------------------------------------------------------
+               U S I N G   T H E   N E W   C O M P I L E R
+----------------------------------------------------------------------------
+If you only install one compiler, then that compiler will be used.
+
+If you install both compilers, then the compiler actually used depends
+on the SHOREWALL_COMPILER setting in shorewall.conf.
+
+The value of this new option can be either 'perl' or 'shell'.
+
+If you add 'SHOREWALL_COMPILER=shell' to /etc/shorewall/shorewall.conf
+then by default, the new compiler will be used on the system. If you
+add it to shorewall.conf in a separate directory (such as a
+Shorewall-lite export directory) then the new compiler will only be
+used when you compile from that directory.
+
+If you only install one compiler, it is suggested that you do not set
+SHOREWALL_COMPILER.
+
+Regardless of the setting of SHOREWALL_COMPILER, there is one change in
+Shorewall operation that is triggered simply by installing
+shorewall-perl. Your params file will be processed during compilation 
+with the shell's '-a' option  which causes any variables that you set
+or create in that file to be automatically exported. Since the params
+file is processed before shorewall.conf, using -a insures that the
+settings of your params variables are available to the new compiler
+should it's use be specified in shorewall.conf.
+
 

Shorewall-common/shorewall.conf

@@ -29,7 +29,7 @@ VERBOSITY=1
 #      (setting this to 'perl' requires installation of Shorewall-perl)
 ###############################################################################
 
-SHOREWALL_COMPILER=shell
+SHOREWALL_COMPILER=
 
 ###############################################################################
 #			       L O G G I N G

Shorewall-perl/releasenotes.txt

@@ -1,5 +1,9 @@
 ----------------------------------------------------------------------------
                      Shorewall-perl 3.9.1
+
+These release notes apply if you are installing Shorewall-perl under
+Shorewall 3.4.2 or later. If you are installing Shorewall 3.9.x, please
+see the release notes in the Shorewall package.
 ----------------------------------------------------------------------------
 This companion product to Shorewall 3.4.2 and later includes a complete
 rewrite of the compiler in Perl.