diff --git a/Shorewall-perl/releasenotes.txt b/Shorewall-perl/releasenotes.txt deleted file mode 100644 index 967e80d25..000000000 --- a/Shorewall-perl/releasenotes.txt +++ /dev/null @@ -1,278 +0,0 @@ ----------------------------------------------------------------------------- - 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. - -Shorewall-perl depends on Shorewall (3.4.2 or later). So if you want to use the -new compiler, you must install both Shorewall and Shorewall-perl. - -Even if you install Shorewall-perl, you have a choice of which compiler you use. -The choice is specified in the shorewall.conf file so you can select the -compiler to use on a system-by-system basis when running Shorewall Lite on -remote systems. - -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 only 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 (I know that it has been handy for me ;-) ) ----------------------------------------------------------------------------- - 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. - Compile-time extension scripts are executed using the Perl - 'eval `cat `' mechanism. Be sure that each script returns a - 'true' value; otherwise, the compiler will assume that the script - failed and will abort the compilation. - - When a script is invoked, the $chainref scalar variable will hold a - reference to a chain table entry. - - $chainref->{name} contains the name of the chain - $chainref->{table} holds the table name - - To add a rule to the chain: - - add_rule $chainref, - - Where - - is a scalar argument holding the rule text. Do not - include "-A " - - Example: - - add_rule $chainref, '-j ACCEPT'; - - To insert a rule into the chain: - - insert_rule $chainref, , - - The log_rule_limit function works like it does in the shell - compiler with two exceptions: - - - You pass the chain reference rather than the name of the - chain. - - The commands are 'add' and 'insert' rather than '-A' and - '-I'. - - There is only a single "pass as-is to iptables" argument - (so you must quote that part). - - Example: - - log_rule_limit - 'info' , - $chainref , - $chainref->{name}, - 'DROP' , - '', #Limit - '' , #Log tag - 'add'; - -f) The 'refresh' command is now synonymous with 'restart'. - -g) The 'maclog' extension script will need to be changed to write its - iptables commands to file descriptor 3 in iptables-restore format - rather than running those commands. - - maclog - - You can use this syntax: - - echo -A $CHAIN >&3 - - Example: - - echo -A $CHAIN -p icmp -j RETURN >&3 - - You may not insert a rule into the chain -- you may only add rules. - - Some run-time scripts are simply eliminated because they no longer - make any sense under Shorewall-perl: - - initdone - The these two scripts assumed a model where the - continue chains were built in parallel. In the - iptables-restore model, chains are built serially - within tables and tables are build serially. - - refresh - The 'refresh' command is the same as 'restart' - 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:]
[,...] - [all:][:
[,...]] - $FW[:
[,...]] - - The DEST column may be one of the following: - [all:]
[,...] - [all:][:
[,...]] - - 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 ----------------------------------------------------------------------------- -In addition to Shorewall-3.4.2 or later, you need: - -- Perl (I use Perl 5.8.8 but other versions should work fine) -- Perl Cwd Module -- Perl File::Basename Module -- Perl File::Temp Module ----------------------------------------------------------------------------- - I N S T A L L A T I O N ----------------------------------------------------------------------------- -Either - - $ tar -jxf shorewall-perl-3.9.1.tar.bz2 - $ cd shorewall-perl-3.9.1 - $ ./install.sh - -or - - $ rpm -ivh shoreawll-pl-3.9.1-1.noarch.rpm ----------------------------------------------------------------------------- - U S I N G T H E N E W C O M P I L E R ----------------------------------------------------------------------------- -By default, the old Bourne-shell based compiler will be used. - -To use the new compiler, add this to shorewall.conf: - - SHOREWALL_COMPILER=perl - -If you add this setting 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. - -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 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. -