# Shorewall 3.x Reference

Tom
Eastep
2001-2006
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.

This documentation is intended primarily for reference. Step-by-step instructions for configuring Shorewall in common setups may be found in the QuickStart Guides.

This article applies to Shorewall 3.0 and later. If you are running a version of Shorewall earlier than Shorewall 3.0.0 then please see the documentation for that release.

## Components

Shorewall consists of the following components:

params

  a parameter file installed in `/etc/shorewall` that can be used to establish the values of shell variables for use in other files.

shorewall.conf

  a parameter file installed in `/etc/shorewall` that is used to set several firewall parameters.

zones

  a parameter file installed in `/etc/shorewall` that defines a network partitioning into zones

policy

  a parameter file installed in `/etc/shorewall` that establishes overall firewall policy.

rules

  a parameter file installed in `/etc/shorewall` and used to express firewall rules that are exceptions to the high-level policies established in /etc/shorewall/policy.

blacklist

  a parameter file installed in `/etc/shorewall` and used to list blacklisted IP/subnet/MAC addresses.

ecn

  a parameter file installed in `/etc/shorewall` and used to selectively disable Explicit Congestion Notification (ECN - RFC 3168).

functions

  a set of shell functions used by both the firewall and shorewall shell programs. Installed in `/usr/share/shorewall`.

modules

  a parameter file installed in `/etc/shorewall` and that specifies kernel modules and their parameters. Shorewall will automatically load the modules specified in this file.

tos

  a parameter file installed in `/etc/shorewall` that is used to specify how the Type of Service (TOS) field in packets is to be set.

init.sh and init.debian.sh

  a shell script installed in `/etc/init.d` to automatically start Shorewall during boot. The particular script installed depends on which distribution you are running.

interfaces

  a parameter file installed in `/etc/shorewall` and used to describe the interfaces on the firewall system.

hosts

  a parameter file installed in `/etc/shorewall` and used to describe individual hosts or subnetworks in zones.

maclist

  a parameter file installed in `/etc/shorewall` and used to verify the MAC address (and possibly also the IP address(es)) of devices.

masq

  This file also describes IP masquerading under Shorewall and is installed in `/etc/shorewall`.

firewall

  a shell program that reads the configuration files in `/etc/shorewall` and configures your firewall. This file is installed in `/usr/share/shorewall`.

nat

  a parameter file in `/etc/shorewall` used to define one-to-one NAT.

proxyarp

  a parameter file in `/etc/shorewall` used to define Proxy Arp.

rfc1918

  a parameter file in `/usr/share/shorewall` used to define the treatment of packets under the norfc1918 interface option.

routestopped

  a parameter file in `/etc/shorewall` used to define those hosts that can access the firewall when Shorewall is stopped.

tcrules

  a parameter file in `/etc/shorewall` used to define rules for classifying packets for Traffic Shaping/Control.

tcdevices

  a parameter file in `/etc/shorewall` used to define the bandwidth for interfaces on which you want traffic shaping to be enabled.

tcclasses

  a parameter file in `/etc/shorewall` used to define classes for traffic shaping.

tcstart

  a set of shell functions used by Shorewall to setup traffic shaping.This file is installed in `/usr/share/shorewall`.

tunnels

  a parameter file in `/etc/shorewall` used to define IPSec tunnels.

shorewall

  a shell program (requiring a Bourne shell or derivative) used to control and monitor the firewall. This should be placed in `/sbin` or in `/usr/sbin` (the install.sh script and the rpm install this file in `/sbin`).

accounting

  a parameter file in `/etc/shorewall` used to define traffic accounting rules.

version

  a file created in `/usr/share/shorewall` that describes the version of Shorewall installed on your system.

actions and action.template

  files in `/etc/shorewall` and `/usr/share/shorewall` respectively that allow you to define your own actions for rules in `/etc/shorewall/rules`.

actions.std and action.*

  files in `/usr/share/shorewall` that define the actions included as a standard part of Shorewall.

providers

  file in /etc/shorewall that is used to define multiple Internet Service Providers and load-balancing.

capabilities

  file in /etc/shorewall that is used to define the iptables/kernel capabilities of a remote system. The file allows firewall scripts compiled on one system to be tailored for a remote system where the script will ultimately run under Shorewall Lite.

## /etc/shorewall/params

You may use the file `/etc/shorewall/params` file to set shell variables that you can then use in some of the other configuration files.

It is suggested that variable names begin with an upper case letter to distinguish them from variables used internally within the Shorewall programs

### shell variables

    NET_IF=eth0 NET_BCAST=130.252.100.255
    NET_OPTIONS=blacklist,norfc1918

### /etc/shorewall/interfaces record

    net $NET_IF $NET_BCAST $NET_OPTIONS

The result will be the same as if the record had been written

    net eth0 130.252.100.255 blacklist,norfc1918

Variables may be used anywhere in the other configuration files.

## /etc/shorewall/zones

This file is used to define the network zones. There is one entry in `/etc/shorewall/zones` for each zone; Columns in an entry are:

ZONE

  short name for the zone. The name should be 5 characters or less in length and consist of lower-case letters or numbers. Short names must begin with a letter and the name assigned to the firewall is reserved for use by Shorewall itself. Note that the output produced by iptables is much easier to read if you select short names that are three characters or less in length. The name all may not be used as a zone name nor may the zone name assigned to the firewall itself via the FW variable in .

  The `/etc/shorewall/interfaces` and `/etc/shorewall/hosts` file allow you to define nested or overlapping zones. Such overlapping/nested zones are allowed and Shorewall normally processes zones in the order that they appear in the `/etc/shorewall/zones` file. So if you have nested zones, you want the sub-zone to appear before the super-zone and in the case of overlapping zones, the rules that will apply to hosts that belong to both zones is determined by which zone appears first in `/etc/shorewall/zones`.

  Hosts that belong to more than one zone may be managed by the rules of all of those zones. This is done through use of the special CONTINUE policy described below.

  Beginning with Shorewall 3.0, you can adjust the order in which Shorewall generates its rules by using special syntax in the ZONE column of `/etc/shorewall/zones`. Where a zone is nested in one or more other zones, you may follow the (sub)zone name by ":" and a comma-separated list of the parent zones. The parent zones must have been declared in earlier records in this file.

  Example:

  >     #ZONE                TYPE           OPTIONS
  >     parnt1               ipv4
  >     parnt2               ipv4
  >     child:parnt1,parnt2  ipv4

  Even though zones parnt1 and parnt2 are declared before zone child, Shorewall will generate the rules for child before either of the parent zones.

TYPE
  - ipsec - All traffic to/from this zone is encrypted.
  - ipv4 - By default, traffic to/from some of the hosts in this zone is not encrypted. Any encrypted hosts are designated using the ipsec option in /etc/shorewall/hosts.
  - firewall - Designates the firewall itself. You must have exactly one 'firewall' zone. No options are permitted with a 'firewall' zone.
OPTIONS, IN OPTIONS, OUT OPTIONS

  Optional parameters that identify the security policy and security associations used in communication with hosts in this zone. A comma-separated list of the following:

  - proto[!]=ah|esp|ipcomp
  - mode[!]=transport|tunnel
  - reqid[!]=<number> — A number assigned to a security policy using the unique:<number> as the SPD level. See setkey(8).
  - tunnel-src[!]=<address>[/<mask>] — Tunnel Source; may only be included with mode=tunnel. Since tunnel source and destination are dependent on the direction of the traffic, this option and the following one should only be included in the IN OPTIONS and OUT OPTIONS columns.
  - tunnel-dst[!]=<address>[/<mask>] — Tunnel Destination; may only be included with mode=tunnel.
  - mss=<number> — Sets the MSS field in TCP syn packets forwarded to/from this zone. May be used to compensate for the lack of IPSEC pseudo-devices with their own MTU in the 2.6 Kernel IPSEC implementation. If specified in the IN OPTIONS, TCP SYN packets from the zone will have MSS altered; if specified in the OUT OPTIONS, TCP SYN packets to the zone will have MSS altered.
  - spi[!]=<number> — The security parameter index of the Security Association. Since a different SA is used for incoming and outgoing traffic, this option should only be listed in the IN OPTIONS and OUT OPTIONS columns.
  - strict — Must be specified when SPD rules are used (e.g., esp encapsulated with ah).
  - next — Separates rules when strict is used.

## /etc/shorewall/interfaces

This file is used to tell the firewall which of your firewall's network interfaces are connected to which zone. There will be one entry in /etc/shorewall/interfaces for each of your interfaces. Columns in an entry are:

ZONE

  A zone defined in the file or -. If you specify -, you must use the file to define the zones accessed via this interface.

INTERFACE

  the name of the interface (examples: eth0, ppp0, ipsec+). Each interface can be listed on only one record in this file.

  You do not need to include the loopback interface (lo) in this file.

BROADCAST

  the broadcast address(es) for the sub-network(s) attached to the interface. This should be left empty for P-T-P interfaces (ppp*, ippp*); if you need to specify options for such an interface, enter - in this column. If you supply the special value detect in this column, the firewall will automatically determine the broadcast address. In order to use detect:

  - the interface must be up before you start your firewall

  - the interface must only be attached to a single sub-network (i.e., there must have a single broadcast address).

OPTIONS

  a comma-separated list of options. Possible options include:

  arp_filter

    This option causes `/proc/sys/net/ipv4/conf/<interface>/arp_filter` to be set with the result that this interface will only answer ARP who-has requests from hosts that are routed out of that interface. Setting this option facilitates testing of your firewall where multiple firewall interfaces are connected to the same HUB/Switch (all interface connected to the single HUB/Switch should have this option specified). Note that using such a configuration in a production environment is strongly recommended against.

  arp_ignore[=<number>]

    respond to arp requests based on the value of <number>.

    1 - reply only if the target IP address is local address configured on the incoming interface

    2 - reply only if the target IP address is local address configured on the incoming interface and both with the sender's IP address are part from same subnet on this interface

    3 - do not reply for local addresses configured with scope host, only resolutions for global and link addresses are replied

    4-7 - reserved

    8 - do not reply for all local addresses

    If no <number> is given then the value 1 is assumed

    DO NOT SPECIFY arp_ignore FOR ANY INTERFACE INVOLVED IN PROXY ARP.

  routeback

    This option causes Shorewall to set up handling for routing packets that arrive on this interface back out the same interface. If this option is specified, the ZONE column may not contain -.

  tcpflags

    This option causes Shorewall to make sanity checks on the header flags in TCP packets arriving on this interface. Checks include Null flags, SYN+FIN, SYN+RST and FIN+URG+PSH; these flag combinations are typically used for silent port scans. Packets failing these checks are logged according to the TCP_FLAGS_LOG_LEVEL option in and are disposed of according to the TCP_FLAGS_DISPOSITION option.

  blacklist

    This option causes incoming packets on this interface to be checked against the blacklist.

  dhcp

    The interface is assigned an IP address via DHCP or is used by a DHCP server running on the firewall. The firewall will be configured to allow DHCP traffic to and from the interface even when the firewall is stopped. You may also wish to use this option if you have a static IP but you are on a LAN segment that has a lot of Laptops that use DHCP and you select the norfc1918 option (see below).

  norfc1918

    Packets arriving on this interface and that have a source or destination address that is reserved in RFC 1918 will be dropped after being optionally logged.

    Beware that as IPv4 addresses become in increasingly short supply, ISPs are beginning to use RFC 1918 addresses within their own infrastructure. Also, many cable and DSL modems have an RFC 1918 address that can be used through a web browser for management and monitoring functions. If you want to specify norfc1918 on your external interface but need to allow access to certain addresses from the above list, see FAQ 14.

  routefilter

    Invoke the Kernel's route filtering (anti-spoofing) facility on this interface. The kernel will reject any packets incoming on this interface that have a source address that would be routed outbound through another interface on the firewall.

    If you specify this option for an interface then the interface must be up prior to starting the firewall.

  proxyarp

    This option causes Shorewall to set /proc/sys/net/ipv4/conf/<interface>/proxy_arp and is used when implementing Proxy ARP Sub-netting as described at http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/. Do not set this option if you are implementing Proxy ARP through entries in .

  maclist

    If this option is specified, all connection requests from this interface are subject to MAC Verification. May only be specified for ethernet interfaces.

  detectnets

    If this option is specified, the zone named in the ZONE column will contain only the hosts routed through the interface named in the INTERFACE column. Do not set this option on your external (Internet) interface! The interface must be in the UP state when Shorewall is [re]started.

  nosmurfs

    If this option is specified, incoming connection requests will be checked to ensure that they do not have a broadcast or multicast address as their source. Any such packets will be dropped after being optionally logged according to the setting of SMURF_LOG_LEVEL in /etc/shorewall/shorewall.conf.

  logmartians

    If this option is specified, the kernel's martian logging facility will be enabled on this interface (/proc/sys/net/ipv4/conf/<interface>/log_martians will be set to 1). See also the LOG_MARTIANS option in shorewall.conf.

  sourceroute

    If this option is not specified for an interface, then source-routed packets will not be accepted from that interface (sets `/proc/sys/net/ipv4/conf/<interface>`/accept_source_route to 1).Only set this option if you know what you are you doing. This might represent a security risk and is not usually needed.

  upnp

    Incoming requests from this interface may be remapped via UPNP (upnpd).

  My recommendations concerning options:

  - External Interface -- tcpflags,blacklist,norfc1918,routefilter,nosmurfs,logmartians

  - Wireless Interface -- maclist,routefilter,tcpflags,detectnets,nosmurfs

  - Use dhcp and proxyarp when needed.

### You have a conventional firewall setup in which eth0 connects to a Cable or DSL modem and eth1 connects to your local network and eth0 gets its IP address via DHCP. You want to check all packets entering from the internet against the black list. Your /etc/shorewall/interfaces file would be as follows:

    #ZONE    INTERFACE    BROADCAST    OPTIONS
    net      eth0         detect       dhcp,norfc1918,blacklist

### You have a standalone dialup GNU/Linux System. Your /etc/shorewall/interfaces file would be:

    #ZONE    INTERFACE    BROADCAST    OPTIONS
    net      ppp0

### You have local interface eth1 with two IP addresses - 192.168.1.1/24 and 192.168.12.1/24

    #ZONE    INTERFACE    BROADCAST                    OPTIONS
    loc      eth1         192.168.1.255,192.168.12.255

## /etc/shorewall/hosts Configuration

For most applications, specifying zones entirely in terms of network interfaces is sufficient. There may be times though where you need to define a zone to be a more general collection of hosts. This is the purpose of the `/etc/shorewall/hosts` file.

The only time that you need entries in `/etc/shorewall/hosts` is where you have more than one zone connecting through a single interface.

IF YOU DON'T HAVE THIS SITUATION THEN DON'T TOUCH THIS FILE!!

Columns in this file are:

ZONE

  A zone defined in the file.

HOST(S)

  The name of an interface defined in the /etc/shorewall/interfaces file followed by a colon (":") and a comma-separated list whose elements are either:

  1. The IP address of a host

  2. A subnetwork in the form <subnet-address>/<mask width>

  3. A physical port name; only allowed when the interface names a bridge created by the `brctl addbr` command. This port must not be defined in `/etc/shorewall/interfaces` and may optionally followed by a colon (":") and a host or network IP. See the bridging documentation for details.

OPTIONS

  A comma-separated list of option

  routeback

    This option causes Shorewall to set up handling for routing packets sent by this host group back back to the same group.

  maclist

    If specified, connection requests from the hosts specified in this entry are subject to MAC Verification. This option is only valid for ethernet interfaces.

  tcpflags

    This option causes Shorewall to make sanity checks on the header flags in TCP packets arriving from these hosts. Checks include Null flags, SYN+FIN, SYN+RST and FIN+URG+PSH; these flag combinations are typically used for silent port scans. Packets failing these checks are logged according to the TCP_FLAGS_LOG_LEVEL option in and are disposed of according to the TCP_FLAGS_DISPOSITION option.

  blacklist (only makes sense for bridge ports)

    This option causes incoming packets on this port to be checked against the blacklist.

  norfc1918 -- only makes sense for bridge ports)

    Packets arriving on this port and that have a source address that is reserved in RFC 1918 will be dropped after being optionally logged as specified in the section of RFC1918_LOG_LEVEL in shorewall.conf.

  nosmurfs (only makes sense for bridge ports)

    If this option is specified, incoming connection requests will be checked to ensure that they do not have a broadcast or multicast address as their source. Any such packets will be dropped after being optionally logged according to the setting of SMURF_LOG_LEVEL in /etc/shorewall/shorewall.conf.

  ipsec

    The hosts are accessed via a kernel 2.6 ipsec SA. Note that if the zone named in the ZONE column is specified as an IPSEC zone in the /etc/shorewall/zones file then you do NOT need to specify 'ipsec' here.

If you don't define any hosts for a zone, the hosts in the zone default to i0:0.0.0.0/0 , i1:0.0.0.0/0, ... where i0, i1, ... are the interfaces to the zone.

You probably DON'T want to specify any hosts for your internet zone since the hosts that you specify will be the only ones that you will be able to access without adding additional rules.

### Your local interface is eth1 and you have two groups of local hosts that you want to make into separate zones:

    192.168.1.0/25 192.168.1.128/25

Your /etc/shorewall/interfaces file might look like:

    #ZONE    INTERFACE    BROADCAST    OPTIONS
    net      eth0         detect       dhcp,norfc1918
    -        eth1         192.168.1.127,192.168.1.255

The - in the ZONE column for eth1 tells Shorewall that eth1 interfaces to multiple zones.

    #ZONE       HOST(S)               OPTIONS
    loc1        eth1:192.168.1.0/25
    loc2        eth1:192.168.1.128/25

### You have local interface eth1 with two IP addresses - 192.168.1.1/24 and 192.168.12.1/24

Your /etc/shorewall/interfaces file might look like:

    #ZONE    INTERFACE    BROADCAST    OPTIONS
    net      eth0         detect       dhcp,norfc1918
    -        eth1         192.168.1.255,192.168.12.255

Your /etc/shorewall/hosts file might look like:

    #ZONE       HOST(S)               OPTIONS
    loc         eth1:192.168.1.0/24,192.168.12.0/24

## /etc/shorewall/policy Configuration

This file is used to describe the firewall policy regarding establishment of connections. Connection establishment is described in terms of clients who initiate connections and servers who receive those connection requests. Policies defined in `/etc/shorewall/policy` describe which zones are allowed to establish connections with other zones.

Policies established in `/etc/shorewall/policy` can be viewed as default policies. If no rule in /etc/shorewall/rules applies to a particular connection request then the policy from `/etc/shorewall/policy` is applied.

Five policies are defined:

ACCEPT

  The connection is allowed.

DROP

  The connection request is ignored.

REJECT

  The connection request is rejected with an RST (TCP) or an ICMP destination-unreachable packet being returned to the client.

QUEUE

  Send the connection request to a user-space process via the iptables QUEUE target (useful when you are using Snort-inline).

CONTINUE

  The connection is neither ACCEPTed, DROPped nor REJECTed. CONTINUE may be used when one or both of the zones named in the entry are sub-zones of or intersect with another zone. For more information, see below.

NONE

  Shorewall should not set up any infrastructure for handling traffic from the SOURCE zone to the DEST zone. When this policy is specified, the LOG LEVEL and BURST:LIMIT columns must be left blank.

For each policy specified in /etc/shorewall/policy, you can indicate that you want a message sent to your system log each time that the policy is applied.

Shorewall supports the association of a set of rules with individual policies. Packets that are having the policy applied are first passed through the associated rules. These rules are specified in the form of a default action or default macro.

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

This approach has had drawbacks:

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

2. Now that Shorewall supports modularized action processing (see the USE_ACTIONS option below), we need a way to define default rules for a policy that does not involve actions.

The solution was two-fold:

- Four new options were 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:

  1. The name of an action.

  2. The name of a macro.

  3. '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 (if any) must be specified in /etc/shorewall/policy.

- The POLICY column in /etc/shorewall/policy was 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:

  1. The word "None" or "none". This causes any default action defined in `/etc/shorewall/shorewall.conf` to be omitted for this policy.

  2. The name of an action (requires that USE_ACTIONS=Yes in shorewall.conf). That action will be invoked before the policy is enforced.

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

  If the value names both an action and a macro, then the action will be used if USE_ACTIONS=Yes and the macro will be used if USE_ACTIONS=No.

Entries in /etc/shorewall/policy have four columns as follows:

SOURCE

  The name of a client zone (a zone defined in the file , the name of the firewall zone or all).

DEST

  The name of a destination zone (a zone defined in the file , the name of the firewall zone or all). Shorewall automatically allows all traffic from the firewall to itself so the name of the firewall zone cannot appear in both the SOURCE and DEST columns.

POLICY

  The default policy for connection requests from the SOURCE zone to the DESTINATION zone. Beginning with Shorewall version 3.4.0, the policy may be optionally followed by a colon (":") and the default action or default macro to be used before the policy is applied. Default actions or macros specified here override any such default specified using the policy_DEFAULT options in /etc/shorewall/shorewall.conf.

LOG LEVEL

  Optional. If left empty, no log message is generated when the policy is applied. Otherwise, this column should contain an integer or name indicating a syslog level.

LIMIT:BURST - optional

  If left empty, TCP connection requests from the SOURCE zone to the DEST zone will not be rate-limited. Otherwise, this column specifies the maximum rate at which TCP connection requests will be accepted followed by a colon (:) followed by the maximum burst size that will be tolerated. Example: 10/sec:40 specifies that the maximum rate of TCP connection requests allowed will be 10 per second and a burst of 40 connections will be tolerated. Connection requests in excess of these limits will be dropped. See the rules file documentation for an explanation of how rate limiting works.

In the SOURCE and DEST columns, you can enter all to indicate all zones.

The default `/etc/shorewall/policy` file is as follows.

    #SOURCE    DEST      POLICY    LOG LEVEL    LIMIT:BURST
    loc        net       ACCEPT
    net        all       DROP      info
    all        all       REJECT    info

This table may be interpreted as follows:

- All connection requests from the local network to hosts on the internet are accepted.

- All connection requests originating from the internet are ignored and logged at level KERNEL.INFO.

- All other connection requests are rejected and logged.

The firewall script processes the `/etc/shorewall/policy` file from top to bottom and uses the first applicable policy that it finds. For example, in the following policy file, the policy for (loc, loc) connections would be ACCEPT as specified in the first entry even though the third entry in the file specifies REJECT.

    #SOURCE    DEST      POLICY    LOG LEVEL    LIMIT:BURST
    loc        all       ACCEPT
    net        all       DROP      info
    loc        loc       REJECT    info

### Intra-Zone Traffic

Shorewall allows a zone to be associated with more than one interface or with multiple networks that interface through a single interface. Shorewall will ACCEPT all traffic from a zone to itself provided that there is no explicit policy governing traffic from that zone to itself (an explicit policy does not specify all in either the SOURCE or DEST column).

The idea is this:

1. A zone should be homogeneous with respect to security requirements.

2. Traffic within a zone should not require rules or policies.

3. Shorewall will not restrict traffic within a zone.

Any time that you have multiple interfaces associated with a single zone, you should ask yourself if you really want traffic routed between those interfaces. Cases where you might not want that behavior are:

1. Multiple net interfaces to different ISPs. You don't want to route traffic from one ISP to the other through your firewall.

2. Multiple VPN clients. You don't necessarily want them to all be able to communicate between themselves using your gateway/router.

You can control the traffic from the firewall to itself. As with any zone, fw->fw traffic is enabled by default. It is not necessary to define the loopback interface (lo) in /etc/shorewall/interfaces in order to define fw->fw rules or a fw->fw policy.

### The CONTINUE policy

Where zones are nested or overlapping, the CONTINUE policy allows hosts that are within multiple zones to be managed under the rules of all of these zones. Let's look at an example:

`/etc/shorewall/zones`:

    #ZONE    TYPE        OPTION
    $FW      firewall
    sam      ipv4
    net      ipv4
    loc      ipv4

`/etc/shorewall/interfaces`:

    #ZONE     INTERFACE     BROADCAST     OPTIONS
    -         eth0          detect        dhcp,norfc1918
    loc       eth1          detect

`/etc/shorewall/hosts`:

    #ZONE     HOST(S)                     OPTIONS
    net       eth0:0.0.0.0/0
    sam       eth0:206.191.149.197

Sam's home system is a member of both the sam zone and the net zone and as described above , that means that sam must be listed before net in `/etc/shorewall/zones`.

`/etc/shorewall/policy`:

    #SOURCE      DEST        POLICY       LOG LEVEL
    loc          net         ACCEPT
    sam          all         CONTINUE
    net          all         DROP         info
    all          all         REJECT       info

The second entry above says that when Sam is the client, connection requests should first be process under rules where the source zone is sam and if there is no match then the connection request should be treated under rules where the source zone is net. It is important that this policy be listed BEFORE the next policy (net to all).

Partial `/etc/shorewall/rules`:

    #ACTION   SOURCE    DEST            PROTO    DEST PORT(S)
    ...
    DNAT      sam       loc:192.168.1.3 tcp      ssh
    DNAT      net       loc:192.168.1.5 tcp      www
    ...

Given these two rules, Sam can connect to the firewall's internet interface with ssh and the connection request will be forwarded to 192.168.1.3. Like all hosts in the net zone, Sam can connect to the firewall's internet interface on TCP port 80 and the connection request will be forwarded to 192.168.1.5. The order of the rules is not significant.

Sometimes it is necessary to suppress port forwarding for a sub-zone. For example, suppose that all hosts can SSH to the firewall and be forwarded to 192.168.1.5 EXCEPT Sam. When Sam connects to the firewall's external IP, he should be connected to the firewall itself. Because of the way that Netfilter is constructed, this requires two rules as follows:

    #ACTION   SOURCE    DEST            PROTO    DEST PORT(S)
    ...
    ACCEPT+   sam       $FW             tcp      ssh
    DNAT      net       loc:192.168.1.3 tcp      ssh
    ...

The first rule allows Sam SSH access to the firewall. The second rule says that any clients from the net zone with the exception of those in the sam zone should have their connection port forwarded to 192.168.1.3. If you need to exclude more than one zone, simply use multiple ACCEPT+ rules. This technique also may be used when the ACTION is REDIRECT.

## /etc/shorewall/rules

The `/etc/shorewall/rules` file defines exceptions to the policies established in the `/etc/shorewall/policy` file. There is one entry in /etc/shorewall/rules for each of these rules. Entries in this file only govern the establishment of new connections — packets that are part of an existing connection or that establish a connection that is related to an existing connection are automatically accepted.

Rules for each pair of zones (source zone, destination zone) are evaluated in the order that they appear in the file — the first match determines the disposition of the connection request with a couple of caveats:

- LOG rules cause the connection request to be logged then processing continues with the next rule in the file.

- QUEUE rules cause the connection request to be passed to user-space -- the user-space application can later insert them back into the stream for further processing by following rules.

- CONTINUE rules may cause the connection request to be reprocessed using a different (source zone, destination zone) pair.

The /etc/shorewall/rules file may now be into sections. Each section is introduced by a line that begins with the keyword SECTION which is followed by the section name. Sections are as listed below and must appear in the order shown.

ESTABLISHED

  Rules in this section apply to packets in the ESTABLISHED state.

RELATED

  Rules in this section apply to packets in the RELATED state.

NEW

  Rules in this section apply to packets in the NEW and INVALID states.

Rules in the ESTABLISHED and RELATED sections are limited to the following ACTIONs:

> ACCEPT, DROP, REJECT, QUEUE, LOG and User-defined actions.

Macros may be used in these sections provided that they expand to only these ACTIONs. At the end of the ESTABLISHED and RELATED sections, there is an implicit ACCEPT rule.

RESTRICTION: If you specify FASTACCEPT=Yes in /etc/shorewall.shorewall.conf then the ESTABLISHED and RELATED sections must be empty.

Unless you understand Netfilter well enough to be comfortable with the difference between ESTABLISHED, RELATED, INVALID and NEW connection tracking states, you should omit the ESTABLISHED and RELATED sections and place all of your rules in the NEW section.

Entries in the file have the following columns:

ACTION
  ACCEPT, DROP, REJECT, CONTINUE

    These have the same meaning here as in the policy file above.

  ACCEPT+

    Works like ACCEPT but also exempts the connection from matching DNAT and REDIRECT rules later in the file.

  NONAT

    Exempts matching connections from DNAT and REDIRECT rules later in the file.

  DNAT

    Causes the connection request to be forwarded to the system specified in the DEST column (port forwarding). DNAT stands for Destination Network Address Translation

  DNAT-

    The above ACTION (DNAT) generates two iptables rules:

    1. a header-rewriting rule in the Netfilter nat table

    2. an ACCEPT rule in the Netfilter filter table.

    DNAT- works like DNAT but only generates the header-rewriting rule.

  SAME

    SAME is useful when more than one server IP address (an address range, for example) is given in the DEST column below. SAME works similar to DNAT with the exception that when multiple connections from an internet host match a SAME rule then all of the connections will be sent to the same internal server.

    Unlike when using DNAT rules, SAME rules may not alter the destination port number used for the connection.

  SAME-

    SAME generates two iptables rules:

    1. a header-rewriting rule in the Netfilter nat table

    2. an ACCEPT rule in the Netfilter filter table.

    SAME- works like SAME but only generates the header-rewriting rule.

  REDIRECT

    Causes the connection request to be redirected to a port on the local (firewall) system.

  REDIRECT-

    The above ACTION (REDIRECT) generates two iptables rules:

    1. a header-rewriting rule in the Netfilter nat table

    2. an ACCEPT rule in the Netfilter filter table.

    REDIRECT- works like REDIRECT but only generates the header-rewriting rule.

  LOG

    Log the packet -- requires a syslog level (see below).

  QUEUE

    Forward the packet to a user-space application. This facility is provided to allow interfacing to ftwall for Kazaa filtering.

    With Shorewall versions prior to 3.2.0, when the protocol specified in the PROTO column is TCP (tcp, TCP or 6), Shorewall will only pass connection requests (SYN packets) to user space. This is for compatibility with ftwall.

    With Shorewall version 3.2.0 and later, this special treatment no longer applies. Rather, use tcp:syn in the PROTOCOL column to acheive this behavior.

  <defined action>

    An action defined in the `/etc/shorewall/actions` or `/usr/share/shorewall/actions.std` files.

  <macro>

    The name of a macro defined using a file with name macro.<name>. Macro files are usually placed in /etc/shorewall but may reside in any directory on the CONFIG_PATH.

  The ACTION may optionally be followed by : and a syslog level (example: REJECT:info or ACCEPT:debug). This causes the packet to be logged at the specified level prior to being processed according to the specified ACTION. Note: if the ACTION is LOG then you MUST specify a syslog level. The log level may be optionally followed by a log tag. A log tag is a string of alphanumeric characters and is specified by following the log level with ":" and the log tag. Example:

      ACCEPT:info:ftp	net	dmz	tcp	21

  The log tag is appended to the log prefix generated by the LOGPREFIX variable in `/etc/shorewall/conf`. If "ACCEPT:info" generates the log prefix "Shorewall:net2dmz:ACCEPT:" then "ACCEPT:info:ftp" will generate "Shorewall:net2dmz:ACCEPT:ftp " (note the trailing blank). The maximum length of a log prefix supported by iptables is 29 characters; if a larger prefix is generated, Shorewall will issue a warning message and will truncate the prefix to 29 characters.

  Specifying a log level for a <defined action> will log all invocations of the action. For example:

      AllowFTP:info          net        dmz

  will log all net->dmz traffic that has not been handled by earlier rules. That's probably not what you want. If you want to log the FTP connections that are actually accepted, you need to log within the action itself. One way to do that would be to copy `/usr/share/shorewall/action.AllowFTP` to `/etc/shorewall` and modify the copy as follows:

      #TARGET       SOURCE         DEST            PROTO   DEST    SOURCE          RATE    USER/
      #                                                    PORT    PORT(S)         LIMIT   GROUP
      ACCEPT:info   -              -               tcp     21
      #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE

  The use of DNAT or REDIRECT requires that you have NAT enabled in your kernel configuration.

SOURCE

  Describes the source hosts to which the rule applies.. The contents of this field must begin with the name of a zone defined in /etc/shorewall/zones, $FW, all or "none".

  If the source is "none" then the rule is ignored. This is most commonly used with Shell Variables where a shell variable is set to "none" if a rule is to be omitted.

  "all" means "All Zones", including the firewall itself. "all-" means "All Zones, except the firewall itself". When "all[-]" is used either in the SOURCE or DEST column intra-zone traffic is not affected. When "all+[-]" is used, intra-zone traffic is affected. "all-" and "all+-" were introduced in Shorewall version 3.2.0 Beta 8.

  If the source is not one of the variants of all then the source may be further restricted by adding a colon (:) followed by a comma-separated list of qualifiers. Qualifiers are may include:

  interface name

    refers to any connection requests arriving on the specified interface (example loc:eth4). The interface name may optionally be followed by a colon (:) and an IP address or subnet (examples: loc:eth4:192.168.4.22, net:eth0:192.0.2.0/24).

  IP address

    refers to a connection request from the host with the specified address (example net:155.186.235.151). If the ACTION is DNAT, this must not be a DNS name.

  MAC Address

    in Shorewall format.

  subnet

    refers to a connection request from any host in the specified subnet (example net:155.186.235.0/24). IP address ranges of the form <first address>-<last address> may be specified. This requires that your kernel and iptables have iprange match support.

DEST

  Describes the destination host(s) to which the rule applies. May take most of the forms described above for SOURCE plus the following two additional forms:

  - An IP address followed by a colon and the port number that the server is listening on (service names from /etc/services are not allowed - example loc:192.168.1.3:80).

  - A single port number (again, service names are not allowed) -- this form is only allowed if the ACTION is REDIRECT and refers to a server running on the firewall itself and listening on the specified port.

  Restrictions:

  - MAC addresses may not be specified.

  - In DNAT rules, only IP addresses may be given -- DNS names are not permitted.

  - You may not specify both an IP address and an interface name in the DEST column.

  Like in the SOURCE column, a range of IP addresses may be specified in the DEST column as <first address>-<last address>. When the ACTION is DNAT or DNAT-, connections will be assigned to the addresses in the range in a round-robin fashion (load-balancing).

PROTO

  Protocol. Must be a protocol name from /etc/protocols, a number, or all. Specifies the protocol of the connection request.

  In the ESTABLISHED and RELATED sections, may also be "ipp2p", "ipp2p:udp", "ipp2p:all"; requires ipp2p match support in your kernel and iptables.

  Beginning with Shorewall 3.1, you may also specify "tcp:syn" in this column. This is equivalent to "tcp" but also requires that the SYN flag be set and the FIN, ACK and RST flags be reset.

DEST PORT(S)

  Port or port range (<low port>:<high port>) being connected to. May only be specified if the protocol is tcp, udp or icmp. For icmp, this column's contents are interpreted as an icmp type. If you don't want to specify DEST PORT(S) but need to include information in one of the columns to the right, enter - in this column. You may give a list of ports and/or port ranges separated by commas. Port numbers may be either integers or service names from /etc/services.

SOURCE PORTS(S)

  May be used to restrict the rule to a particular client port or port range (a port range is specified as <low port number>:<high port number>). If you don't want to restrict client ports but want to specify something in the next column, enter - in this column. If you wish to specify a list of port number or ranges, separate the list elements with commas (with no embedded white space). Port numbers may be either integers or service names from /etc/services.

ORIGINAL DEST

  This column may only be non-empty if the ACTION is DNAT or REDIRECT.

  If DNAT or REDIRECT is the ACTION and the ORIGINAL DEST column is left empty, any connection request arriving at the firewall from the SOURCE that matches the rule will be forwarded or redirected. This works fine for connection requests arriving from the internet where the firewall has only a single external IP address. When the firewall has multiple external IP addresses or when the SOURCE is other than the internet, there will usually be a desire for the rule to only apply to those connection requests directed to particular IP addresses (see Example 2 below for another usage). Those IP addresses are specified in the ORIGINAL DEST column as a comma-separated list.

  If this list begins with ! then the rule will only apply if the original destination address matches none of the addresses listed.

RATE LIMIT

  You may rate-limit ACCEPT, DNAT[-], REDIRECT[-] or LOG rules with an entry in this column. Entries have the form

      <rate>/<interval>[:<burst>]

  where <rate> is the number of connections per <interval> (sec or min) and <burst> is the largest burst permitted. If no burst value is given, a value of 5 is assumed.

  There may be no whitespace embedded in the specification.

  ### Let's take

      ACCEPT net dmz tcp 80 - - 2/sec:4

  The first time this rule is reached, the packet will be accepted; in fact, since the burst is 4, the first four packets will be accepted. After this, it will be 500ms (1 second divided by the rate of 2) before a packet will be accepted from this rule, regardless of how many packets reach it. Also, every 500ms which passes without matching a packet, one of the bursts will be regained; if no packets hit the rule for 2 second, the burst will be fully recharged; back where we started.

  When rate limiting is specified on a rule with all in the SOURCE or DEST fields below, the limit will apply to each pair of zones individually rather than as a single limit for all pairs of zones covered by the rule.

  If you want to specify any following columns but no rate limit, place - in this column.

USER/GROUP

  Output rules from the firewall itself may be restricted to a particular user or group.

  The column may contain:

             [!][<user name or number>][:<group name or number>][+<program name>]

  When this column is non-empty, the rule applies only if the program generating the output is running under the effective <user> and/or <group> specified (or is NOT running under that id if "!" is given).

  Examples:

      joe     #program must be run by joe
      :kids   #program must be run by a member of the 'kids' group
      !:kids  #program must not be run by a member of the 'kids' group
      +upnpd  #program named upnpd (This feature was removed from Netfilter in kernel version 2.6.14).

### You wish to forward all ssh connection requests from the internet to local system 192.168.1.3. You wish to limit the number of connections to 4/minute with a burst of 8:

    #ACTION        SOURCE      DEST             PROTO      DEST PORT(S)    ORIGINAL    RATE LIMIT
    #                                                                      DEST
    DNAT           net         loc:192.168.1.3  tcp        ssh             -           4/min:8

### You want to redirect all local www connection requests EXCEPT those to your own http server (206.124.146.177) to a Squid transparent proxy running on the firewall and listening on port 3128. Squid will of course require access to remote web servers. This example shows yet another use for the ORIGINAL DEST column; here, connection requests that were NOT (notice the !) originally destined to 206.124.146.177 are redirected to local port 3128.

    #ACTION  SOURCE  DEST   PROTO   DEST PORT(S)   SOURCE   ORIGINAL
    #                                              PORT(S)  DEST
    REDIRECT loc     3128   tcp     www            -        !206.124.146.177
    ACCEPT   $FW     net    tcp     www

### You want to run a web server at 155.186.235.222 in your DMZ and have it accessible remotely and locally. the DMZ is managed by Proxy ARP or by classical sub-netting.

    #ACTION        SOURCE      DEST                PROTO      DEST PORT(S)
    ACCEPT         net         dmz:155.186.235.222 tcp        www
    ACCEPT         loc         dmz:155.186.235.222 tcp        www

### You want to run wu-ftpd on 192.168.2.2 in your masqueraded DMZ. Your internet interface address is 155.186.235.151 and you want the FTP server to be accessible from the internet in addition to the local 192.168.1.0/24 and dmz 192.168.2.0/24 subnetworks.

since the server is in the 192.168.2.0/24 subnetwork, we can assume that access to the server from that subnet will not involve the firewall (but see FAQ 2)

unless you have more than one external IP address, you can leave the ORIGINAL DEST column blank in the first rule. You cannot leave it blank in the second rule though because then all ftp connections originating in the local subnet 192.168.1.0/24 would be sent to 192.168.2.2 regardless of the site that the user was trying to connect to. That is clearly not what you want.

    #ACTION  SOURCE             DEST             PROTO  DEST PORT(S)   SOURCE   ORIGINAL
    #                                                                  PORT(S)  DEST
    DNAT     net                dmz:192.168.2.2  tcp    ftp
    DNAT     loc:192.168.1.0/24 dmz:192.168.2.2  tcp    ftp            -        155.186.235.151

If you are running wu-ftpd, you should restrict the range of passive in your /etc/ftpaccess file. I only need a few simultaneous FTP sessions so I use port range 65500-65535. In /etc/ftpaccess, this entry is appropriate:

    passive ports 0.0.0.0/0 65500 65534

If you are running pure-ftpd, you would include -p 65500:65534 on the pure-ftpd runline.

The important point here is to ensure that the port range used for FTP passive connections is unique and will not overlap with any usage on the firewall system.

### You wish to allow unlimited DMZ access to the host with MAC address 02:00:08:E3:FA:55.

    #ACTION  SOURCE                  DEST PROTO DEST PORT(S)
    ACCEPT   loc:~02-00-08-E3-FA-55  dmz  all

### You wish to allow access to the SMTP server in your DMZ from all zones.

    #ACTION  SOURCE   DEST PROTO DEST PORT(S)
    ACCEPT   all      dmz  tcp   25

When all is used as a source or destination, intra-zone traffic is not affected. In this example, if there were two DMZ interfaces then the above rule would NOT enable SMTP traffic between hosts on these interfaces.

### Your firewall's external interface has several IP addresses but you only want to accept SSH connections on address 206.124.146.176.

    #ACTION  SOURCE   DEST               PROTO DEST PORT(S)
    ACCEPT   net      fw:206.124.146.176 tcp   22

### (For advanced users). From the internet, you with to forward tcp port 25 directed to 192.0.2.178 and 192.0.2.179 to host 192.0.2.177 in your DMZ. You also want to allow access from the internet directly to tcp port 25 on 192.0.2.177.

    #ACTION  SOURCE   DEST             PROTO  DEST PORT(S)   SOURCE   ORIGINAL
    #                                                        PORT(S)  DEST
    DNAT-    net      dmz:192.0.2.177  tcp    25             -        192.0.2.178
    DNAT-    net      dmz:192.0.2.177  tcp    25             -        192.0.2.179
    ACCEPT   net      dmz:192.0.2.177  tcp    25

Using DNAT- rather than DNAT avoids two extra copies of the third rule from being generated.

### You have 9 http servers behind a Shorewall firewall and you want connection requests to be distributed among your servers. The servers are 192.168.1.101-192.168.1.109.

    #ACTION  SOURCE   DEST                            PROTO DEST PORT(S)
    DNAT     net      loc:192.168.1.101-192.168.1.109 tcp   80

### You want to redirect all local www connection requests EXCEPT those from 192.168.1.4 and 192.168.1.199 to a Squid transparent proxy running on the firewall and listening on port 3128.

    #ACTION  SOURCE  DEST   PROTO   DEST PORT(S)   SOURCE   ORIGINAL
    #                                              PORT(S)  DEST
    NONAT    loc:192.168.1.4,192.168.1.199 \
                     net    tcp     www
    REDIRECT loc     3128   tcp     www            -
    ACCEPT   $FW     net    tcp     www

The reason that NONAT is used in the above example rather than ACCEPT+ is that the example is assuming the usual ACCEPT loc->net policy. Since traffic from the local zone to the internet zone is accepted anyway, adding an additional ACCEPT rule is unnecessary and all that is required is to avoid the REDIRECT rule for HTTP connection requests from the two listed IP addresses.

Look here for information on other services.

## /etc/shorewall/masq

The /etc/shorewall/masq file is used to define classical IP Masquerading and Source Network Address Translation (SNAT). There is one entry in the file for each subnet that you want to masquerade. In order to make use of this feature, you must have NAT enabled.

Columns are:

INTERFACE

  The interface that will masquerade the subnet; this is normally your internet interface. This interface name can be optionally qualified by adding : and a subnet or host IP. When this qualification is added, only packets addressed to that host or subnet will be masqueraded. The interface name can be qualified with ":" followed by a comma separated list of hosts and/or subnets. If this list begins with ! (e.g., eth0:!192.0.2.8/29,192.0.2.32/29) then only packets addressed to destinations not listed will be masqueraded; otherwise (e.g., eth0:192.0.2.8/29,192.0.2.32/29), traffic will be masqueraded if it does match one of the listed addresses.

  If you have set ADD_SNAT_ALIASES=Yes in , you can cause Shorewall to create an alias label of the form interfacename:digit (e.g., eth0:0) by placing that label in this column. See example 5 below. Alias labels created in this way allow the alias to be visible to the ipconfig utility. THAT IS THE ONLY THING THAT THIS LABEL IS GOOD FOR AND IT MAY NOT APPEAR ANYWHERE ELSE IN YOUR SHOREWALL CONFIGURATION.

  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

  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

SUBNET

  The subnet that you want to have masqueraded through the INTERFACE. This may be expressed as a single IP address, a subnet or an interface name. In the latter instance, the interface must be configured and started before Shorewall is started as Shorewall will determine the subnet based on information obtained from the ip utility.

  The subnet may be optionally followed by ! and a comma-separated list of addresses and/or subnets that are to be excluded from masquerading.

ADDRESS

  The source address to be used for outgoing packets. This column is optional and if left blank, the current primary IP address of the interface in the first column is used. If you have a static IP on that interface, listing it here makes processing of output packets a little less expensive for the firewall. If you specify an address in this column, it must be an IP address configured on the INTERFACE or you must have ADD_SNAT_ALIASES enabled in . You may include a range of IP addresses in this column to indicate that Netfilter should use the addresses in the range in round-robin fashion. Beginning with Shorewall version 1.4.7, you may include a list of ranges and/or addresses in this column; again, Netfilter will use all listed ranges/addresses in rounded-robin fashion.

  You may also specify the source port range to be used (the PROTO column must specify tcp or udp) by following the address or address range if any with ":" and the port range (in the format <low port>-<high port>).

  Examples:

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

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

  Some internet application that establish multiple connections from a client assume that when SNAT is being used that all connections between the client and a particular client and a remote server will appear to the server to come from the same external IP address. You can ensure that this is the case by preceding the ADDRESS range by "SAME:".

  Example:

      #INTERFACE SUBNET          ADDRESS
      eth0       10.0.0.0/8      SAME:192.0.2.44-192.168.2.50

  If you want all connections from an internal system to use the same external IP address regardless of the remote server that they are connecting to then precede the ADDRESS range by "SAME:nodst:".

  Example:

      #INTERFACE SUBNET          ADDRESS
      eth0       10.0.0.0/8      SAME:nodst:192.0.2.44-192.168.2.50

PROTO

  If specified, must be a protocol number of a protocol name from /etc/protocols. Restricts the SNAT or Masquerade to that protocol.

PORT(S)

  If the PROTO column specifies TCP (6) or UDP (17) then this column may be used to restrict to SNAT or Masquerade to traffic with a certain destination port or a set of destination ports. The column may contain:

  - A port number or a port name from /etc/services.

  - A comma-separated list of port numbers and/or port names. Your kernel must have Multiport match support. You can tell if your kernel has this support by issuing a `shorewall check` command and looking at the output under Shorewall has detected the following iptables/netfilter capabilities:.

  - A range of port numbers of the form <low port>:<high port>

IPSEC

  If you specify a value other than "-" in this column, you must be running kernel 2.6 and your kernel and iptables must include policy match support.

  The value in this column is a comma-separated list of options from the following. Only packets that will be encrypted via an SA that matches these options will have their source address changed.

  - Yes or yes ― Match any SA. Normally used as the only option.

  - reqid=<number> where <number> is specified using setkey(8) using the 'unique:<number>' option for the SPD level.

  - spi=<number> where <number> is the SPI of the SA.

  - proto=ah|esp|ipcomp

  - mode=transport|tunnel

  - tunnel-src=<address>[/<mask>] (only available with mode=tunnel)

  - tunnel-dst=<address>[/<mask>] (only available with mode=tunnel)

  - strict — Means that packets must match all rules.

  - next — Separates rules; can only be used with strict.

### You have eth0 connected to a cable modem and eth1 connected to your local subnetwork 192.168.9.0/24. Your /etc/shorewall/masq file would look like:

    #INTERFACE          SUBNET           ADDRESS
    eth0                192.168.9.0/24

### You have a number of IPSEC tunnels through ipsec0 and you want to masquerade traffic from your 192.168.9.0/24 subnet to the remote subnet 10.1.0.0/16 only.

    #INTERFACE          SUBNET           ADDRESS
    ipsec0:10.1.0.0/16  192.168.9.0/24

### You have a DSL line connected on eth0 and a local network (192.168.10.0/24) connected to eth1. You want all local->net connections to use source address 206.124.146.176.

    #INTERFACE          SUBNET           ADDRESS
    eth0                192.168.10.0/24  206.124.146.176

### Same as example 3 except that you wish to exclude 192.168.10.44 and 192.168.10.45 from the SNAT rule.

    #INTERFACE SUBNET                                      ADDRESS
    eth0       192.168.10.0/24!192.168.10.44,192.168.10.45 206.124.146.176

### You have a second IP address (206.124.146.177) assigned to you and wish to use it for SNAT of the subnet 192.168.12.0/24. You want to give that address the name eth0:0. You must have ADD_SNAT_ALIASES=Yes in .

    #INTERFACE           SUBNET           ADDRESS
    eth0:0               192.168.12.0/24  206.124.146.177

### You want to use both 206.124.146.177 and 206.124.146.179 for SNAT of the subnet 192.168.12.0/24. Each address will be used on alternate outbound connections.

    #INTERFACE            SUBNET          ADDRESS
    eth0                  192.168.12.0/24 206.124.146.177,206.124.146.179

### You want all outgoing SMTP traffic entering the firewall on eth1 to be sent from eth0 with source IP address 206.124.146.177. You want all other outgoing traffic from eth1 to be sent from eth0 with source IP address 206.124.146.176.

    #INTERFACE            SUBNET          ADDRESS            PROTO  PORT(S)
    eth0                  eth1            206.124.146.177    tcp    25
    eth0                  eth1            206.124.146.176

Note that the order of the entries in the above example is important.

## /etc/shorewall/proxyarp

If you want to use proxy ARP on an entire sub-network, I suggest that you look at the Proxy ARP Subnet Mini HOWTO. If you decide to use the technique described in that HOWTO, you can set the proxy_arp flag for an interface (`/proc/sys/net/ipv4/conf/`<interface>`/proxy_arp`) by including the proxyarp option in the interface's record in . When using Proxy ARP sub-netting, you do NOT include any entries in /etc/shorewall/proxyarp.

The `/etc/shorewall/proxyarp` file is used to define Proxy ARP. The file is typically used for enabling Proxy ARP on a small set of systems since you need one entry in this file for each system using proxy ARP. Columns are:

ADDRESS

  address of the system.

INTERFACE

  the interface that connects to the system. If the interface is obvious from the subnetting, you may enter - in this column.

EXTERNAL

  the external interface that you want to honor ARP requests for the ADDRESS specified in the first column.

HAVEROUTE

  If you already have a route through INTERFACE to ADDRESS, this column should contain Yes or yes. If you want Shorewall to add the route, the column should contain No or no.

PERSISTENT

  If you specify "No" or "no" in the HAVEROUTE column, Shorewall will automatically add a route to the host in the ADDRESS column through the interface in the INTERFACE column. If you enter No or no in the PERSISTENT column or if you leave the column empty, that route will be deleted if you issue a `shorewall stop` or `shorewall clear` command. If you place Yes or yes in the PERSISTENT column, then those commands will not cause the route to be deleted.

After you have made a change to the `/etc/shorewall/proxyarp file`, you may need to flush the ARP cache of all routers on the LAN segment connected to the interface specified in the EXTERNAL column of the change/added entry(s). If you are having problems communicating between an individual host (A) on that segment and a system whose entry has changed, you may need to flush the ARP cache on host A as well.

ISPs typically have ARP configured with long TTL (hours!) so if your ISPs router has a stale cache entry (as seen using tcpdump -nei <external interface> host <IP addr>), it may take a long while to time out. I personally have had to contact my ISP and ask them to delete a stale entry in order to restore a system to working order after changing my proxy ARP settings.

### You have public IP addresses 155.182.235.0/28. You configure your firewall as follows:

    eth0 - 155.186.235.1 (internet connection) eth1 -
          192.168.9.0/24 (masqueraded local systems) eth2 - 192.168.10.1
          (interface to your DMZ)

In your DMZ, you want to install a Web/FTP server with public address 155.186.235.4. On the Web server, you subnet just like the firewall's eth0 and you configure 155.186.235.1 as the default gateway. In your `/etc/shorewall/proxyarp` file, you will have:

    #ADDRESS       INTERFACE        EXTERNAL          HAVEROUTE
    155.186.235.4  eth2             eth0              NO

You may want to configure the servers in your DMZ with a subnet that is smaller than the subnet of your internet interface. See the Proxy ARP Subnet Mini HOWTO for details. In this case you will want to place Yes in the HAVEROUTE column.

## /etc/shorewall/nat

The `/etc/shorewall/nat` file is used to define one-to-one NAT. There is one entry in the file for each one-to-one NAT relationship that you wish to define. In order to make use of this feature, you must have NAT enabled.

If all you want to do is forward ports to servers behind your firewall, you do NOT want to use one-to-one NAT. Port forwarding can be accomplished with simple entries in the rules file. Also, in most cases Proxy ARP provides a superior solution to one-to-one NAT because the internal systems are accessed using the same IP address internally and externally.

Columns in an entry are:

EXTERNAL

  External IP address

  This should NOT be the primary IP address of the interface named in the next column.

INTERFACE

  Interface that you want the EXTERNAL IP address to appear on. If you have set ADD_IP_ALIASES=Yes in , you can specify an alias label of the form interfacename:digit (e.g., eth0:0) and Shorewall will create the alias with that label. Alias labels created in this way allow the alias to be visible to the ipconfig utility. THAT IS THE ONLY THING THAT THIS LABEL IS GOOD FOR AND IT MAY NOT APPEAR ANYWHERE ELSE IN YOUR SHOREWALL CONFIGURATION.

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

  Example:

      eth0:

INTERNAL

  Internal IP address.

ALL INTERFACES

  If Yes or yes, NAT will be effective from all hosts. If No or no (or if left empty) then NAT will be effective only through the interface named in the INTERFACE column.

LOCAL

  If Yes or yes, NAT will be effective from the firewall system. Note that with Shorewall 2.0.1 and earlier versions, this column was ignored if the ALL INTERFACES column did not contain "Yes" or "yes". This column's contents are independent of the value in ALL INTERFACES.

Look here for additional information and an example.

## /etc/shorewall/tunnels

The /etc/shorewall/tunnels file allows you to define IPSec, GRE, IPIP, OpenVPN, PPTP, 6to4 and other tunnels with end-points on your firewall.

For an overview of Shorewall's VPN support, try this article.

Instructions for setting up IPSEC tunnels may be found here (if you are using kernel 2.6 with native IPSEC support, look here), instructions for IPIP and GRE tunnels are here, instructions for OpenVPN tunnels are here, instructions for PPTP tunnels are here, instructions for 6to4 tunnels are here, and instructions for integrating Shorewall with other types of tunnels are here.

## /etc/shorewall/shorewall.conf

See also the description of /etc/shorewall-lite/shorewall-lite.conf.

This file is used to set the following firewall parameters:

ACCEPT_DEFAULT, DROP_DEFAULT, QUEUE_DEFAULT and REJECT_DEFAULT (Added in version 3.4.0)

  These options specify the default action or default macro for ACCEPT, DROP, QUEUE and REJECT policies respectively. If not specified, the following defaults are used:

  - ACCEPT_DEFAULT=none

  - DROP_DEFAULT=Drop

  - QUEUE_DEFAULT=none

  - REJECT_DEFAULT=Reject

  The special value "none" is used to indicate that no default action/default macro should be used.

  For more information on this topic, see the `/etc/shorewall/policy` section above.

ADD_IP_ALIASES

  This parameter determines whether Shorewall automatically adds the external address(es) in . If the variable is set to Yes or yes then Shorewall automatically adds these aliases. If it is set to No or no, you must add these aliases yourself using your distribution's network configuration tools.

  If this variable is not set or is given an empty value (ADD_IP_ALIASES="") then ADD_IP_ALIASES=Yes is assumed.

  Addresses added by ADD_IP_ALIASES=Yes are deleted and re-added during `shorewall restart`. As a consequence, connections using those addresses may be severed.

ADD_SNAT_ALIASES

  This parameter determines whether Shorewall automatically adds the SNAT ADDRESS in . If the variable is set to Yes or yes then Shorewall automatically adds these addresses. If it is set to No or no, you must add these addresses yourself using your distribution's network configuration tools.

  If this variable is not set or is given an empty value (ADD_SNAT_ALIASES="") then ADD_SNAT_ALIASES=No is assumed.

  Addresses added by ADD_SNAT_ALIASES=Yes are deleted and re-added during `shorewall restart`. As a consequence, connections using those addresses may be severed.

ADMINISABSENTMINDED

  The value of this variable affects Shorewall's stopped state. When ADMINISABSENTMINDES=No, only traffic to/from those addresses listed in /etc/shorewall/routestopped is accepted when Shorewall is stopped. When ADMINISABSENTMINDED=Yes, in addition to traffic to/from addresses in `/etc/shorewall/routestopped`, connections that were active when Shorewall stopped continue to work and all new connections from the firewall system itself are allowed. If this variable is not set or is given the empty value then ADMINISABSENTMINDED=No is assumed.

BLACKLIST_DISPOSITION

  This parameter determines the disposition of packets from blacklisted hosts. It may have the value DROP if the packets are to be dropped or REJECT if the packets are to be replied with an ICMP port unreachable reply or a TCP RST (tcp only). If you do not assign a value or if you assign an empty value then DROP is assumed.

BLACKLIST_LOGLEVEL

  This parameter determines if packets from blacklisted hosts are logged and it determines the syslog level that they are to be logged at. Its value is a syslog level (Example: BLACKLIST_LOGLEVEL=debug). If you do not assign a value or if you assign an empty value then packets from blacklisted hosts are not logged.

BRIDGING

  When set to Yes or yes, enables Shorewall Bridging support.

CLAMPMSS[=<value>]

  This parameter enables the TCP Clamp MSS to PMTU feature of Netfilter and is usually required when your internet connection is through PPPoE or PPTP. If set to Yes or yes, the feature is enabled. If left blank or set to No or no, the feature is not enabled.

  This option requires CONFIG_IP_NF_TARGET_TCPMSS in your kernel.

  You may also set CLAMPMSS to a numeric value (e.g., CLAMPMSS=1400). This will set the MSS field in TCP SYN packets going through the firewall to the value that you specify.

CLEAR_TC

  If this option is set to No then Shorewall won't clear the current traffic control rules during [re]start. This setting is intended for use by people that prefer to configure traffic shaping when the network interfaces come up rather than when the firewall is started. If that is what you want to do, set TC_ENABLED=Yes and CLEAR_TC=No and do not supply an `/etc/shorewall/tcstart` file. That way, your traffic shaping rules can still use the fwmark classifier based on packet marking defined in /etc/shorewall/tcrules. If not specified, CLEAR_TC=Yes is assumed.

CONFIG_PATH

  Specifies where configuration files other than `shorewall.conf` may be found. CONFIG_PATH is specifies as a list of directory names separated by colons (":"). When looking for a configuration file other than shorewall.conf:

  - If the command is "try" or if "-c <configuration directory>" was specified in the command then the directory given in the command is searched first.

  - Next, each directory in the CONFIG_PATH setting is searched in sequence.

  If CONFIG_PATH is not given or if it is set to the empty value then the contents of `/usr/share/shorewall/configpath` are used. As released from shorewall.net, that file sets the CONFIG_PATH to /etc/shorewall:/usr/share/shorewall but your particular distribution may set it differently. See the output of `shorewall show config` for the default on your system.

  Note that the setting in `/usr/share/shorewall/configpath` is always used to locate `shorewall.conf`.

DELAYBLACKLISTLOAD

  Users with a large static black list (`/etc/shorewall/blacklist`) may want to set the DELAYBLACKLISTLOAD option to Yes. 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`.

DETECT_DNAT_ADDRS

  If set to Yes or yes, Shorewall will detect the first IP address of the interface to the source zone and will include this address in DNAT rules as the original destination IP address. If set to No or no, Shorewall will not detect this address and any destination IP address will match the DNAT rule. If not specified or empty, DETECT_DNAT_ADDRS=Yes is assumed.

DYNAMIC_ZONES

  When set to Yes or yes, enables dynamic zones. DYNAMIC_ZONES=Yes is not allowed in configurations that will run under Shorewall Lite.

FASTACCEPT

  Normally, Shorewall accepting ESTABLISHED/RELATED packets until these packets reach the chain in which the original connection was accepted. So for packets going from the 'loc' zone to the 'net' zone, ESTABLISHED/RELATED packets are ACCEPTED in the 'loc2net' chain.

  If you set FASTACCEPT=Yes, then ESTABLISHED/RELEATED packets are accepted early in the INPUT, FORWARD and OUTPUT chains. If you set FASTACCEPT=Yes then you may not include rules in the ESTABLISHED or RELATED sections of /etc/shorewall/rules.

HIGH_ROUTE_MARKS (Added in version 3.2.0)

  Prior to version 3.2.0, it was not possible to use connection marking in `/etc/shorewall/tcrules` if you have a multi-ISP configuration that uses the track option.

  Beginning with release 3.2.0, you may now set HIGH_ROUTE_MARKS=Yes in to effectively divide the packet mark and connection mark into two 8-byte mark fields.

  When you do this:

  1. The MARK field in the `providers` file must have a value that is less than 65536 and that is a multiple of 256 (using hex representation, the values are 0x0100-0xFF00 with the low-order 8 bits being zero).

  2. You may only set those mark values in the PREROUTING chain.

  3. Marks used for traffic shaping must still be in the range of 1-255 and may still not be set in the PREROUTING chain.

  4. When you SAVE or RESTORE in tcrules, only the TC mark value is saved or restored. Shorewall handles saving and restoring the routing (provider) marks.

IMPLICIT_CONTINUE (Added in version 3.2.0)

  When this option is set to "Yes", it causes subzones to be treated differently with respect to policies.

  Subzones are defined by following their name with ":" and a list of parent zones (in /etc/shorewall/zones). Normally, you want to have a set of special rules for the subzone and if a connection doesn't match any of those subzone-specific rules then you want the parent zone rules and policies to be applied. With IMPLICIT_CONTINUE=Yes, that happens automatically.

  If IMPLICIT_CONTINUE=No or if IMPLICIT_CONTINUE is not set, then subzones are not subject to this special treatment. With IMPLICIT_CONTINUE=Yes, an implicit CONTINUE policy may be overridden by including an explicit policy (one that does not specify "all" in either the SOURCE or the DEST columns).

  Example:

  > `/etc/shorewall/zones`:

  >     #ZONE      TYPE
  >     prnt       ipv4
  >     chld:prnt  ipv4

  > Traffic to/from the chld zone will first pass through the applicable chld rules and if none of those rules match then it will be passed through the appropriate prnt rules. If the connection request does not match any of the prnt rules then the relevant prnt policy is applied.

  > If you want the fw->chld policy to be ACCEPT, simply add this entry to `/etc/shorewall/policy`:

  >     #SOURCE  DESTINATION        POLICY
  >     $FW      chld               ACCEPT

  > Traffic from all other zones to 'chld' will be subject to the implicit CONTINUE policy.

IP_FORWARDING

  This parameter determines whether Shorewall enables or disables IPV4 Packet Forwarding (/proc/sys/net/ipv4/ip_forward). Possible values are:

  On or on

    packet forwarding will be enabled.

  Off or off

    packet forwarding will be disabled.

  Keep or keep

    Shorewall will neither enable nor disable packet forwarding.

  If this variable is not set or is given an empty value (IP_FORWARD="") then IP_FORWARD=On is assumed.

IPTABLES

  This parameter names the iptables executable to be used by Shorewall. If not specified or if specified as a null value, then the iptables executable located using the PATH option is used.

LOG_MARTIANS

  If set to Yes or yes, sets `/proc/sys/net/ipv4/conf/all/log_martians` and `/proc/sys/net/ipv4/conf/default/log_martians` to 1. Default is which sets both of the above to zero. If you do not enable martian logging for all interfaces, you may still enable it for individual interfaces using the logmartians interface option in /etc/shorewall/interfaces.

LOGALLNEW

  When set to a log level, this option causes Shorewall to generate 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 pref

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

      Shorewall:nat:PREROUTING

  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.

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

LOGFILE

  This parameter tells the /sbin/shorewall program where to look for Shorewall messages when processing the show log, monitor, status and hits commands. If not assigned or if assigned an empty value, /var/log/messages is assumed.

LOGFORMAT

  The value of this variable generate the --log-prefix setting for Shorewall logging rules. It contains a printf formatting template which accepts three arguments (the chain name, logging rule number (optional) and the disposition). To use LOGFORMAT with fireparse, set it as:

      LOGFORMAT="fp=%s:%d a=%s "

  If the LOGFORMAT value contains the substring %d then the logging rule number is calculated and formatted in that position; if that substring is not included then the rule number is not included. If not supplied or supplied as empty (LOGFORMAT="") then Shorewall:%s:%s: is assumed.

  In Shorewall major versions prior to 3.4, `/sbin/shorewall` uses the leading part of the LOGFORMAT string (up to but not including the first %) to find log messages in the show log, status and hits commands. This part should not be omitted (the LOGFORMAT should not begin with %) and the leading part should be sufficiently unique for `/sbin/shorewall` to identify Shorewall messages.

LOGRATE and LOGBURST

  These parameters set the match rate and initial burst size for logged packets. Please see the iptables man page for a description of the behavior of these parameters (the iptables option --limit is set by LOGRATE and --limit-burst is set by LOGBURST). If both parameters are set empty, no rate-limiting will occur.

  ###

      LOGRATE=10/minute
      LOGBURST=5

  For each logging rule, the first time the rule is reached, the packet will be logged; in fact, since the burst is 5, the first five packets will be logged. After this, it will be 6 seconds (1 minute divided by the rate of 10) before a message will be logged from the rule, regardless of how many packets reach it. Also, every 6 seconds which passes without matching a packet, one of the bursts will be regained; if no packets hit the rule for 30 seconds, the burst will be fully recharged; back where we started.

MACLIST_DISPOSITION

  Determines the disposition of connections requests that fail MAC Verification and must have the value ACCEPT (accept the connection request anyway), REJECT (reject the connection request) or DROP (ignore the connection request). If not set or if set to the empty value (e.g., MACLIST_DISPOSITION="") then MACLIST_DISPOSITION=REJECT is assumed.

MACLIST_LOG_LEVEL

  Determines the syslog level for logging connection requests that fail MAC Verification. The value must be a valid syslogd log level. If you don't want to log these connection requests, set to the empty value (e.g., MACLIST_LOG_LEVEL="").

MACLIST_TABLE

  Normally, MAC verification occurs in the filter table (INPUT and FORWARD) chains. When forwarding a packet from an interface with MAC verification to a bridge interface, that doesn't work.

  This problem can be worked around by setting MACLIST_TABLE=mangle which will cause Mac verification to occur out of the PREROUTING chain. Because REJECT isn't available in that environment, you may not specify MACLIST_DISPOSITION=REJECT with MACLIST_TABLE=mangle.

MACLIST_TTL

  The performance of configurations with a large numbers of entries in /etc/shorewall/maclist can be improved by setting the MACLIST_TTL variable in /etc/shorewall/shorewall.conf.

  If your iptables and kernel support the "Recent Match" (see the output of "shorewall check" near the top), you can cache the results of a 'maclist' file lookup and thus reduce the overhead associated with MAC Verification.

  When a new connection arrives from a 'maclist' interface, the packet passes through then list of entries for that interface in /etc/shorewall/maclist. If there is a match then the source IP address is added to the 'Recent' set for that interface. Subsequent connection attempts from that IP address occurring within $MACLIST_TTL seconds will be accepted without having to scan all of the entries. After $MACLIST_TTL from the first accepted connection request from an IP address, the next connection request from that IP address will be checked against the entire list.

  If MACLIST_TTL is not specified or is specified as empty (e.g, MACLIST_TTL="" or is specified as zero then 'maclist' lookups will not be cached).

MARK_IN_FORWARD_CHAIN

  If your kernel has a FORWARD chain in the mangle table, you may set MARK_IN_FORWARD_CHAIN=Yes to cause the marking specified in the tcrules file to occur in that chain rather than in the PREROUTING chain. This permits you to mark inbound traffic based on its destination address when SNAT or Masquerading are in use. To determine if your kernel has a FORWARD chain in the mangle table, use the `/sbin/shorewall show mangle` command; if a FORWARD chain is displayed then your kernel will support this option. If this option is not specified or if it is given the empty value (e.g., MARK_IN_FORWARD_CHAIN="") then MARK_IN_FORWARD_CHAIN=No is assumed.

MODULE_SUFFIX

  The value of this variable determines the possible file extensions of kernel modules. The default value is "o gz ko and o.gz". See for more details.

MODULESDIR

  This parameter specifies the directory/directories where your kernel netfilter modules may be found. If you leave the variable empty, Shorewall will supply the value "/lib/modules/`uname -r`/kernel/net/ipv4/netfilter" in versions of Shorewall prior to 3.2.4 and "/lib/modules/`uname -r`/kernel/net/ipv4/netfilter:/lib/modules/`uname -r`/kernel/net/ipv4/netfilter" in later versions.

OPTIMIZE (Added in version 3.4.0)

  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
          0     0 wifi2all   all  --  *      br0     0.0.0.0/0            0.0.0.0/0
          0     0 wifi2all   all  --  *      eth3    0.0.0.0/0            0.0.0.0/0
          0     0 wifi2all   all  --  *      tun+    0.0.0.0/0            0.0.0.0/0
      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

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

  With 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

PKTTYPE

  Normally Shorewall attempts to use the iptables packet type match extension to determine broadcast and multicast packets.

  1. This can cause a message to appear during `shorewall start` (modprobe: cant locate module ipt_pkttype).

  2. Some users have found problems with the packet match extension with the result that their firewall log is flooded with messages relating to broadcast packets.

  If you are experiencing either of these problems, setting PKTTYPE=No will prevent Shorewall from trying to use the packet type match extension and to use IP address matching to determine which packets are broadcasts or multicasts.

RESTOREFILE

  The simple name of a file in`/var/lib/shorewall` to be used as the default restore script in the shorewall save, shorewall restore, shorewall forget and shorewall -f start commands. See the Saved Configuration documentation for details.

RETAIN_ALIASES

  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 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. When RETAIN_ALIASES 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".

RFC1918_LOG_LEVEL

  This parameter determines the level at which packets logged under the norfc1918 mechanism are logged. The value must be a valid syslog level and if no level is given, then info is assumed.

RFC1918_STRICT

  Traditionally, the RETURN target in the 'rfc1918' file has caused norfc1918 processing to cease for a packet if the packet's source IP address matches the rule. Thus, if you have this entry in /etc/shorewall/rfc1918:

      #SUBNETS                 TARGET
      192.168.1.0/24           RETURN

  then traffic from 192.168.1.4 to 10.0.3.9 will be accepted even though you also have:

      #SUBNETS                 TARGET
      10.0.0.0/8               logdrop

  Setting RFC1918_STRICT=Yes in shorewall.conf will cause such traffic to be logged and dropped since while the packet's source matches the RETURN rule, the packet's destination matches the 'logdrop' rule.

  If not specified or specified as empty (e.g., RFC1918_STRICT="") then RFC1918_STRICT=No is assumed.

  RFC1918_STRICT=Yes requires that your kernel and iptables support 'Connection Tracking' match.

ROUTE_FILTER

  If this parameter is given the value Yes or yes then route filtering (anti-spoofing) is enabled on all network interfaces which are brought up while Shorewall is in the started state. The default value is no.

SHOREWALL_SHELL

  This parameter is used to specify the shell program to be used to interpret the firewall script (/usr/share/shorewall/firewall). If not specified or specified as a null value, /bin/sh is assumed.

SMURF_LOG_LEVEL

  Specifies the logging level for smurf packets (see the nosmurfs option in /etc/shorewall/interfaces). If set to the empty value ( SMURF_LOG_LEVEL="" ) then smurfs are not logged.

STARTUP_ENABLED

  When set to Yes or yes, Shorewall may be started. Used as guard against Shorewall being accidentally started before it has been configured.

SUBSYSLOCK

  This parameter should be set to the name of a file that the firewall should create if it starts successfully and remove when it stops. Creating and removing this file allows Shorewall to work with your distribution's initscripts. For RedHat, this should be set to /var/lock/subsys/shorewall. For Debian, the value is /var/state/shorewall and in LEAF it is /var/run/shorwall. Example: SUBSYSLOCK=/var/lock/subsys/shorewall.

TCP_FLAGS_DISPOSITION

  Determines the disposition of TCP packets that fail the checks enabled by the tcpflags interface option and must have a value of ACCEPT (accept the packet), REJECT (send an RST response) or DROP (ignore the packet). If not set or if set to the empty value (e.g., TCP_FLAGS_DISPOSITION="") then TCP_FLAGS_DISPOSITION=DROP is assumed.

TCP_FLAGS_LOG_LEVEL

  Determines the syslog level for logging packets that fail the checks enabled by the tcpflags interface option. The value must be a valid syslogd log level. If you don't want to log these packets, set to the empty value (e.g., TCP_FLAGS_LOG_LEVEL="").

USE_ACTIONS (Added in version 3.4.0)

  If set to 'Yes' (the default) then user-defined and standard actions may be used. If set to 'No', only built-in actions may be used. See the action documentation for additional information.

  If this option is not set, or if it is set to the empty value, then USE_ACTIONS=Yes is assumed.

VERBOSITY (Added in version 3.2.0)

  Shorewall has traditionally been very noisy (produced lots of output). You may now set the default level of verbosity using the VERBOSITY OPTION.

  Values are:

  - 0 — Silent. You may make it more verbose using the -v option
  - 1 — Major progress messages displayed
  - 2 — All progress messages displayed (old default behavior)

  If not specified, then 2 is assumed.

## /etc/shorewall/modules Configuration

The file `/etc/shorewall/modules` contains commands for loading the kernel modules required by Shorewall-defined firewall rules. Shorewall will source this file during start/restart provided that it exists and that the directory specified by the MODULESDIR parameter exists (see above).

This file was moved to `/usr/share/shorewall` in Shorewall version 3.2.0.

If you have an earlier kernel but need to modify the modules file, then copy `/usr/share/shorewall/modules` to `/etc/shorewall/modules` and modify the copy.

The file that is released with Shorewall calls the Shorewall function loadmodule for the set of modules that I load.

The loadmodule function is called as follows:

    loadmodule <modulename> [ <module parameters> ]

where

<modulename>

  is the name of the modules without the trailing .o (example ip_conntrack).

<module parameters>

  Optional parameters to the insmod utility.

The function determines if the module named by <modulename> is already loaded and if not then the function determines if the .o file corresponding to the module exists in the <moduledirectory>; if so, then the following command is executed:

    insmod <moduledirectory>/<modulename>.o <module parameters>

If the file doesn't exist, the function determines of the .o.gz file corresponding to the module exists in the moduledirectory. If it does, the function assumes that the running configuration supports compressed modules and execute the following command:

    insmod <moduledirectory>/<modulename>.o.gz <module parameters>

The value of the MODULE_SUFFIX option in determines which files the loadmodule function looks for if the named module doesn't exist. For each file <extension> listed in MODULE_SUFFIX (default "o gz ko o.gz"), the function will append a period (".") and the extension and if the resulting file exists then the following command will be executed:

    insmod moduledirectory/<modulename>.<extension> <module parameters>

## /etc/shorewall/tos Configuration

This Shorewall feature is somewhat broken -- while it shouldn't hurt anything to use it, it may not do what you want either.

In versions of Shorewall prior to 3.2.4, it is only safe to specify "all" in the SOURCE and DEST columns. In 3.2.4 and later versions:

- It continues to work fine if you specify "all" in both the SOURCE and DEST columns.

- It mostly works when you specify zone names in either column (provided that you have Mangle table FORWARD chain support in your kernel) but it doesn't work with dynamic zones and it doesn't work with IPSEC zones.

- If you specify a zone name together with an address in the SOURCE or DEST column, the generated rule ignores the zone name and simply matches on the source or destination address.

The `/etc/shorewall/tos` file allows you to set the Type of Service field in packet headers based on packet source, packet destination, protocol, source port and destination port. In order for this file to be processed by Shorewall, you must have mangle support enabled.

Entries in the file have the following columns:

SOURCE

  The source zone. May be qualified by following the zone name with a colon (:) and either an IP address, an IP subnet, a MAC address in Shorewall Format or the name of an interface. This column may also contain the name of the firewall zone to indicate packets originating on the firewall itself or all to indicate any source.

DEST

  The destination zone. May be qualified by following the zone name with a colon (:) and either an IP address or an IP subnet. This column may also contain all to indicate any destination.

PROTOCOL

  The name of a protocol in `/etc/protocols` or the protocol's number.

SOURCE PORT(S)

  The source port or a port range. For all ports, place a hyphen (-) in this column.

DEST PORT(S)

  The destination port or a port range. To indicate all ports, place a hyphen (-) in this column.

TOS

  The type of service. Must be one of the following:

  - Minimize-Delay (16)
  - Maximize-Throughput (8)
  - Maximize-Reliability (4)
  - Minimize-Cost (2)
  - Normal-Service (0)

Here's a sample `/etc/shorewall/tos` file:

    #SOURCE  DEST    PROTOCOL    SOURCE PORTS(S)   DEST PORTS(S)   TOS
    all      all     tcp         -                 ssh             16
    all      all     tcp         ssh               -               16
    all      all     tcp         -                 ftp             16
    all      all     tcp         ftp               -               16
    all      all     tcp         -                 ftp-data        8
    all      all     tcp         ftp-data          -               8

Users have reported that odd routing problems result from adding the ESP and AH protocols to the `/etc/shorewall/tos` file.

## /etc/shorewall/blacklist

Each line in `/etc/shorewall/blacklist` contains an IP address, a MAC address in Shorewall Format or subnet address.

###

    130.252.100.69
    206.124.146.0/24

Packets from hosts listed in the blacklist file will be disposed of according to the value assigned to the BLACKLIST_DISPOSITION and BLACKLIST_LOGLEVEL variables in /etc/shorewall/shorewall.conf. Only packets arriving on interfaces that have the blacklist option in `/etc/shorewall/interfaces` are checked against the blacklist. The black list is designed to prevent listed hosts/subnets from accessing services on your network.

The blacklist file has three columns:

ADDRESS/SUBNET

  As described above.

PROTOCOL

  Optional. If specified, only packets specifying this protocol will be blocked.

PORTS

  Optional; may only be given if PROTOCOL is tcp or udp. Expressed as a comma-separated list of destination port numbers or service names (from /etc/services). If present, only packets matching the specified protocol and one of the listed destination ports are blocked.

Shorewall also has a dynamic blacklist capability.

The Shorewall blacklist file is NOT designed to police your users' web browsing -- to do that, I suggest that you install and configure Squid with SquidGuard.

## /usr/share/shorewall/rfc1918

This file lists the subnets affected by the norfc1918 interface option. Columns in the file are:

SUBNET

  The subnet using VLSM notation (e.g., 192.168.0.0/16).

TARGET

  What to do with packets to/from the SUBNET:

  RETURN

    Process the packet normally thru the rules and policies. See also RFC1918_STRICT above.

  DROP

    Silently drop the packet.

  logdrop

    Log then drop the packet -- see the RFC1918_LOG_LEVEL parameter above.

If you want to modify this file, DO NOT MODIFY `/usr/share/shorewall/rfc1918`. Rather copy that file to `/etc/shorewall/rfc1918` and modify the copy.

## /etc/shorewall/netmap

Network mapping is defined using the `/etc/shorewall/netmap` file. Columns in this file are:

TYPE

  Must be DNAT or SNAT.

  If DNAT, traffic entering INTERFACE and addressed to NET1 has it's destination address rewritten to the corresponding address in NET2.

  If SNAT, traffic leaving INTERFACE with a source address in NET1 has it's source address rewritten to the corresponding address in NET2.

NET1

  Must be expressed in CIDR format (e.g., 192.168.1.0/24).

INTERFACE

  A firewall interface. This interface must have been defined in `/etc/shorewall/interfaces`.

NET2

  A second network expressed in CIDR format.

For more information, see the Network Mapping documentation.

## /etc/shorewall/routestopped

This file defines the hosts that are accessible from the firewall when the firewall is stopped. Entries in this file are also active while Shorewall is being stopped or [re]started.

Columns in the file are:

INTERFACE

  The firewall interface through which the host(s) communicate with the firewall.

HOST(S) - (Optional)

  A comma-separated list of IP/Subnet addresses. If not supplied or supplied as - then 0.0.0.0/0 is assumed.

OPTIONS - (Optional)

  A comma-separated list of options. The currently-supported options are:

  - routeback - Set up a rule to ACCEPT traffic from these hosts back to themselves.

  - source - Allow traffic from these hosts to ANY destination. Without this option or the 'dest' option, only traffic from this host to other listed hosts (and the firewall) is allowed. If 'source' is specified then 'routeback' is redundant.

  - dest - Allow traffic to these hosts from ANY source. Without this option or the 'source' option, only traffic from this host to other listed hosts (and the firewall) is allowed. If 'dest' is specified then 'routeback' is redundant.

  - critical - Allow traffic between the firewall and these hosts throughout '[re]start', 'stop' and 'clear'. Specifying 'critical' on one or more entries will cause your firewall to be "totally open" for a brief window during each of those operations. Examples of where you might want to use this are:

    - 'Ping' nodes with heartbeat.

    - LDAP server(s) if you use LDAP Authentication

    - NFS Server if you have an NFS-mounted root filesystem.

### When your firewall is stopped, you want firewall accessibility from local hosts 192.168.1.0/24 and from your DMZ. Your DMZ interfaces through eth1 and your local hosts through eth2.

    #INTERFACE          HOST(S)
    eth2                192.168.1.0/24
    eth1                -

Shorewall allows connections defined by the contents of `/etc/shorewall/routestopped` during the potentially lengthy processing of the commands `shorewall start`, `shorewall restart`, `shorewall try` and `shorewall stop`.

## /etc/shorewall/maclist

This file is described in the MAC Validation Documentation.

## /etc/shorewall/ecn

This file is described in the ECN Control Documentation.

## /etc/shorewall/accounting

This file is described in the Traffic Accounting Documentation.