shorewall_code/Shorewall/releasenotes.txt

Shorewall 3.3.5

 Note to users upgrading from Shorewall 3.0 or 3.3

    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

    If you have a file named /etc/shorewall/modules, please remove
    it. The default modules file is now located in /usr/share/shorewall/
    (see the "Migration Considerations" below).

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

Problems Corrected in 3.3.5

1)  Previously, if the last 'balance' provider was removed from
    /etc/shorewall/providers then "shorewall restart" would not restore
    the default route that was in place prior to "shorewall start".

2)  Previously, restoration of routing was ignoring the "-n"
    option. Now such restoration only occurs if "-n" was not specified.

3)  Previously, a startup error resulted when white space was included
    in LOGFORMAT.

4)  Previously, the "shorewall[-lite] start" command would return a
    non-zero exit status if Shorewall [Lite] was already started. It
    now returns an indication of success.

Other Changes in 3.3.5.

1)  Shorewall no longer includes policy matches in its generated
    ruleset when no IPSEC zones or IPSEC networks are defined (IPSEC
    networks are defined using the 'ipsec' option in
    /etc/shorewall/hosts).

2)  From the beginning, the Shorewall configuration files in
    /etc/shorewall/ have contained documentary comments. While these
    comments are useful, they present an upgrade problem. Beginning
    with this release, these comments are removed from the
    configuration files themselves and are gathered together in a
    single file /etc/shorewall/Documentation. The documentation is in
    alphabetical order by file name.

3)  The "shorewall [re]load" command now supports a "-c" option.

    Example:

	shorewall reload -c gateway

    When -c is given, Shorewall will capture the capabilities of the
    remote system to a file named "capabilities" in the export
    directory before compiling the configuration.

    If the file "capabilities" does not currently exist in the 
    export directory then "-c" is automatically assumed.

4)  If 0 (zero) is specified for the IN-BANDWIDTH in
    /etc/shorewall/tcdevices then no ingress qdisc will be created for
    the device.

5)  The Makefile installed in /usr/share/shorewall/configfiles/ is now
    the same one mentioned at
    http://www.shorewall.net/CompiledPrograms.html.

    Once the file is copied into an export directory, you modify the
    setting of the HOST variable to match the name of the remote
    firewall.

    The default target is the "firewall" script so "make" compiles the
    firewall script if any of the configuration files have
    changed. "make install" builds "firewall" if necessary then
    installs it on the remote firewall. "make capabilities" will
    generate the "capabilities" file if that file doesn't exist. "make
    save" will save the running configuration on the remote firewall.

6)  Shorewall and Shorewall Lite now include the following manpages. 

	      shorewall-accounting(5)
	      shorewall-actions(5)
	      shorewall-blacklist(5)
	      shorewall.conf(5)
	      shorewall-hosts(5)
	      shorewall-interfaces(5)
	      shorewall-lite(8)
	      shorewall-maclist(5)
	      shorewall-masq(5)
	      shorewall-nat(5)
	      shorewall-netmap(5)
	      shorewall-params(5)
	      shorewall-policy(5)
	      shorewall-providers(5)
	      shorewall-proxyarp(5)
	      shorewall-route_rules(5)
	      shorewall-routestopped(5)
	      shorewall-rules(5)
	      shorewall-tcclasses(5)
	      shorewall-tcdevices(5)
	      shorewall-tcrules(5)
	      shorewall-template(5)
	      shorewall-tos(5)
	      shorewall-tunnels(5)
	      shorewall(8)
	      shorewall-zones(5)

Migration Considerations:

1)  Shorewall supports the notion of "default actions". A default
    action defines a set of rules that are applied before a policy is
    enforced. Default actions accomplish two goals:

    a) Relieve log congestion. Default actions typically include rules
       to silently drop or reject traffic that would otherwise be logged
       when the policy is enforced.

    b) Ensure correct operation. Default actions can also avoid common
       pitfalls like dropping connection requests on port TCP port
       113. If these connections are dropped (rather than rejected)
       then you may encounter problems connecting to internet services
       that utilize the AUTH protocol of client authentication.

    In prior Shorewall versions, default actions (action.Drop and
    action.Reject) were defined for DROP and REJECT policies in
    /usr/share/shorewall/actions.std. These could be overridden in
    /etc/shorewall/actions.

    This approach has two drawbacks:

    a) All DROP policies must use the same default action and all
       REJECT policies must use the same default action.

    b) Now that we have modularized action processing (see the New
       Features section below), we need a way to define default rules
       for a policy that does not involve actions.

    If you have not overridden the defaults using entries in
    /etc/shorewall/actions then you need make no changes to migrate to
    Shorewall version 3.3. Otherwise, please see item 3) in the New
    Features below.

2)  The 'Limit' action is now a builtin. If you have 'Limit' listed in
    /etc/shorewall/actions, remove the entry. Also remove the files
    /etc/shorewall/action.Limit and/or /etc/shorewall/Limit if you have
    them.

New Features:

1)  In order to accomodate small embedded applications, Shorewall 3.3
    is now modularized. In addition to the base files, there are
    loadable "libraries" that may be included or omitted from an
    embedded system as required.

    Loadable Shorewall libraries reside in /usr/share/shorewall/ and
    have names that begin with "lib.". The following libraries are
    included in Shorewall 3.3:

    - lib.accounting. Must be available if you include entries in
      /etc/shorewall/accounting.

    - lib.actions. Must be available if you do not specify
      USE_ACTIONS=No in /etc/shorewall/shorewall.conf.

    - lib.dynamiczones. Must be available if you specify
      DYNAMIC_ZONES=Yes in shorewall.conf.

    - lib.maclist. Must be available if you specify the 'maclist'
      option in /etc/shorewall/interfaces or /etc/shorewall/hosts.

    - lib.nat. Must be available if you have entries in
      /etc/shorewall/masq, /etc/shorewall/nat or /etc/shorewall/netmap
      or if you use DNAT or REDIRECT rules.

    - lib.providers. Must be available if you have entries in
      /etc/shorewall/providers.

    - lib.proxyarp. Must be available if you have entries in
      /etc/shorewall/proxyarp or if you specify the 'proxyarp' option
      in /etc/shorewall/interfaces.

    - lib.tc. Must be available if you have entries in
      /etc/shorewall/tcdevices and /etc/shorewall/tcclasses.

    - lib.tcrules. Must be available if you have entries in
      /etc/shorewall/tcrules.

    - lib.tunnels. Must be available if you have entries in
      /etc/shorewall/tunnels.

    Embedded applications can further decrease the size of the Shorewall
    footprint by:

    - Omitting the macro files.
    - Only including the 'modules' file appropriate for the kernel in
      use.
    - Omitting all unused extension scripts.
    - Stripping the comments (except for copyright) from the various
      files.

2)  As hinted in the previous bullet, there is a new USE_ACTIONS option
    in /etc/shorewall/shorewall.conf. Shorewall actions can be very
    powerful but they also require a lot of code to implement. Embedded
    applications can omit that code by setting
    USE_ACTIONS=No. Shorewall will ignore all action-related files
    including /usr/share/shorewall/actions.std and
    /etc/shorewall/actions. Builtin actions will still be available for
    use in rules and macros.

    The 'Limit' action has been converted to a builtin so that Limit is
    available even when USE_ACTIONS=No.

    See the next item for more information.

3)  Prior to Shorewall 3.3, default actions were specified in
    /usr/share/shorewall/actions.std or in /etc/shorewall/actions.

    This approach has two drawbacks:

    a) All DROP policies must use the same default action and all
       REJECT policies must use the same default action.

    b) Now that we have modularized action processing (see the New
       Features section below), we need a way to define default rules
       for a policy that does not involve actions.

    The solution is two-fold:

    - Four new options have been added to the
      /etc/shorewall/shorewall.conf file that allow specifying the
       default action for DROP, REJECT, ACCEPT and QUEUE.

       The options are DROP_DEFAULT, REJECT_DEFAULT, ACCEPT_DEFAULT and
       QUEUE_DEFAULT.

       DROP_DEFAULT describes the rules to be applied before a
       connection request is dropped by a DROP policy; REJECT_DEFAULT
       describes the rules to be applied if a connection request is
       rejected by a REJECT policy. The other two are similar for
       ACCEPT and QUEUE policies.

       The value assigned to these may be:

       	a) The name of an action.
	b) The name of a macro
	c) 'None' or 'none'

       The default values are:

	DROP_DEFAULT="Drop"
	REJECT_DEFAULT="Reject"
	ACCEPT_DEFAULT=none
	QUEUE_DEFAULT=none

       If USE_ACTIONS=Yes, then these values refer to action.Drop and
       action.Reject respectively. If USE_ACTIONS=No, then these values
       refer to macro.Drop and macro.Reject.

       If you set the value of either option to "None" then no default
       action will be used and the default action or macro must be
       specified in /etc/shorewall/policy

    - The POLICY column in /etc/shorewall/policy has been extended.

       In /etc/shorewall/policy, when the POLICY is DROP, REJECT,
       ACCEPT or QUEUE then the policy may be followed by ":" and one
       of the following:

	a) The word "None" or "none". This causes any default
	   action defined in /etc/shorewall/shorewall.conf
	   to be omitted for this policy.
	b) The name of an action (requires that USE_ACTIONS=Yes
	   in shorewall.conf). That action will be invoked
	   before the policy is enforced.
	c) The name of a macro. The rules in that macro will
	   be applied before the policy is enforced. This
	   does not require USE_ACTIONS=Yes.

    Example:

	#SOURCE		DEST		POLICY		LOG
	#						LEVEL
	loc		net		ACCEPT
	net		all		DROP:MyDrop	info
	#
	# THE FOLLOWING POLICY MUST BE LAST
	#
	all		all		REJECT:MyReject	info

4)  For users whose kernel and iptables have Extended MARK Target
    support, it is now possible to logically AND or OR a value into the
    current packet mark by preceding the mark value (and optional mask)
    with an ampersand ("&") or vertical bar ("|") respectively.

    Example: To logically OR the value 4 into the mark value for
    packets from 192.168.1.1:

    #MARK   SOURCE
    |4	    192.168.1.1

5)  Previously, zone names were restricted to five characters in
    length. That length derives from the --log-prefix in Netfilter log
    messages which must be 29 bytes or less in length. With the
    standard Shorewall LOGFORMAT, that leaves 11 characters for the
    chain name; given that many chain names are of the form
    <zone1>2<zone2>, that gives a maximum zone name length of 11.

    Beginning with this release, the maximum length of a zone name is
    dependent on the LOGFORMAT (the maximum length may never be less
    than 5 but it may be greater than 5). For example, setting
    LOGFORMAT="FW:%s:%s:" will allow zone names of up to 8 characters.

6)  Netfilter provides support for attaching comments to Netfilter
    rules. Comments can be up to 255 bytes in length and are
    visible using the "shorewall show <chain>", "shorewall show nat",
    "shorewall show mangle" and "shorewall dump" commands. Comments are
    delimited by '/* ... */" in the output.

    Beginning with Shorewall 3.3.3, you may place COMMENT lines in the
    /etc/shorewall/rules, /etc/shorewall/tcrules, /etc/shorewall/nat
    and /etc/shorewall/masq files and in action files. The remainder of
    the line is treated as a comment and it will be attached as a
    Netfilter comment to the rule(s) generated by the following entries
    in the file.

    Note: Do not prefix the comment with "#". Shorewall's two-pass
    compiler strips off "#" comments in the first pass and processes
    COMMENT lines in the second pass. So by the time that COMMENT is
    processed, the "#" and everything after it has been removed (see
    example below).

    To stop the current comment from being attached to further
    rules, simply include COMMENT on a line by itself (so that the
    following rules will have no comment) or specify a new COMMENT.

    If you do not have Comment support in your iptables/kernel (see the
    output of "shorewall[-lite] show capabilities") then COMMENTS are
    ignored with this warning:

     COMMENT ignored --  requires comment support in iptables/Netfilter

    Example from my rules file:

	    #SOURCE      SOURCE     DEST       PROTO DEST PORT(S)

	    COMMENT Stop Microsoft Noise

	    REJECT       loc        net        tcp   137,445
	    REJECT       loc        net        udp   137:139

	    COMMENT  # Stop comment from being attached to rules below

    The output of "shorewall show loc2net" includes (folded):

    0     0 reject     tcp  --  *      *       0.0.0.0/0
	  0.0.0.0/0    multiport dports 137,445 /* Stop Microsoft Noise */
    0     0 reject     udp  --  *      *       0.0.0.0/0
	  0.0.0.0/0    udp dpts:137:139 /* Stop Microsoft Noise */

7)  A new macro (macro.RDP) has been added for Microsoft Remote
    Desktop. This macro was contributed by Tuomo Soini.

8)  A new 'maclog' extension file has been added. This file is
    processed just before logging based on the setting of
    MACLIST_LOG_LEVEL is done. When invoked, the CHAIN variable will
    contain the name of the chain where rules should be inserted.
    Remember that if you have specified MACLIST_TABLE=mangle, then your
    run_iptables commands should include "-t mangle".

9)  The SUBNET column in /etc/shorewall/masq has been renamed SOURCE to
    more accurately describe the contents of the column.

10) Previously, it was not possible to use exclusion in
    /etc/shorewall/hosts. Beginning with this release, you may now use
    exclusion lists in entries in this file. Exclusion lists are
    discussed at:

       http://www.shorewall.net/configuration_file_basics.htm#Exclusion.

    Example:

	loc	eth0:192.168.1.0/24!192.168.1.4,192.168.1.16/28

    In that example, the 'loc' zone is defined to be the subnet
    192.168.1.0/24 interfacing via eth0 *except* for host 192.168.1.4
    and hosts in the sub-network 192.168.1.16/28.

11) New "shorewall[-lite] show ip" and "shorewall[-lite] show routing"
    commands have been added. The first produces the same output as "ip
    addr ls". The second produces a report about your routing rules and
    tables.

12) Beginning with this release, Shorewall and Shorewall Lite will
    share common change logs and release notes.

13) In Shorewall versions prior to 3.3.2, multiple jumps to a '2all'
    chain could be generated in succession.

    Example from an earlier shorewall version:

    gateway:~ # shorewall-lite show eth2_fwd
    Shorewall Lite 3.3.2 Chains eth2_fwd at gateway - Thu Oct 19 08:54:37 PDT 2006

    Counters reset Thu Oct 19 08:34:47 PDT 2006

    Chain eth2_fwd (1 references)
     pkts bytes target     prot opt in     out     source            destination
        0     0 dynamic    all  --  *      *       0.0.0.0/0            0.0.0.0/0           state INVALID,NEW
        0     0 wifi2all   all  --  *      eth0    0.0.0.0/0            0.0.0.0/0           policy match dir out pol none
        0     0 wifi2all   all  --  *      br0     0.0.0.0/0            0.0.0.0/0           policy match dir out pol none
        0     0 wifi2all   all  --  *      eth3    0.0.0.0/0            0.0.0.0/0           policy match dir out pol none
        0     0 wifi2all   all  --  *      tun+    0.0.0.0/0            0.0.0.0/0           policy match dir out pol none
    gateway:~ #

    This redundancy may be eliminated by setting OPTIMIZE=1 in shorewall.conf.

    gateway:~ # shorewall-lite show eth2_fwd
    Shorewall Lite 3.3.3 Chains eth2_fwd at gateway - Thu Oct 19 09:15:24 PDT 2006

    Counters reset Thu Oct 19 09:15:19 PDT 2006

    Chain eth2_fwd (1 references)
     pkts bytes target     prot opt in     out     source               destination
        0     0 dynamic    all  --  *      *       0.0.0.0/0            0.0.0.0/0           state INVALID,NEW
        0     0 wifi2all   all  --  *      *       0.0.0.0/0            0.0.0.0/0
    gateway:~ #

    Note that with OPTIMIZE=1, traffic destined for an
    interface/Address that falls outside of all defined zones may now
    be logged out of a '2all' chain rather than out of the FORWARD
    chain.

    The OPTIMIZE setting also controls the suppression of redundant
    wildcard rules (those specifying "all" in the SOURCE or DEST
    column). A wildcard rule is considered to be redundant when it
    has the same ACTION and Log Level as the applicable policy.

    Example:

	/etc/shorewall/policy

	#SOURCE		DEST		POLICY		LEVEL
	loc		net		ACCEPT

        /etc/shorewall/rules

	#ACTION		SOURCE		DEST	PROTO	DEST
	#						PORT(S)
	...
	ACCEPT		all		all	icmp	8

    OPTIMIZE=0

    gateway:~ # shorewall show loc2net
    Shorewall Lite 3.3.3 Chains loc2net at gateway - Thu Oct 26 07:55:03 PDT 2006

    Counters reset Thu Oct 26 07:54:58 PDT 2006

    Chain loc2net (1 references)
     pkts bytes target     prot opt in     out     source               destination
      ...
        0     0 DROP       all  --  *      *      !192.168.0.0/22       0.0.0.0/0
        0     0 ACCEPT     icmp --  *      *       0.0.0.0/0            0.0.0.0/0           icmp type 8
        0     0 ACCEPT     all  --  *      *       0.0.0.0/0            0.0.0.0/0

    gateway:~

    OPTIMIZE=1

    gateway:~ # shorewall show loc2net
    Shorewall Lite 3.3.3 Chains loc2net at gateway - Thu Oct 26 07:57:12 PDT 2006

    Counters reset Thu Oct 26 07:56:38 PDT 2006

    Chain loc2net (1 references)
     pkts bytes target     prot opt in     out     source               destination
      ...
        0     0 DROP       all  --  *      *      !192.168.0.0/22       0.0.0.0/0
        0     0 ACCEPT     all  --  *      *       0.0.0.0/0            0.0.0.0/0

    gateway:~

    If you really want a rule that duplicates the policy, follow the
    action with "!":

	#ACTION		SOURCE		DEST	PROTO	DEST
	#						PORT(S)
	...
	ACCEPT!		all		all	icmp	8

14) IP Address ranges are now allowed in the drop, reject, allow and
    logdrop shorewall[-lite] commands.

15) The lib.cli library has been added. It is distributed with
    both Shorewall and Shorewall Lite and contains the
    command-processing code that is common to both /sbin/shorewall and
    /sbin/shorewall-lite.

16) Previously, Shorewall has not attempted to undo the changes it has
    made to the firewall's routing as a result of entries in
    /etc/shorewall/providers and /etc/shorewall/routes. Beginning with
    this release, Shorewall will attempt to undo these changes.

    When Shorewall starts or is restarted and there are entries in
    /etc/shorewall/providers, Shorewall will capture the contents
    of /etc/shorewall/rt_tables and will restore that database when
    Shorewall is stopped or restarted. Similarly, the default route
    will be captured the first time that you [re]start Shorewall using
    this version and will be restored under the following conditions:

    a) shorewall stop
    b) shorewall clear
    c) shorewall restart or restore and there are no entries in
       /etc/shorewall/providers.

    Once the default route has been restored, Shorewall will delete
    the saved copy so that it will once again be captured at the next
    shorewall start or shorewall restore.