Shorewall 2.x

Tom Eastep

The information on this site applies only to 2.x releases of Shorewall. For older versions:

The current 2.2 Stable Release is 2.2.0 -- Here are the release notes and here are the known problems and updates.

End of support life for Shorewall 1.4 -- Upgrading to Shorewall 2.2

Copyright © 2001-2005 Thomas M. Eastep

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.

2005-02-05

Table of Contents

Introduction to Shorewall

Glossary
What is Shorewall?
Getting Started with Shorewall
Looking for Information?
Running Shorewall on Mandrake® with a two-interface setup?
License

News

Shorewall 2.0.16
Shorewall 2.2.0

Leaf

OpenWRT

Donations

Introduction to Shorewall

Glossary

What is Shorewall?

The Shoreline Firewall, more commonly known as "Shorewall", is a high-level tool for configuring Netfilter. You describe your firewall/gateway requirements using entries in a set of configuration files. Shorewall reads those configuration files and with the help of the iptables utility, Shorewall configures Netfilter to match your requirements. Shorewall can be used on a dedicated firewall system, a multi-function gateway/router/server or on a standalone GNU/Linux system. Shorewall does not use Netfilter's ipchains compatibility mode and can thus take advantage of Netfilter's connection state tracking capabilities.

Shorewall is not a daemon. Once Shorewall has configured Netfilter, it's job is complete. After that, there is no Shorewall code running although the /sbin/shorewall program can be used at any time to monitor the Netfilter firewall.

Getting Started with Shorewall

New to Shorewall? Start by selecting the QuickStart Guide that most closely matches your environment and follow the step by step instructions.

Looking for Information?

The Documentation Index is a good place to start as is the Quick Search in the frame above.

Running Shorewall on Mandrake® with a two-interface setup?

If so, the documentation on this site will not apply directly to your setup. If you want to use the documentation that you find here, you will want to consider uninstalling what you have and installing a setup that matches the documentation on this site. See the Two-interface QuickStart Guide for details.

Update: I've been informed by Mandrake Development that this problem has been corrected in Mandrake 10.0 Final (the problem still exists in the 10.0 Community release).

License

This program is free software; you can redistribute it and/or modify it under the terms of Version 2 of the GNU General Public License as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more detail.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

News

02/01/2005 Shorewall 2.0.16

This release back-ports the DROPINVALID shorewall.conf option from 2.2.0.
  1. Recent 2.6 kernels include code that evaluates TCP packets based on TCP Window analysis. This can cause packets that were previously classified as NEW or ESTABLISHED to be classified as INVALID.

    The new kernel code can be disabled by including this command in your /etc/shorewall/init file:

    echo 1 > /proc/sys/net/ipv4/netfilter/ip_conntrack_tcp_be_liberal

    Additional kernel logging about INVALID TCP packets may be obtained by adding this command to /etc/shorewall/init:

    echo 1 > /proc/sys/net/ipv4/netfilter/ip_conntrack_log_invalid

    Traditionally, Shorewall has dropped INVALID TCP packets early. The new DROPINVALID option allows INVALID packets to be passed through the normal rules chains by setting DROPINVALID=No.

    If not specified or if specified as empty (e.g., DROPINVALID="") then DROPINVALID=Yes is assumed.
02/01/2005 Shorewall 2.2.0

New Features:
  1. ICMP packets that are in the INVALID state are now dropped by the Reject and Drop default actions. They do so using the new 'dropInvalid' builtin action. An 'allowInvalid' builtin action is also provided which accepts packets in that state.
  2. The /etc/shorewall/masq file INTERFACE column now allows additional options.

    Normally MASQUERADE/SNAT rules are evaluated after one-to-one NAT rules defined in the /etc/shorewall/nat file. If you preceed the interface name with a plus sign ("+") then the rule will be evaluated before one-to-one NAT.

    Examples:

    +eth0
    +eth1:192.0.2.32/27

    Also, the effect of ADD_SNAT_ALIASES=Yes can be negated for an entry by following the interface name by ":" but no digit.

    Examples:

    eth0:
    eth1::192.0.2.32/27
    +eth3:

  3. Similar to 2), the /etc/shorewall/nat file INTERFACE column now allows you to override the setting of ADD_IP_ALIASES=Yes by following the interface name with ":" but no digit.
  4. All configuration files in the Shorewall distribution with the exception of shorewall.conf are now empty. In particular, the /etc/shorewall/zones, /etc/shorewall/policy and /etc/shorewall/tos files now have no active entries. Hopefully this will stop the questions on the support and development lists regarding why the default entries are the way they are.
  5. Previously, including a log level (and optionally a log tag) on a rule that specified a user-defined (or Shorewall-defined) action would log all traffic passed to the action. Beginning with this release, specifying a log level in a rule that specifies a user- or Shorewall-defined action will cause each rule in the action to be logged with the specified level (and tag).

    The extent to which logging of action rules occurs is goverend by the following:
This change has an effect on extension scripts used with user-defined actions. If you define an action 'acton' and you have an /etc/shorewall/acton script then when that script is invoked, the following three variables will be set for use by the script:

$CHAIN = the name of the chain where your rules are to be placed. When logging is used on an action invocation, Shorewall creates a chain with a slightly different name from the action itself.
$LEVEL = Log level. If empty, no logging was specified.
$TAG   = Log Tag.

Example:

/etc/shorewall/rules:
   
acton:info:test

Your /etc/shorewall/acton file will be run with:

$CHAIN="%acton1
$LEVEL="info"
$TAG="test"

  1. The /etc/shorewall/startup_disabled file is no longer created when Shorewall is first installed. Rather, the variable STARTUP_ENABLED is set to 'No' in /etc/shorewall/shorewall.conf. In order to get Shorewall to start, that variable's value must be set to 'Yes'. This change accomplishes two things:
  2. Support has been added for the 2.6 Kernel IPSEC implementation. To use this support, you must have installed the IPSEC policy match patch and the four IPSEC/Netfilter patches from Patch-0-Matic-ng. The policy match patch affects both your kernel and iptables. There are two ways to specify that IPSEC is to be used when communicating with a set of hosts; both methods involve the new /etc/shorewall/ipsec file:
    1. If encrypted communication is used with all hosts in a zone, then you can designate the zone as an "ipsec" zone by placing 'Yes" in the IPSEC ONLY column in /etc/shorewall/ipsec:

      #ZONE        IPSEC    OPTIONS ...
      #            ONLY
      vpn          Yes

      The hosts in the zone (if any) must be specified in /etc/shorewall/hosts but you do not need to specify the 'ipsec' option on the entries in that file (see below). Dynamic zones involving IPSEC must use that technique.

      Example:Under 2.4 Kernel FreeS/Wan:

      /etc/shorewall/zones:

      net    Net    The big bad Internet
      vpn    VPN    Remote Network

      /etc/shorewall/interfaces:

      net    eth0    ...
      vpn    ipsec0    ...

      Under 2.6 Kernel with this new support:

      /etc/shorewall/zones:

      net    Net    The big bad Internet
      vpn    VPN    Remote Network

      /etc/shorewall/interfaces:

      net    eth0    ...

      /etc/shorewall/hosts:

      vpn    eth0:0.0.0.0/0

      /etc/shorewall/ipsec

      vpn    Yes
    2. If only part of the hosts in a zone require encrypted communication, you may use of the new 'ipsec' option in /etc/shorewall/hosts to designate those hosts.

      Example:

      Under 2.4 Kernel FreeS/Wan:

      /etc/shorewall/zones:
      net    Net    The big bad Internet
      loc    Local  Extended local zone
      /etc/shorewall/interfaces:

      net    eth0    ...
      loc    eth1    ...
      loc    ipsec0    ...

      Under 2.6 Kernel with this new support:

      /etc/shorewall/zones:

      net        Net    The big bad Internet
      vpn        VPN    Remote Network

      /etc/shorewall/interfaces:

      net    eth0    ...
      loc    eth1    ...

      /etc/shorewall/hosts:

      vpn    eth0:0.0.0.0/0    ipsec,...
Regardless of which technique you choose, you can specify additional SA options for the zone in the /etc/shorewall/ipsec entry.

The OPTIONS, IN OPTIONS and OUT OPTIONS columns specify the input-output, input and output characteristics of the security associations to be used to decrypt (input) or encrypt (output) traffic to/from the zone.

The available options are:
Examples:

#ZONE    IPSEC  OPTIONS                  IN          OUT
#        ONLY                            OPTIONS     OPTIONS
vpn      Yes    mode=tunnel,proto=esp    spi=1000    spi=1001
loc      No     reqid=44,mode=transport

The /etc/shorewall/masq file has a new IPSEC column added. If you specify Yes or yes in that column then the unencrypted packets will have their source address changed. Otherwise, the unencrypted packets will not have their source addresses changed. This column may also contain a comma-separated list of the options specified above in which case only those packets that will be encrypted by an SA matching the given options will have their source address changed.
  1. To improve interoperability, tunnels of type 'ipsec' no longer enforce the use of source port 500 for ISAKMP and OpenVPN tunnels no longer enforce use of the specified port as both the source and destination ports.
  2. A new 'allowBcast' builtin action has been added -- it silently allows broadcasts and multicasts.
  3. The -c option in /sbin/shorewall commands is now deprecated. The commands where -c was previously allowed now permit you to specify a configuration directory after the command:

          shorewall check   [ <configuration-directory> ]
          shorewall restart [ <configuration-directory> ]
          shorewall start   [ <configuration-directory> ]

  4. Normally, when SNAT or MASQUERADE is applied to a tcp or udp connection, Netfilter attempts to retain the source port number. If it has to change to port number to avoid  <source address>,<source port> conflicts, it tries to do so within port ranges ( < 512, 512-1023, and > 1023). You may now specify an explicit range of source ports to be used by following the address or address range (if any) in the ADDRESS column with ":" and a port range in the format <low-port>-<high-port>. You must specify either "tcp" or "udp" in the PROTO column.

    Examples 1 -- MASQUERADE with tcp source ports 4000-5000:

        #INTERFACE SUBNET          ADDRESS        PROTO
        eth0       192.168.1.0/24  :4000-5000     tcp

    Example 2 -- SNAT with udp source ports 7000-8000:

        #INTERFACE SUBNET          ADDRESS                 PROTO
       eth0       10.0.0.0/8      192.0.2.44:7000-8000    udp

  5. You may now account by user/group ID for outbound traffic from the firewall itself with entries in /etc/shorewall/accounting. Such accounting rules must be placed in the OUTPUT chain. See the comments at the top of /etc/shorewall/accounting for details.
  6. Shorewall now verifies that your kernel and iptables have physdev match support if BRIDGING=Yes in shorewall.conf.
  7. Beginning with this release, if your kernel and iptables have iprange match support (see the output from "shorewall check"), then with the exception of the /etc/shorewall/netmap file, anywhere that a network address may appear an IP address range of the form <low address>-<high address> may also appear.
  8. Support has been added for the iptables CLASSIFY target. That target allows you to classify packets for traffic shaping directly rather than indirectly through fwmark. Simply enter the <major>:<minor> classification in the first column of /etc/shorewall/tcrules:

    Example:

    #MARK/      SOURCE       DEST      PROTO     PORT(S)
    #CLASSIFY
    1:30        -            eth0      tcp       25

    Note that when using this form of rule, it is acceptable to include the name of an interface in the DEST column.

    Marking using the CLASSIFY target always occurs in the POSTROUTING chain of the mangle table and is not affected by the setting of MARK_IN_FORWARD_CHAIN in shorewall.conf.
  9. During "shorewall start", IP addresses to be added as a consequence of ADD_IP_ALIASES=Yes and ADD_SNAT_ALIASES=Yes are quietly deleted when /etc/shorewall/nat and /etc/shorewall/masq are processed then they are re-added later. This is done to help ensure that the addresses can be added with the specified labels but can have the undesirable side effect of causing routes to be quietly deleted. A new RETAIN_ALIASES option has been added to shorewall.conf; when this option is set to Yes, existing addresses will not be deleted. Regardless of the setting of RETAIN_ALIASES, addresses added during "shorewall start" are still deleted at a subsequent "shorewall stop" or "shorewall restart".
  10. Users with a large black list (from /etc/shorewall/blacklist) may want to set the new DELAYBLACKLISTLOAD option in shorewall.conf. When DELAYBLACKLISTLOAD=Yes, Shorewall will enable new connections before loading the blacklist rules. While this may allow connections from blacklisted hosts to slip by during construction of the blacklist, it can substantially reduce the time that all new connections are disabled during "shorewall [re]start".
  11. Using the default LOGFORMAT, chain names longer than 11 characters (such as in user-defined actions) may result in log prefix truncation. A new shorewall.conf action  LOGTAGONLY has been added to deal with this problem. When LOGTAGONLY=Yes, logging rules that specify a log tag will substitute the tag for the chain name in the log prefix.

    Example -- file /etc/shorewall/action.thisisaverylogactionname:

        Rule:

             DROP:info:ftp    0.0.0.0/0    0.0.0.0/0    tcp        21
       
        Log prefix with LOGTAGONLY=No:

             Shorewall:thisisaverylongacti

        Log prefix with LOGTAGONLY=Yes:

             Shorewall:ftp:DROP

  12. Shorewall now resets the 'accept_source_route' flag for all interfaces. If you wish to accept source routing on an interface, you must specify the new 'sourceroute' interface option in /etc/shorewall/interfaces.
  13. The default Drop and Reject actions now invoke the new standard action 'AllowICMPs'. This new action accepts critical ICMP types:
       
        Type 3 code 4 (fragmentation needed)
        Type 11       (TTL exceeded)

  14. Explicit control over the kernel's Martian logging is now provided using the new 'logmartians' interface option. If you include 'logmartians' in the interface option list then logging of Martian packets on will be enabled on the specified interface. If you wish to globally enable martian logging, you can set LOG_MARTIANS=Yes in shorewall.conf.
  15. You may now cause Shorewall to use the '--set-mss' option of the TCPMSS target. In other words, you can cause Shorewall to set the MSS field of SYN packets passing through the firewall to the value you specify. This feature extends the existing CLAMPMSS option in /etc/shorewall/shorewall.conf by allowing that option to have a numeric value as well as the values "Yes" and "No".

    Example:

        CLAMPMSS=1400

  16. Shorewall now includes support for the ipp2p match facility. This is a departure from my usual policy in that the ipp2p match facility is included in Patch-O-Matic-NG and is unlikely to ever be included in the kernel.org source tree. Questions about how to install the patch or how to build your kernel and/or iptables should not be posted on the Shorewall mailing lists.

    In the following files, the "PROTO" or "PROTOCOL" column may contain "ipp2p":

           /etc/shorewall/rules
           /etc/shorewall/tcrules
           /etc/shorewall/accounting

    When the PROTO or PROTOCOL column contains "ipp2p" then the DEST PORT(S) or PORT(S) column may contain a recognized ipp2p option; for a list of the options and their meaning, at a root prompt:

        iptables -m ipp2p --help

    You must not include the leading "--" on the option; Shorewall will supply those characters for you. If you do not include an option then "ipp2p" is assumed (Shorewall will generate "-m ipp2p --ipp2p").
  17. Shorewall now has support for the CONNMARK target from iptables. See the /etc/shorewall/tcrules file for details.
  18. A new debugging option LOGALLNEW has been added to shorewall.conf. When set to a log level, this option causes Shorewall to generaate a logging rule as the first rule in each builtin chain.

        - The table name is used as the chain name in the log prefix.
        - The chain name is used as the target in the log prefix.

    Example: Using the default LOGFORMAT, the log prefix for logging from the nat table's PREROUTING chain is:

         Shorewall:nat:PREROUTING

    IMPORTANT: There is no rate limiting on these logging rules so use LOGALLNEW at your own risk; it may cause high CPU and disk utilization and you may not be able to control your firewall after you enable this option.

    DANGER: DO NOT USE THIS OPTION IF THE RESULTING LOG MESSAGES WILL BE SENT TO ANOTHER SYSTEM.

  19. The SUBNET column in /etc/shorewall/rfc1918 has been renamed SUBNETS and it is now possible to specify a list of addresses in that column.
  20. The AllowNNTP action now also allows NNTP over SSL/TLS (NNTPS).
  21. For consistency, the CLIENT PORT(S) column in the tcrules file has been renamed SOURCE PORT(S).
  22. The contents of /proc/sys/net/ip4/icmp_echo_ignore_all is now shown in the output of "shorewall status".
  23. A new IPTABLES option has been added to shorewall.conf. IPTABLES can be used to designate the iptables executable to be used by Shorewall. If not specified, the iptables executable determined by the PATH setting is used.
  24. You can now use the "shorewall show zones" command to display the current contents of the zones. This is particularly useful if you use dynamic zones (DYNAMIC_ZONES=Yes in shorewall.conf).

        Example:

          ursa:/etc/shorewall # shorewall show zones
        Shorewall-2.2.0-Beta7 Zones at ursa - Sat Nov 27 11:18:25 PST 2004
     
        loc
           eth0:192.168.1.0/24
           eth1:1.2.3.4
        net      
           eth0:0.0.0.0/0
        WiFi
           eth1:0.0.0.0/0
        sec
           eth1:0.0.0.0/0
     
        ursa:/etc/shorewall #

  25. Variable expansion may now be used with the INCLUDE directive.

        Example:

        /etc/shorewall/params

            FILE=/etc/foo/bar

            Any other config file:

            INCLUDE $FILE

  26. The output of "shorewall status" now includes the results of "ip -stat link ls". This helps diagnose performance problems caused by link errors.
  27. Previously, when rate-limiting was specified in /etc/shorewall/policy (LIMIT:BURST column), any traffic which exceeded the specified rate was silently dropped. Now, if a log level is given in the entry (LEVEL column) then drops are logged at that level at a rate of 5/min with a burst of 5.
  28. Recent 2.6 kernels include code that evaluates TCP packets based on TCP Window analysis. This can cause packets that were previously classified as NEW or ESTABLISHED to be classified as INVALID.

    The new kernel code can be disabled by including this command in your /etc/shorewall/init file:

        echo 1 > /proc/sys/net/ipv4/netfilter/ip_conntrack_tcp_be_liberal

    Additional kernel logging about INVALID TCP packets may be obtained by adding this command to /etc/shorewall/init:

        echo 1 > /proc/sys/net/ipv4/netfilter/ip_conntrack_log_invalid

    Traditionally, Shorewall has dropped INVALID TCP packets early. The new DROPINVALID option allows INVALID packets to be passed through the normal rules chains by setting DROPINVALID=No.

    If not specified or if specified as empty (e.g., DROPINVALID="") then DROPINVALID=Yes is assumed.

  29. The "shorewall add" and "shorewall delete" commands now accept a list of hosts to add or delete.

    Examples:

        shorewall add eth1:1.2.3.4 eth1:2.3.4.5 z12
       shorewall delete eth1:1.2.3.4 eth1:2.3.4.5 z12

        The above commands may also be written:

        shorewall add eth1:1.2.3.4,2.3.4.5 z12
       shorewall delete eth1:1.2.3.4,2.3.4.5 z12
      
  30. TCP OpenVPN tunnels are now supported using the 'openvpn' tunnel type. OpenVPN entries in /etc/shorewall/tunnels have this format:

        openvpn[:{tcp|udp}][:<port>]    <zone>        <gateway>

    Examples:

          openvpn:tcp         net    1.2.3.4    # TCP tunnel on port 1194
        openvpn:3344        net    1.2.3.4    # UDP on port 3344
        openvpn:tcp:4455    net    1.2.3.4    # TCP on port 4455

  31. A new 'ipsecvpn' script is included in the tarball and in the RPM. The RPM installs the file in the Documentation directory (/usr/share/doc/packages/shorewall-2.2.0-0RC1).

    This script is intended for use on Roadwarrior laptops for establishing an IPSEC SA to/from remote networks. The script has some limitations:
  1. The output of "shorewall status" now lists the loaded netfilter kernel modules.
  2. The range of UDP ports opened by the AllowTrcrt action has been increased to 33434:33524.
  3. The IANA has recently registered port 1194 for use by OpenVPN. In previous versions of Shorewall (and OpenVPN), the default port was 5000 but has been changed to 1194 to conform to the new OpenVPN default.

More News

Leaf

(Leaf Logo) LEAF is an open source project which provides a Firewall/router on a floppy, CD or CF. Several LEAF distributions including Bering and Bering-uClibc use Shorewall as their Netfilter configuration tool.

OpenWRT

(OpenWRT Logo)OpenWRT is a project which provides open source firmware for Linksys WRT54G wireless routers. Two different Shorewall packages are available for OpenWRT.

Donations

(Alzheimer's Association Logo)(Starlight Foundation Logo)Shorewall is free but if you try it and find it useful, please consider making a donation to the Alzheimer's Association or to the Starlight Children's Foundation.

Thank You