shorewall_code/Shorewall/debian/shorewall.8

.TH SHOREWALL 8 "November 2002" "" ""


.SH NAME
shorewall \- the Shoreline firewall, an iptables based firewall


.SH SYNOPSIS
\fBshorewall\fR [debug|trace] [nolock] [-c <directory>] [-q] [-f] <command>


.SH COPYRIGHT
Copyright (C) 1999-2005 by Tom Eastep <teastep@shorewall.net>


.SH DESCRIPTION
The \fBShoreline Firewall\fR, more commonly known as Shorewall, is a
Netfilter (iptables) based firewall that can be used on a dedicated firewall
system, a multi-function gateway/router/server or on a standalone GNU/Linux
system.


.SH OPTIONS
.TP
\fBdebug|trace\fR 
Set up the debug mode (sets the -x shell option).

.TP
\fBnolock\fR 
Tells Shorewall not to acquire the lock file (\fI$STATEDIR/lock\fR). Used by programs issuing Shorewall commands when those programs already have the lock file.

.TP
\fB\-c \fIdirectory\fR
Look for configuration files in \fIdirectory\fR instead of \fI/etc/shorewall/\fR.

.TP
\fB-f\fR
If the file \fI/var/lib/shorewall/restore\fR is present shorewall restore the state of the firewall when \fI/var/lib/shorewall/restore\fR was created. Note: this option can be used only with the \fBstart\fR command.

.TP
\fB-q\fR
Quiet mode.


.SH STARTUP COMMAND
.TP
\fBstart\fR
Starts the firewall.

.TP
\fBstop\fR
Stops the firewall. The only traffic permitted through the firewall is from systems listed in \fI/etc/shorewall/routestopped\fR.

.TP
\fBrestart\fR
Stops the firewall (if it's running) and then starts it again.

.TP
\fBreset\fR
Reset the packet and byte counters in the firewall.

.TP
\fBclear\fR
Remove all rules and chains installed by the firewall.

.TP
\fBrefresh\fR
Refresh the rules involving the broadcast addresses of firewall interfaces, the black list, traffic control rules and ECN control rules.

.TP
\fBsave\fR
Creates a script \fI/var/lib/shorewall/restore\fR  which when run will restore the state of the firewall to its current state.

.TP
\fBrestore\fR
Runs the \fI/var/lib/shorewall/restore\fR created by the Shorewall save command.

.TP
\fBforget\fR
Removes the \fI/var/lib/shorewall/restore\fR script created by the save command.

.SH MONITORING COMMAND
.TP
\fBstatus\fR
Produces a verbose report about the firewall (iptables -L -n -v).
.TP
\fBshow [\fIkey\fR]
Produces a verbose report about the firewall (iptable -L -n -v), \fIkey\fR can be one of the following:

.RS
.TP
\fBchain\fR
Produces a verbose report about the \fIchain\fR (iptable -L \fIchain\fR -n -v)

.TP
\fBnat\fR
Produces a verbose report about the nat table (iptables -t nat -L -n -v).

.TP
\fBtos\fR
Produces a verbose report about the mangle table (iptables -t mangle -L -n -v).

.TP
\fBlog\fR
Display the last 20 packet log entries.

.TP
\fBconnections\fR
Displays the IP connections currently being tracked by the firewall.

.TP
\fBtc\fR
Displays information about the traffic control/shaping configuration

.TP
\fBdynamic\fR
Displays the dynamic blacklisting configuration
.RE

.TP
\fBmonitor\fR [\fIdelay\fR]
Continuously displays the firewall status, last 20 log entries and nat. When the
log entry display changes, an audible alarm is sounded. The \fIdelay\fR indicates the number of seconds between updates with the default being 10 seconds.

.TP
\fBhits\fR
Produces several reports about the Shorewall packet log messages in the current log file named in the \fI$LOGFILE\fR variable in \fR/etc/shorewall/shorewall.conf\fR.

.TP
\fBversion\fR
Displays the installed version number.

.TP
\fBcheck\fR
Performs a cursory validation of the zones, interfaces, hosts, rules and policy
files. \fBCAUTION\fR: this command is totally unsuppored and does not parse and validate the generated iptables commands. Even though the command completes successfully, the configuration may fail to start. Problem reports that complain about errors that the command does not detect will not be accepted.

.TP
\fBtry\fR \fIconfiguration-directory\fR [\fItimeout\fR]
Restarts Shorewall using the configuration found in \fIconfiguration-directory\fR and if an error occurs or if the \fItimeout\fR option is given and the new configuration has been up for that many seconds then Shorewall is restarted using the standard configuration.

.TP
\fBlogwatch\fR
Monitors the \fI$LOGFILE\fR and produces an audible alarm when new
Shorewall messages are logged.


.SH DYNAMIC BLACKLIST COMMAND
Shorewall can handle blacklists dynamically:

.TP
\fBdrop\fR <\fIipaddresslist\fR>
Inserts \fIipaddresslist\fR into the blacklist using the \fIDENY\fR policy.

.TP
\fBreject\fR <\fIipaddresslist\fR>
Inserts \fIipaddresslist\fR into the blacklist using the \fIREJECT\fR policy

.TP
\fBallow\fR <\fIipaddresslist\fR>
Removes \fIipaddresslist\fR from the blacklist.

.TP
\fBsave\fR
saves the dynamic blacklisting configuration so that it will be automatically restored the next time that the firewall is restarted. This command also creates the \fI/var/lib/shorewall/restore\fR script as described above.  


.SH
DYNAMIC ZONES COMMAND
Shorewall's zones can be altered dynamically:
.TP
\fBadd\fR <\fIinterface\fR>[:\fIhost\fR] <\fIzone\fR>
Adds the specified \fIinterface\fR (and \fIhost\fR if included) to the
specified \fIzone\fR.

.TP
\fBdel\fR <\fIinterface\fR>[:\fIhost\fR] <\fIzone\fR>
Deletes the specified \fIinterface\fR (and \fIhost\fR if included) from the
specified \fIzone\fR.

.SH 
MISC COMMAND
.TP
\fBipcalc\fR [<\fIaddress\fR> <\fImask\fR> | <\fIaddress/vlsm\fR>]
Displays the network address, broadcast address, network in CIDR notation and
netmask corresponding to the input[s].

.TP
\fBiprange\fR \fIaddress1-address2\fR
Decomposes the specified range of IP addresses into the equivalent list of
network/host addresses.


.SH SEE ALSO
.TP
iptables(8)


.SH CONFIGURATION FILES
.TP
\fI/etc/shorewall/\fR
The default configuration directory. Common default configurations provided by the author are installed under \fI/usr/share/shorewall/\fR.

.TP
\fIshorewall.conf\fR
Main Shorewall's configuration file.

.TP
\fIparams\fR
Set shell variables that can be used in some of the other configuration files.

.TP
\fIzones\fR
Define the network zones.

.TP
\fIinterfaces\fR
Tells the firewall which of your firewall's network interfaces are connected to which zone.

.TP
\fIhosts\fR
Defines zones in terms of subnets and/or individual IP addresses.

.TP
\fIpolicy\fR
Describes the firewall policies that control the traffic between zones.

.TP
\fIrules\fR
Defines exceptions to the policies.

.TP
\fImasq\fR
Defines classical IP Masquerading and Source Network Address Translation (SNAT).

.TP
\fIproxyarp\fR
Defines Proxy ARP.

.TP
\fInat\fR
Defines static NAT rules.

.TP
\fItunnels\fR
Defines IPSec, GRE, IPIP and PPTP tunnels with end-points on the firewall.

.TP
\fItcrules\fR
Defines marks to classify packet for traffic shaping.

.TP
\fImodules\fR
Contains commands for loading the kernel modules required by Shorewall-defined firewall rules.

.TP
\fItos\fR
Defines Type of Service field in packet headers based on packet source, packet
destination, protocol, source port and destination port.

.TP
\fIblacklist\fR
Defines static blacklists.

.TP
\fIrfc1918\fR
Defines the treatment of packets under the \fInorfc1918\fR interface option (it is installed under \fI/ysr/share/shorewall\fR).

.TP
\fIbogons\fR
Defines the treatment of packets under the \fInobogons\fR interface option (it is installed under \fI/ysr/share/shorewall\fR).

.TP
\fIroutestopped\fR
Defines the hosts that are accessible from the firewall when the firewall is stopped.

.TP
\fImaclist\fR
Associates MAC addresses with interfaces and optionally associates IP addresses with MAC addresses.

.TP
\fInetmap\fR
.

.TP
\fIinit\fR
Contains a list of commands that will be executed at the beginning of a "shorewall start" or "shorewall restart" command.

.TP
\fIinitdone\fR
Contains a list of commands that will be executed early in the process of
Shorewall configuration, after the old configuration has been cleared.

.TP
\fIstart\fR
Contains a list of commands that will be executed after Shorewall has been started or restarted.

.TP
\fIstop\fR
Contains a list of commands that will be executed at the beginning of a
"shorewall stop" command.

.TP
\fIstopped\fR
Contains a list of commands that will be executed at the completion of a
"shorewall stop" command.

.TP
\fIecn\fR
Lists the destinations for which you want to disable ECN.

.TP
\fIusers\fR
Associates local users and/or groups to Shorewall "User Sets".

.TP
\fIuserset\fR
Controls access by individual users to other network hosts from the firewall system.

.TP
\fIaccounting\fR
Contains rules for traffic accounting.

.TP
\fIactions\fR and \fIaction.template\fR
Files in \fI/etc/shorewall\fR and \fI/usr/share/shorewall\fR respectively that allow you to define your own actions for rules in \fI/etc/shorewall/rules\fR.

.TP
\fIactions.std\fR and \fIaction.*\fR
Files in \fI/usr/share/shorewall\fR that define the actions included as a standard part of Shorewall.


.SH AUTHORS
Tom Eastep <teastep@shorewall.net>