Tom Eastep 2004-06-15 2001-2004 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.

If you have a permanent internet connection such as DSL or Cable, I recommend that you start the firewall automatically at boot. The installation procedure attempts to set up the init scripts to start the firewall in run levels 2-5 and stop it in run levels 1 and 6. If you want to configure your firewall differently from this default, you can use your distribution's run-level editor. 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. 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. You can manually start and stop Shoreline Firewall using the /sbin/shorewall shell program. shorewall [ -q ] [ -f ] start - starts the firewall. It important to understand that when the firewall is in the Started state there is no Shorewall Program running. It rather means that Netfilter has been configured to handle traffic as described in your Shorewall configuration files. Please refer to the Shorewall State Diagram as shown at the bottom of this page for more information. The -q option was added in Shorewall 2.0.2 Beta 1 and reduces the amout of output produced. Also beginning with Shorewall version 2.0.2 Beta 1, the -f option may be specified. See the Saved Configurations section below for details. shorewall stop - stops the firewall; the only traffic permitted through the firewall is from systems listed in /etc/shorewall/routestopped (Beginning with version 1.4.7, if ADMINISABSENTMINDED=Yes in /etc/shorewall/shorewall.conf then in addition, all existing connections are permitted and any new connections originating from the firewall itself are allowed). shorewall [ -q ] restart - stops the firewall (if it is in the Started state) and then starts it again. The -q option was added in Shorewall 2.0.2 Beta 1 and reduces the amout of output produced. shorewall reset - reset the packet and byte counters in the firewall shorewall clear - remove all rules and chains installed by Shoreline Firewall. The firewall is wide open shorewall refresh - refresh the rules involving the broadcast addresses of firewall interfaces, the black list, traffic control rules and ECN control rules. shorewall save - Beginning with Shorewall 2.0.2 Beta1, this command creates a script which when run will restore the state of the firewall to its current state. See the Saved Configurations section below for details. shorewall restore [ <file name> ] - Runs a script created by the shorewall save command. See the Saved Configurations section below for details. shorewall forget - Added in Shorewall 2.0.2 Beta 1. Removes the /var/lib/shorewall restore script created by the shorewall save command. If you include the keyword debug as the first argument, then a shell trace of the command is produced as in: shorewall debug start 2> /tmp/traceThe above command would trace the start command and place the trace information in the file /tmp/trace Beginning with version 1.4.7, shorewall can give detailed help about each of its commands: shorewall help [ command | host | address ]The shorewall program may also be used to monitor the firewall. shorewall status - produce a verbose report about the firewall (iptables -L -n -v) shorewall show <chain1> [ <chain2> ... ] - produce a verbose report about the listed chains (iptables -L chain -n -v) Note: You may only list one chain in the show command when running Shorewall version 1.4.6 and earlier. Version 1.4.7 and later allow you to list multiple chains in one command. shorewall show nat - produce a verbose report about the nat table (iptables -t nat -L -n -v) shorewall 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 connections - displays the IP connections currently being tracked by the firewall. shorewall show tc - displays information about the traffic control/shaping configuration. shorewall monitor [ <delay> ] - Continuously display the firewall status, last 20 log entries and nat. When the log entry display changes, an audible alarm is sounded. The <delay> indicates the number of seconds between updates with the default being 10 seconds. shorewall hits - Produces several reports about the Shorewall packet log messages in the current log file named in the LOGFILE variable in /etc/shorewall/shorewall.conf. shorewall version - Displays the installed version number. shorewall check - Performs a cursory validation of the zones, interfaces, hosts, rules and policy files.The check command is totally unsuppored and does not parse and validate the generated iptables commands. Even though the check command completes successfully, the configuration may fail to start. Problem reports that complain about errors that the check command does not detect will not be accepted.See the recommended way to make configuration changes described below. shorewall try <configuration-directory> [ <timeout> ] - Restart shorewall using the specified configuration and if an error occurs or if the <timeout> option is given and the new configuration has been up for that many seconds then shorewall is restarted using the standard configuration. shorewall logwatch (added in version 1.3.2) - Monitors the LOGFILE and produces an audible alarm when new Shorewall messages are logged. Beginning with Shorewall 1.4.6, /sbin/shorewall supports a couple of commands for dealing with IP addresses and IP address ranges: shorewall ipcalc [ <address> <mask> | <address>/<vlsm> ] - displays the network address, broadcast address, network in CIDR notation and netmask corresponding to the input[s]. shorewall iprange <address1>-<address2> - Decomposes the specified range of IP addresses into the equivalent list of network/host addresses There is a set of commands dealing with dynamic blacklisting: shorewall drop <ip address list> - causes packets from the listed IP addresses to be silently dropped by the firewall. shorewall reject <ip address list> - causes packets from the listed IP addresses to be rejected by the firewall. shorewall allow <ip address list> - re-enables receipt of packets from hosts previously blacklisted by a drop or reject command. shorewall save [ <file name> ] - save the dynamic blacklisting configuration so that it will be automatically restored the next time that the firewall is restarted. Beginning with Shorewall version 2.0.2 Beta1, this command also creates a script that can be used to restore the state of the firewall. See the Saved Configurations section below for details. show dynamic - displays the dynamic blacklisting chain. Finally, the shorewall program may be used to dynamically alter the contents of a zone. shorewall add <interface>[:<host>] <zone> - Adds the specified interface (and host if included) to the specified zone. shorewall delete <interface>[:<host>] <zone> - Deletes the specified interface (and host if included) from the specified zone. Examples: shorewall add ipsec0:192.0.2.24 vpn1 -- adds the address 192.0.2.24 from interface ipsec0 to the zone vpn1 shorewall delete ipsec0:192.0.2.24 vpn1 -- deletes the address 192.0.2.24 from interface ipsec0 from zone vpn1

When shorewall start, shorewall restart or shorewall refresh encounter an error, the behavior depends on which version of Shorewall you are running and whether there is a /var/lib/shorewall/restore script available (see shorewall save above). If you are running a version of Shorewall earlier than 2.0.2 Beta 1 then the effect is as if a shorewall stop command had been run. If you have executed a shorewall save command without a subsequent shorewall forget, then the firewall is restored to the state when shorewall save was executed.

The shorewall start, shorewall restart, shorewall check, and shorewall try commands allow you to specify which Shorewall configuration to use: shorewall [ -c <configuration-directory> ] {start|restart|check} 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: mkdir /etc/test cd /etc/test <copy any files that you need to change from /etc/shorewall to . and change them here> shorewall -c ./ check <correct any errors found by check and check again> /sbin/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 start the old one for you. When the new configuration works then just: cp * /etc/shorewall cd rm -rf /etc/test

Beginning with Shorewall 2.0.2 Beta 1, Shorewall is integrated with the iptables-save/iptables-restore programs through saved configurations. A saved configuration is a shell script that when executed will restore the firewall state to match what it was when the script was created. Because of the way in which saved configurations are used, they are also referred to using the term restore script. The shorewall save command creates a restore script. The shorewall restore command executes a restore script. The shorewall forget command deleted a restore script. The -f option of the shorewall start command causes a restore script to be executed if it exists. In Shorewall 2.0.2, the name of the restore script is fixed: /var/lib/shorewall/restore. Beginning with Shorewall 2.0.3 Beta 1, multiple restore scripts are permitted in /var/lib/shorewall. The shorewall save, shorewall restore and shorewall forget commands are extended to allow you to specify a simple file name (one not containing embedded slashes). The fiile name specifies the name of a restore script in /var/lib/shorewall. A RESTOREFILE option has been added to shorewall.conf. This variable may contain a simple file name that designates the default restore script when the command doesn't specify one. To maintain backward compatibility with Shorewall 2.0.2, if RESTOREFILE is not set or is set to the empty value (RESTOREFILE=""), then the default value is restore.

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)

1.102004-05-14TEUpdate "try" syntax in the alternate configuration section to include [ <timeout> ]1.92004-05-03TEShorewall 2.0.21.3-1.82004-01-04TEDocbook standards1.22003-12-31TEAdded clarification about "Started State"1.12003-12-29TEInitial Docbook conversion