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

There are a number of files that comprise the operational components of Shorewall. /sbin/shorewall — The program that you use to interact with Shorewall. Normally the root user's PATH includes /sbin and the program can be run from a shell prompt by simply typing shorewall followed by a command. In some releases of KDE, the default configuration of the konsole program is brain dead with respect to the "Root Console". It executes the command "su" where it should execute "su -"; the latter will cause a login shell to be created which will in turn set PATH properly. You can correct this problem as follows: Click on "Settings" on the toolbar and select "Configure Konsole" Select the "Session" tab. Click on "Root Console" Change the Execute command from "su" to "su -" Click on "Save Session" Click on "Ok" To see a list of supported commands, use the help command: shorewall help To get further information about a particular command, follow help by the command: shorewall help start /etc/shorewall — The default directory where Shorewall looks for configuration files. See the sections entitled Additional Configuration Directories and Alternate Configuration Directories for information about how you can direct Shorewall to look in other directories. /etc/init.d/shorewall (/etc/rc.d/firewall.rc on Slackware) — The script run by init (the program responsible for startup and shutdown of your system) to start Shorewall at boot time and to stop Shorewall at shutdown. /usr/share/shorewall/firewall — The program responsible for configuring Netfilter based on your configuration files. /usr/share/shorewall/functions — A library of Bourne Shell functions used by both /sbin/shorewall and /usr/share/shorewall/firewall.

As explained in the Introduction, Shorewall is not something that runs all of the time in your system. Nevertheless, for integrating Shorewall into your initialization scripts it is useful to speak of starting Shorewall and stopping Shorewall. Shorewall is started using the shorewall start command. Once the start command completes successfully, Netfilter is configured as described in your Shorewall configuration files. If there is an error during shorewall start, then if you have a saved configuration then that configuration is restored. Otherwise, an implicit shorewall stop is executed. Shorewall is stopped using the shorewall stop command. The shorewall stop command does not remove all netfilter rules and open your firewall for all traffic to pass. It rather places your firewall in a safe state defined by the contents of your /etc/shorewall/routestopped file and the setting of ADMINISABSENTMINDED in /etc/shorewall/shorewall.conf. If you want to remove all Netfilter rules and open your firewall for all traffic to pass, use the shorewall clear command. If you change your configuration and want to install the changes, use the shorewall restart command. For additional information, see the Shorewall State Diagram section.

If you include the word trace as the first parameter to an /sbin/shorewall command that transfers control to /usr/share/shorewall/firewall, execution of the latter program will be traced to STDERR. To trace the execution of shorewall start and write the trace to the file /tmp/trace, you would enter:shorewall trace start 2> /tmp/trace

The .rpm, .deb and .tgz all try to configure your startup scripts so that Shorewall will start automatically at boot time. If you are using the install.sh script from the .tgz and it cannot determine how to configure automatic startup, a message to that effect will be displayed. You will need to consult your distribution's documentation to see how to integrate the /etc/init.d/shorewall script into the distribution's startup mechanism. Shorewall startup is disabled by default. Once you have configured your firewall, you can enable startup by removing the file /etc/shorewall/startup_disabled. Note: Users of the .deb package must edit /etc/default/shorewall and set startup=1 while users who are running Shorewall 2.1.3 or later must edit /etc/shorewall/shorewall.conf and set STARTUP_ENABLED=Yes. If you use dialup or some flavor of PPP where your IP address can change arbitrarily, you may want to start the firewall in your /etc/ppp/ip-up.local script. I recommend just placing /sbin/shorewall restart in that script.

Once you have Shorewall working the way that you want it to, you can use shorewall save to save the commands necessary to recreate that configuration in a restore script. In its simplest form, the save command is just: shorewall save That command creates the default restore script, /var/lib/shorewall/restore. The default may be changed using the RESTOREFILE option in /etc/shorewall/shorewall.conf. A different file name may also be specified in the save command: shorewall save <filename> Where <filename> is a simple file name (no slashes). Once created, the default restore script serves several useful purposes: If you change your configuration and there is an error when you try to restart Shorewall, the restore script will be run to restore your firewall to working order. Bootup is faster. The -f option of the start command (e.g., shorewall -f start) causes Shorewall to look for the default restore script and if it exists, the script is run. This is much faster than starting Shorewall using the normal mechanism of reading the configuration files and running iptables dozens or even hundreds of times. By default, /etc/init.d/shorewall (/etc/rc.d/firewall.rc) uses the -f option when it is processing a request to start Shorewall. The shorewall restore command can be used at any time to quickly configure the firewall. shorewall restore [ <filename> ] If no <filename> is given, the default restore script is used. Otherwise, the script /var/lib/shorewall/<filename> is used. The ability to have multiple restore scripts means that you can save different Shorewall firewall configurations and switch between them quickly using the restore command. Restore scripts may be removed using the shorewall forget command: shorewall forget [ <filename> ] If no <filename> is given, the default restore script is removed. Otherwise, /var/lib/shorewall/<filename> is removed (of course, you can also use the Linux rm command from the shell prompt to remove these files).

The CONFIG_PATH setting in /etc/shorewall/shorewall.conf determines where Shorewall looks for configuration files. The default setting is CONFIG_PATH=/etc/shorewall:/usr/share/shorewall which means that /etc/shorewall is searched first and if the file is not found then /usr/share/shorewall is searched. You can change the value of CONFIG_PATH to cause additional directories to be searched but CONFIG_PATH should always include both /etc/shorewall and /usr/share/shorewall. When an alternate configuration directory is specified as described in the next section, that directory is searched before those directories listed in CONFIG_PATH. Example - Search /etc/shorewall, /etc/shorewall/actiondir and /usr/share/shorewall in that order: CONFIG_PATH=/etc/shorewall:/etc/shorewall/actiondir:/usr/share/shorewall The above is the setting that I use and it allows me to place all of my user-defined 'action.' files in /etc/shorewall/actiondir.

As explained above, Shorewall normally looks for configuration files in the directories specified by the CONFIG_PATH option in /etc/shorewall/shorewall.conf. The shorewall start, shorewall restart, shorewall check, and shorewall try commands allow you to specify an additional directory for Shorewall to check before looking in the directories listed in CONFIG_PATH. Shorewall versions before Shorewall 2.2.0: shorewall [ -c <configuration-directory> ] {start|restart|check} shorewall try <configuration-directory> [ <timeout> ] Shorewall versions 2.2.0 and later the -c option is deprecated: shorewall {start|restart|check} <configuration-directory> shorewall try <configuration-directory> [ <timeout> ] If a <configuration-directory> is specified, each time that Shorewall is going to use a file in /etc/shorewall it will first look in the <configuration-directory> . If the file is present in the <configuration-directory>, that file will be used; otherwise, the file in /etc/shorewall will be used. When changing the configuration of a production firewall, I recommend the following: If you haven't saved the current working configuration, do so using shorewall save. mkdir /etc/test cd /etc/test <copy any files that you need to change from /etc/shorewall to . and change them here> shorewall check ./ <correct any errors found by check and check again> shorewall try ./ If the configuration starts but doesn't work, just shorewall restart to restore the old configuration. If the new configuration fails to start, the try command will automatically restore your configuration. When the new configuration works then just: cp -f * /etc/shorewall cd rm -rf /etc/test shorewall save

add shorewall add <interface>[:<host-list>] … <zone> A <host-list> is a comma-separated list whose entries are: A host or network address The name of a bridge port The name of a bridge port followed by a colon (":") and a host or network address. Adds an interface (and list of hosts if included) to a dynamic zone usually used with VPN's. Note that there was no provision in the syntax for specifying a bridge port prior to Shorewall versions 2.0.12 and 2.2.0 Beta 7 and that the "shorewall add" command was not supported for hosts connected to the firewall through a bridge port prior to those releases. Example: shorewall add ipsec0:192.0.2.24 vpn1 adds the address 192.0.2.24 from interface ipsec0 to the zone vpn1. allow shorewall allow <address> ... Re-enables receipt of packets from hosts previously blacklisted by a drop or reject command. Shorewall allow, drop, rejct and save implement dynamic blacklisting. check (Shorewall versions prior to 2.2.0) shorewall [ -c <configuration-directory> ] check Performs a cursory validation of the zones, interfaces, hosts, rules and policy files. Use this if you are unsure of any edits you have made to the shorewall configuration. See above for a recommended way to make changes. check (Shorewall 2.2.0 and later) shorewall [-q] check [ <configuration-directory> ] Performs a cursory validation of the zones, interfaces, hosts, rules and policy files. Use this if you are unsure of any edits you have made to the shorewall configuration. See above for a recommended way to make changes. clear shorewall clear Clear will remove all rules and chains installed by Shorewall. The firewall is then wide open and unprotected. Existing connections are untouched. Clear is often used to see if the firewall is causing connection problems. delete shorewall delete <interface>[:<host-list>] … <zone> A <host-list> is a comma-separated list whose entries are: A host or network address The name of a bridge port The name of a bridge port followed by a colon (":") and a host or network address. Deletes the specified interface (and host list if included) from the specified zone. Note that there was no provision in the syntax for specifying a bridge port prior to Shorewall versions 2.0.12 and 2.2.0 Beta 7 and that the "shorewall delete" command was not supported for hosts connected to the firewall through a bridge port prior to those releases. Example: shorewall delete ipsec0:192.0.2.24 vpn1 deletes the address 192.0.2.24 from interface ipsec0 from zone vpn1 drop shorewall drop <address> ... Causes packets from the specified <address> to be ignored forget shorewall forget [ <filename> ] Deletes /var/lib/shorewall/<filename>. If no <filename> is given then the file specified by RESTOREFILE in /etc/shorewall/shorewall.conf is removed. help shorewall help [<command> | host | address ] Display helpful information about the shorewall commands. hits hits Produces several reports about the Shorewall packet log messages in the current log file specified by the LOGFILE option in /etc/shorewall/shorewall.conf. ipcalc shorewall ipcalc [ <address> <mask> | <address>/<vlsm> ] Ipcalc displays the network address, broadcast address, network in CIDR notation and netmask corresponding to the input[s]. Example: ipcalc 192.168.1.0/24 iprange shorewall iprange <address1>-<address2> Iprange decomposes the specified range of IP addresses into the equivalent list of network/host addresses. logwatch shorewall logwatch [<refresh interval>] Monitors the log file specified by theLOGFILE option in /etc/shorewall/shorewall.conf and produces an audible alarm when new Shorewall messages are logged. monitor shorewall [-x] monitor [<refresh_interval>] Continuously display the firewall status, last 20 log entries and nat. When the log entry display changes, an audible alarm is sounded. When -x is given, that option is also passed to iptables to display actual packet and byte counts. refresh shorewall refresh: [ -q ] refresh The rules involving the broadcast addresses of firewall interfaces, the black list, traffic control rules and ECN control rules are recreated to reflect any changes made to your configuration files. Existing connections are untouched If -q is specified, less detain is displayed making it easier to spot warnings. reject shorewall reject <address> ... Causes packets from the specified <address>s to be rejected reset shorewall reset All the packet and byte counters in the firewall are reset. restart (Prior to Shorewall version 2.2.0) shorewall [ -q ] [ -c <configuration-directory> ] restart Restart is similar to shorewall stop followed by shorewall start. Existing connections are maintained. If -q is specified, less detail is displayed making it easier to spot warnings restart (Shorewall version 2.2.0 and later) shorewall [ -q ] restart <configuration-directory> Restart is similar to shorewall stop followed by shorewall start. Existing connections are maintained. If -q is specified, less detail is displayed making it easier to spot warnings restore shorewall [ -q ] restore [ <filename> ] Restore Shorewall to a state saved using the shorewall save command Existing connections are maintained. The <filename> names a restore file in /var/lib/shorewall created using shorewall save; if no <filename> is given then Shorewall will be restored from the file specified by the RESTOREFILE option in /etc/shorewall/shorewall.conf. safe-restart (Shorewall version 2.4.0 and later) shorewall [ -q ] safe-restart [ <filename> ] Only allowed if Shorewall is running. The current configuration is saved in /var/lib/shorewall/safe-restart (see the save command below). You will then be prompted asking if you want to accept the new configuration or not. If you answer "n" or if you fail to answer within 60 seconds (such as when your new configuration has disabled communication with your terminal), the configuration is restored from the saved configuration. safe-start (Shorewall version 2.4.0 and later) shorewall [ -q ] safe-start [ <filename> ] Shorewall is started normally. You will then be prompted asking if everything went all right. If you answer "n" or if you fail to answer within 60 seconds (such as when your new configuration has disabled communication with your terminal), a shorewall clear is performed for you. save shorewall save [ <filename> ] The dynamic data is stored in /var/lib/shorewall/save. The state of the firewall is stored in /var/lib/shorewall/<filename> for use by the shorewall restore and shorewall -f start commands. If <filename> is not given then the state is saved in the file specified by the RESTOREFILE option in /etc/shorewall/shorewall.conf. show shorewall [ -x ] show [ <chain> [ <chain> ...] |classifiers|connections|log|nat|tc|tos] shorewall [ -x ] show <chain> [ <chain> ... ] - produce a verbose report about the Netfilter chain(s). (iptables -L chain -n -v) shorewall [ -x ] show nat - produce a verbose report about the nat table. (iptables -t nat -L -n -v) shorewall [ -x ] show tos - produce a verbose report about the mangle table. (iptables -t mangle -L -n -v) shorewall show log - display the last 20 packet log entries. shorewall show capabilities - Added in Shorewall version 2.2.4 and displays your kernel/iptables capabilities shorewall show connections - displays the IP connections currently being tracked by the firewall. shorewall show classifiers - displays information about the traffic control/shaping classifiers. shorewall show tc - displays information about the traffic control/shaping configuration. shorewall show zones — Added in Shorewall version 2.2.0 Beta 7. Enabled when Shorewall is [re]started with DYNAMIC_ZONES=Yes in /etc/shorewall/shorewall.conf. Displays the composition of each zone. When -x is given, that option is also passed to iptables to display actual packet and byte counts. start (Shorewall versions prior to 2.2.0) shorewall [ -q ] [ -f ] [ -c <configuration-directory> ] start Start shorewall. Existing connections through shorewall managed interfaces are untouched. New connections will be allowed only if they are allowed by the firewall rules or policies. If -q is specified, less detail is displayed making it easier to spot warnings If -f is specified, the saved configuration specified by the RESTOREFILE option in /etc/shorewall/shorewall.conf will be restored if that saved configuration exists start (Shorewall 2.2.0 and later) shorewall [ -q ] [ -f ] start [ <configuration-directory> ] Start shorewall. Existing connections through shorewall managed interfaces are untouched. New connections will be allowed only if they are allowed by the firewall rules or policies. If -q is specified, less detail is displayed making it easier to spot warnings If -f is specified, the saved configuration specified by the RESTOREFILE option in /etc/shorewall/shorewall.conf will be restored if that saved configuration exists stop shorewall stop Stops the firewall. All existing connections, except those listed in /etc/shorewall/routestopped or permitted by the ADMINISABSENTMINDED option in /etc/shorewall/shorewall.conf, are taken down. The only new traffic permitted through the firewall is from systems listed in /etc/shorewall/routestopped or by ADMINISABSENTMINDED. status shorewall [ -x ] status Produce a verbose report about the firewall. When -x is given, that option is also passed to iptables to display actual packet and byte counts. try shorewall try <configuration-directory> [ <timeout> ] Restart shorewall using the specified configuration. If an error occurs during the restart, then another shorewall restart is performed using the default configuration. If a timeout is specified then the restart is always performed after the timeout occurs and uses the default configuration. When restarting using the default configuration, if the default restore script (as specified by the RESTOREFILE setting in /etc/shorewall/shorewall.conf) exists. then that script is used. version shorewall version Show the current shorewall version

The Shorewall State Diargram is depicted below. You will note that the commands that result in state transitions use the word firewall rather than shorewall. That is because the actual transitions are done by /usr/share/shorewall/firewall; /sbin/shorewall runs firewall according to the following table: /sbin/shorewall Command Resulting /usr/share/shorewall/firewall Command Effect if the Command Succeeds shorewall start firewall start The system filters packets based on your current Shorewall Configuration shorewall stop firewall stop Only traffic to/from hosts listed in /etc/shorewall/hosts is passed to/from/through the firewall. For Shorewall versions beginning with 1.4.7, if ADMINISABSENTMINDED=Yes in /etc/shorewall/shorewall.conf then in addition, all existing connections are retained and all connection requests from the firewall are accepted. shorewall restart firewall restart Logically equivalent to firewall stop;firewall start shorewall add firewall add Adds a host or subnet to a dynamic zone shorewall delete firewall delete Deletes a host or subnet from a dynamic zone shorewall refresh firewall refresh Reloads rules dealing with static blacklisting, traffic control and ECN. shorewall reset firewall reset Resets traffic counters shorewall clear firewall clear Removes all Shorewall rules, chains, addresses, routes and ARP entries. shorewall try firewall -c <new configuration> restart If unsuccessful then firewall start (standard configuration) If timeout then firewall restart (standard configuration)