extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2024-11-08 00:34:04 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation updates

Browse Source
This commit is contained in:
Tom Eastep 2009-05-30 08:34:34 -07:00
parent 7ecd3f0437
commit 234b9b294a
7 changed files with 297 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
docs/Actions.xml
View File

@ -64,6 +64,9 @@
which each packet/rule match within the action causes a log message to be
generated.</para>
<para>For readers familiar with iptables, actions are the way in which you
can create your own filter-table chains.</para>
<para>There are three types of Shorewall actions:</para>
<orderedlist>
@ -158,7 +161,7 @@ ACCEPT - - tcp 135,139,445
<para>In addition, the default specified in
<filename>/etc/shorewall/shorewall.conf</filename> may be overridden by
specifying a different default in the POLICY column of <filename><ulink
specifying a different action in the POLICY column of <filename><ulink
url="manpages/shorewall-policy.html">/etc/shorewall/policy</ulink></filename>.</para>
<warning>
@ -169,107 +172,6 @@ ACCEPT - - tcp 135,139,445
</warning>
</section>
<section id="Limit">
<title>Limiting Per-IP Connection Rate</title>
<para>Shorewall supports a <quote>Limit</quote> <ulink
url="Actions.html">action</ulink>. Limit is invoked with a comma-separated
list in place of a logging tag. The list has three elements:</para>
<orderedlist>
<listitem>
<para>The name of a <quote>recent</quote> list. You select the list
name which must conform to the rules for a valid chain name. Different
rules that specify the same list name will use the same set of
counters.</para>
</listitem>
<listitem>
<para>The number of connections permitted in a specified time
period.</para>
</listitem>
<listitem>
<para>The time period, expressed in seconds.</para>
</listitem>
</orderedlist>
<para>Connections that exceed the specified rate are dropped.</para>
<para>For example, to use a recent list name of <emphasis
role="bold">SSHA</emphasis>, and to limit SSH connections to 3 per minute,
use this entry in <filename>/etc/shorewall/rules</filename>:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
Limit:none:SSHA,3,60 net $FW tcp 22</programlisting>
<para>If you want dropped connections to be logged at the info level, use
this rule instead:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
Limit:info:SSHA,3,60 net $FW tcp 22</programlisting>
<para>To summarize, you pass four pieces of information to the Limit
action:</para>
<itemizedlist>
<listitem>
<para>The log level. If you don't want to log, specify
<quote>none</quote>.</para>
</listitem>
<listitem>
<para>The name of the recent list that you want to use
(<quote>SSHA</quote> in this example).</para>
</listitem>
<listitem>
<para>The maximum number of connections to accept (3 in this
example).</para>
</listitem>
<listitem>
<para>The number of seconds over which you are willing to accept that
many connections (60 in this example).</para>
</listitem>
</itemizedlist>
<section id="LimitImp">
<title>How Limit is Implemented</title>
<para>For those who are curious, the Limit action is implemented as
follows:</para>
<programlisting>my @tag = split /,/, $tag;
fatal_error 'Limit rules must include &lt;list name&gt;,&lt;max connections&gt;,&lt;interval&gt; as the log tag (' . join( ':', 'Limit', $level eq '' ? 'none' : $level , $tag ) . ')'
unless @tag == 3;
my $list = $tag[0];
for ( @tag[1,2] ) {
fatal_error 'Max connections and interval in Limit rules must be numeric (' . join( ':', 'Limit', $level eq '' ? 'none' : $level, $tag ) . ')' unless /^\d+$/
}
my $count = $tag[1] + 1;
add_rule $chainref, "-m recent --name $list --set";
if ( $level ) {
my $xchainref = new_chain 'filter' , "$chainref-&gt;{name}%";
log_rule_limit $level, $xchainref, $tag[0], 'DROP', '', '', 'add', '';
add_rule $xchainref, '-j DROP';
add_rule $chainref, "-m recent --name $list --update --seconds $tag[2] --hitcount $count -j $xchainref-&gt;{name}";
} else {
add_rule $chainref, "-m recent --update --name $list --seconds $tag[2] --hitcount $count -j DROP";
}
add_rule $chainref, '-j ACCEPT';
1; </programlisting>
</section>
</section>
<section id="Defining">
<title>Defining your own Actions</title>
@ -699,7 +601,107 @@ add_rule( $chainref, '-m pkttype --pkttype broadcast -j DROP' );
1;</programlisting></para>
</example>
<para>For a richer example, see <ulink url="PortKnocking.html">this
article</ulink>.</para>
<para>For a richer example, see the next section.</para>
</section>
<section id="Limit">
<title>Limiting Per-IP Connection Rate using the Limit Action</title>
<para>Shorewall supports a <quote>Limit</quote> built-in action. Limit is
invoked with a comma-separated list in place of a logging tag. The list
has three elements:</para>
<orderedlist>
<listitem>
<para>The name of a <quote>recent</quote> list. You select the list
name which must conform to the rules for a valid chain name. Different
rules that specify the same list name will use the same set of
counters.</para>
</listitem>
<listitem>
<para>The number of connections permitted in a specified time
period.</para>
</listitem>
<listitem>
<para>The time period, expressed in seconds.</para>
</listitem>
</orderedlist>
<para>Connections that exceed the specified rate are dropped.</para>
<para>For example, to use a recent list name of <emphasis
role="bold">SSHA</emphasis>, and to limit SSH connections to 3 per minute,
use this entry in <filename>/etc/shorewall/rules</filename>:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
Limit:none:SSHA,3,60 net $FW tcp 22</programlisting>
<para>If you want dropped connections to be logged at the info level, use
this rule instead:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
Limit:info:SSHA,3,60 net $FW tcp 22</programlisting>
<para>To summarize, you pass four pieces of information to the Limit
action:</para>
<itemizedlist>
<listitem>
<para>The log level. If you don't want to log, specify
<quote>none</quote>.</para>
</listitem>
<listitem>
<para>The name of the recent list that you want to use
(<quote>SSHA</quote> in this example).</para>
</listitem>
<listitem>
<para>The maximum number of connections to accept (3 in this
example).</para>
</listitem>
<listitem>
<para>The number of seconds over which you are willing to accept that
many connections (60 in this example).</para>
</listitem>
</itemizedlist>
<section id="LimitImp">
<title>How Limit is Implemented</title>
<para>For those who are curious, the Limit action is implemented as
follows:</para>
<programlisting>my @tag = split /,/, $tag;
fatal_error 'Limit rules must include &lt;list name&gt;,&lt;max connections&gt;,&lt;interval&gt; as the log tag (' . join( ':', 'Limit', $level eq '' ? 'none' : $level , $tag ) . ')'
unless @tag == 3;
my $list = $tag[0];
for ( @tag[1,2] ) {
fatal_error 'Max connections and interval in Limit rules must be numeric (' . join( ':', 'Limit', $level eq '' ? 'none' : $level, $tag ) . ')' unless /^\d+$/
}
my $count = $tag[1] + 1;
add_rule $chainref, "-m recent --name $list --set";
if ( $level ) {
my $xchainref = new_chain 'filter' , "$chainref-&gt;{name}%";
log_rule_limit $level, $xchainref, $tag[0], 'DROP', '', '', 'add', '';
add_rule $xchainref, '-j DROP';
add_rule $chainref, "-m recent --name $list --update --seconds $tag[2] --hitcount $count -j $xchainref-&gt;{name}";
} else {
add_rule $chainref, "-m recent --update --name $list --seconds $tag[2] --hitcount $count -j DROP";
}
add_rule $chainref, '-j ACCEPT';
1; </programlisting>
</section>
</section>
</article>

48
docs/Build.xml
View File

@ -139,7 +139,8 @@
<title>setversion</title>
<para>The <command>setversion</command> script updates the version
number is a directory.</para>
number in a directory. The script is run with the current working
directory being <filename class="directory">trunk</filename>.</para>
<blockquote>
<para><command>setversion</command>
@ -153,8 +154,7 @@
<section>
<title>build44</title>
<para>This is the script that builds Shorewall packages from Git.
</para>
<para>This is the script that builds Shorewall packages from Git.</para>
<para>The script copies content from Git using the <command>git
archive</command> command. It then uses that content to build the
@ -344,22 +344,6 @@
<para>Build the shorewall6-lite package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>p</term>
<listitem>
<para>Build the shorewall-perl package</para>
</listitem>
</varlistentry>
<varlistentry>
<term>s</term>
<listitem>
<para>Build the shorewall-shell package</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
@ -386,14 +370,14 @@
4.3.6:</para>
<blockquote>
<para><command>buildshorewall 4.3.7 4.3.6</command></para>
<para><command>build44 4.3.7 4.3.6</command></para>
</blockquote>
<para>Example 2 - Build Shorewall 4.2.7.1 Shorewall-perl and generate
patches against 4.2.7:</para>
<para>Example 2 - Build Shorewall 4.2.7.1 Shorewall and generate patches
against 4.2.7:</para>
<blockquote>
<para><command>buildshorewall -trSp 4.3.7.1 4.3.7</command></para>
<para><command>build44 -trSc 4.3.7.1 4.3.7</command></para>
</blockquote>
</section>
@ -452,24 +436,6 @@
<para>Upload the shorewall6-lite package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>p</term>
<listitem>
<para>Upload the shorewall-perl package (versions 4.0 and
4.2 only)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>s</term>
<listitem>
<para>Upload the shorewall-shell package (versions 4.0 and
4.2 only)</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

32
docs/CompiledPrograms.xml
View File

@ -58,11 +58,6 @@
attempting to use them.</para>
<orderedlist>
<listitem>
<para>The <emphasis role="bold">detectnets</emphasis> interface
option is not supported.</para>
</listitem>
<listitem>
<para>All extension scripts used are copied into the program (with
the exception of <ulink url="shorewall_extension_scripts.htm">those
@ -115,8 +110,8 @@
command:</para>
<blockquote>
<para><command>shorewall compile [ -e ] [ &lt;directory name&gt; ]
&lt;path name&gt;</command></para>
<para><command>shorewall compile [ -e ] [ &lt;directory name&gt; ] [
&lt;path name&gt; ]</command></para>
</blockquote>
<para>where</para>
@ -162,7 +157,9 @@
<term>&lt;path name&gt;</term>
<listitem>
<para>specifies the name of the script to be created.</para>
<para>specifies the name of the script to be created. If not
given, ${VARDIR}/firewall is assumed (by default, ${VARDIR} is
<filename>/var/lib/shorewall/</filename>)</para>
</listitem>
</varlistentry>
</variablelist>
@ -239,8 +236,9 @@
<listitem>
<para>modify the files in the corresponding export directory
appropriately. It's a good idea to include the IP address of the
administrative system in the <filename>routestopped</filename>
file.</para>
administrative system in the <ulink
url="manpages/shorewall-routestopped.html"><filename>routestopped</filename>
file</ulink>.</para>
<para>It is important to understand that with Shorewall Lite, the
firewall's export directory on the administrative system acts as
@ -288,8 +286,9 @@
-e</command>), copies that file to the remote system via scp and
starts Shorewall Lite on the remote system via ssh. The -c option
causes the capabilities of the remote system to be generated and
copied to a file named capabilities in the export directory. See
<link linkend="Shorecap">below</link>.</para>
copied to a file named <filename>capabilities</filename> in the
export directory. See <link
linkend="Shorecap">below</link>.</para>
<para>Example (firewall's DNS name is 'gateway'):</para>
@ -538,8 +537,9 @@ clean:
<para>On the administrative system:</para>
<para>It's a good idea to include the IP address of the
administrative system in the firewall system's
<filename>routestopped</filename> file.</para>
administrative system in the firewall system's <ulink
url="manpages/shorewall-routestopped.html"><filename>routestopped</filename>
file</ulink>.</para>
<para>Also, edit the <filename>shorewall.conf</filename> file in the
firewall's export directory and change the CONFIG_PATH setting to
@ -727,8 +727,8 @@ CAPVERSION=40190</programlisting>
<section id="Running">
<title>Running compiled programs directly</title>
<para>Compiled firewall programs are complete programs that support the
following command line forms:</para>
<para>Compiled firewall programs are complete shell programs that support
the following command line forms:</para>
<blockquote>
<simplelist>

150
docs/Dynamic.xml
View File

@ -45,11 +45,144 @@
<para>Shorewall provides basic support for defining such zones. This
support is based on <ulink
url="http://ipset.netfilter.org/">ipset</ulink>, so to use dynamic zones,
you must have installed the <ulink
url="http://ipset.netfilter.org/">ipset</ulink>. As of this writing, ipset
is not included in the standard kernel distribution; so to use dynamic
zones, you must be running kernel 2.6.20 or later and have installed the
<ulink
url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>.</para>
</section>
<section>
<title>Installing xtables-addons</title>
<para>The xtables-addons are fairly easy to install. You do not need to
recompile your kernel. Basic steps are as follows:</para>
<orderedlist>
<listitem>
<para>Install gcc and make</para>
</listitem>
<listitem>
<para>Install the headers for the kernel you are running. In some
distributions, such as <trademark>Debian</trademark> and
<trademark>Ubuntu</trademark>, the packet is called kernel-headers.
For other distrubutions, such as OpenSuSE, you must install the
kernel-source package.</para>
</listitem>
<listitem>
<para>At a shell prompt, type 'locate libxtables'. If no output is
produced, then you must download and install the latest iptables.
</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>download the iptables source tarball</para>
</listitem>
<listitem>
<para>untar the source</para>
</listitem>
<listitem>
<para>cd to the iptables source directory</para>
</listitem>
<listitem>
<para>run './configure'</para>
</listitem>
<listitem>
<para>run 'make'</para>
</listitem>
<listitem>
<para>As root, cd to the iptables source directory and run 'make
install'.</para>
</listitem>
<listitem>
<para>Your new iptables binary will now be installed in
/usr/local/sbin. Modify shorewall.conf to specify
IPTABLES=/usr/local/sbin/iptables</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Download the latest xtables-addons source tarball</para>
</listitem>
<listitem>
<para>Untar the xtables-addons source</para>
</listitem>
<listitem>
<para>cd to the xtables-addons source directory</para>
</listitem>
<listitem>
<para>run './configure'</para>
</listitem>
<listitem>
<para>run 'make'</para>
</listitem>
<listitem>
<para>As root, cd to the xtables-addons directory and run 'make
install'.</para>
</listitem>
<listitem>
<para>Restart shorewall</para>
</listitem>
<listitem>
<para>'shorewall show capabilities' should now indicate<emphasis
role="bold"> Ipset Match: Available</emphasis></para>
</listitem>
</orderedlist>
<para>You will have to repeat steps 6-9 each time that you receive a
kernel upgrade from your distribution venrundor. You can install
xtables-addons before booting to the new kernel as follows
(<emphasis>new-kernel-version</emphasis> is the version of the
newly-installed kernel - example <emphasis
role="bold">2.6.28.11-generic</emphasis>. Look in the /lib/modules
directory to get the full version name)</para>
<orderedlist>
<listitem>
<para>cd to the xtables-addons source directory</para>
</listitem>
<listitem>
<para>run 'make clean'</para>
</listitem>
<listitem>
<para>run './configure --with-kbuild
/lib/modules/<emphasis>new-kernel-version</emphasis>/build'</para>
</listitem>
<listitem>
<para>run 'make'</para>
</listitem>
<listitem>
<para>As root, cd to the xtables-addons source directory and run 'make
install'.</para>
</listitem>
<listitem>
<para>As root, run 'depmod -a
<emphasis>new-kernel-version'</emphasis></para>
</listitem>
</orderedlist>
</section>
<section>
<title>Defining a Dynamic Zone</title>
@ -93,6 +226,10 @@ webok eth0 - hosts=dynamic</programlisting>
<blockquote>
<para><command>shorewall add eth0:192.168.3.4 webok</command></para>
</blockquote>
<para>The command can only be used when the ipset involved is of type
iphash. For other ipset types, the <command>ipset</command> command must
be used directly.</para>
</section>
<section>
@ -112,6 +249,10 @@ webok eth0 - hosts=dynamic</programlisting>
<blockquote>
<para><command>shorewall delete eth0:192.168.3.4 webok</command></para>
</blockquote>
<para>The command can only be used when the ipset involved is of type
iphash. For other ipset types, the <command>ipset</command> command must
be used directly.</para>
</section>
<section>
@ -152,7 +293,8 @@ eth0:
<section>
<title>Restrictions</title>
<para>When using dynamic zones, you may not use ipsets in your
<filename>/etc/shorewall/routestopped</filename> file.</para>
<para>When using dynamic zones, you may not use ipsets in your <ulink
url="manpages/shorewall-routestopped.html">/etc/shorewall/routestopped</ulink>
file.</para>
</section>
</article>

16
docs/configuration_file_basics.xml
View File

@ -227,6 +227,14 @@
<filename>/etc/shorewall</filename> and modify the
copy</emphasis>.</para>
</listitem>
<listitem>
<para><filename>/usr/share/modules</filename> — Specifies the kernel
modules to be loaded during shorewall start/restart . <emphasis
role="bold">If you need to change this file, copy it to
<filename>/etc/shorewall</filename> and modify the
copy</emphasis>.</para>
</listitem>
</itemizedlist></para>
</section>
@ -600,8 +608,8 @@ SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>
<listitem>
<para>The <filename>/etc/shorewall/params</filename> file is processed
by the compiler at compile-time and by the compiled script at
run-time. Beginning with Shorewall 3.2.9 and 3.4.0 RC2, if you have
set EXPORTPARAMS=No in <filename>shorewall.conf</filename>, then the
run-time. If you have set EXPORTPARAMS=No in
<filename>shorewall.conf</filename>, then the
<filename><filename>params</filename></filename> file is only
processed by the compiler; it is not run by the compiled
script.</para>
@ -865,8 +873,8 @@ POP(ACCEPT) loc net:pop.gmail.com</programlisting>
<listitem>
<para>If you use line continuation to break a comma-separated list,
the continuation line(s) must begin in column 1 (or there would be
embedded white space)</para>
the comma must be the last thing on the continued line before '\'
unless the continuation line has no leading white space.</para>
</listitem>
<listitem>

4
docs/traffic_shaping.xml
View File

@ -1344,7 +1344,7 @@ ppp0 4 90kbit 200kbit 3 default</pro
instructions.</para>
</section>
<section>
<section id="HFSC">
<title>An HFSC Example</title>
<para>As mentioned at the top of this article, there is an excellent
@ -1371,7 +1371,7 @@ eth0 - 1000kbit hfsc</programlisting>
<para>The following sub-section offers some notes about the
article.</para>
<section>
<section id="MajicNumbers">
<title>Where Did all of those Magic Numbers come from?</title>
<para>As you read the article, numbers seem to be introduced out of thin

36
manpages/shorewall-routestopped.xml
View File

@ -12,7 +12,7 @@
<refname>routestopped</refname>
<refpurpose>The Shorewall file that governs what traffic flows through the
firewall while it is in 'stopped' state.</refpurpose>
firewall while it is in the 'stopped' state.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -29,6 +29,12 @@
used, the file also determines those hosts that are accessible when the
firewall is in the process of being [re]started.</para>
<warning>
<para>Changes to this file do not take effect until after the next
<command>shorewall start</command> or <command>shorewall
restart</command> command.</para>
</warning>
<para>The columns in the file are as follows.</para>
<variablelist>
@ -102,34 +108,6 @@
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">critical</emphasis></term>
<listitem>
<para>Allow traffic between the firewall and these hosts
throughout '[re]start', 'stop' and 'clear'. Specifying
<emphasis role="bold">critical</emphasis> 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:</para>
<itemizedlist>
<listitem>
<para>'Ping' nodes with heartbeat.</para>
</listitem>
<listitem>
<para>LDAP server(s) if you use LDAP Authentication</para>
</listitem>
<listitem>
<para>NFS Server if you have an NFS-mounted root
filesystem.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>notrack</term>