extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2025-01-02 19:49:08 +01:00
Code Issues Packages Projects Releases Wiki Activity

Some documentation updates

Browse Source 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@8863 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2008-11-09 20:14:58 +00:00
parent 2db8cc0207
commit a902e71a0a
2 changed files with 162 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/FAQ.xml
View File

@ -2013,6 +2013,19 @@ iptables: Invalid argument
</section>
</section>
<section>
<title>Using DNS Names</title>
<section id="faq79">
<title>(FAQ 79) Can I use DNS names in Shorewall configuration file
entries in place of IP addresses?</title>
<para><emphasis role="bold">Answer</emphasis>: <ulink
url="configuration_file_basics.htm#dnsnames">Yes</ulink>, but we advise
strongly against it.</para>
</section>
</section>
<section id="TC">
<title>Traffic Shaping</title>

267
docs/configuration_file_basics.xml
View File

@ -484,6 +484,125 @@ SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>
</example>
</section>
<section id="Variables">
<title>Using Shell Variables</title>
<para>You may use the <filename>/etc/shorewall/params</filename> file to
set shell variables that you can then use in some of the other
configuration files.</para>
<para>It is suggested that variable names begin with an upper case letter
to distinguish them from variables used internally within the Shorewall
programs</para>
<para>Example:</para>
<blockquote>
<programlisting>    /etc/shorewall/params
NET_IF=eth0
NET_BCAST=130.252.100.255
NET_OPTIONS=routefilter,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 routefilter,norfc1918
</programlisting>
</blockquote>
<para>Variables may be used anywhere in the other configuration
files.<note>
<para>Shorewall-perl users: If you use "$FW" on the right side of
assignments in the <filename>/etc/shorewall/params</filename> file,
you must also set the FW variable in that file.</para>
<para>Example:<programlisting>/etc/shorewall/zones:
#ZONE TYPE OPTIONS
<emphasis role="bold">fw</emphasis> firewall
/etc/shorewall/params:
FW=<emphasis role="bold">fw</emphasis>
BLARG=$FW:206.124.146.176</programlisting></para>
</note></para>
<para>Because the <filename>/etc/shorewall/params</filename> file is
simply sourced into the shell, you can place arbitrary shell code in the
file and it will be executed each time that the file is read. Any code
included should follow these guidelines:</para>
<orderedlist>
<listitem>
<para>The code should not have side effects, especially on other
shorewall configuration files.</para>
</listitem>
<listitem>
<para>The code should be safe to execute multiple times without
producing different results.</para>
</listitem>
<listitem>
<para>Should not depend on where the code is called from (the params
file is sourced by both /sbin/shorewall and
/usr/lib/shorewall/firewall).</para>
</listitem>
<listitem>
<para>Should not assume anything about the state of Shorewall.</para>
</listitem>
<listitem>
<para>The names of any functions or variables declared should begin
with an upper case letter.</para>
</listitem>
<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
<filename><filename>params</filename></filename> file is only
processed by the compiler; it is not run by the compiled
script.</para>
</listitem>
<listitem>
<para>If you are using <ulink
url="CompiledPrograms.html#Lite">Shorewall Lite</ulink> and if the
<filename>params</filename> script needs to set shell variables based
on the configuration of the firewall system, you can use this
trick:</para>
<programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
<para>The <command>shorewall-lite call</command> command allows you to
to call interactively any Shorewall function that you can call in an
extension script.</para>
</listitem>
</orderedlist>
<para>When expanding a variable, the acceptable forms of expansion depend
on whether you are using Shorewall-shell or Shorewall-perl.</para>
<itemizedlist>
<listitem>
<para>Shorewall-shell and all Shorewall versions prior to 4.0 can use
any form of expansion supported by the shell ($VAR, ${VAR},
${VAR:=val}, ...).</para>
</listitem>
<listitem>
<para>Shorewall-perl only supports the $VAR and ${VAR} forms.</para>
</listitem>
</itemizedlist>
</section>
<section id="Embedded">
<title>Embedded Shell and Perl</title>
@ -592,6 +711,35 @@ use Shorewall::Config qw/shorewall/;</programlisting>
the firewall has started have absolutely no effect on the firewall's rule
set.</para>
<para>For some sites, using DNS names is very risky. Here's an
example:</para>
<programlisting>teastep@ursa:~$ dig pop.gmail.com
; &lt;&lt;&gt;&gt; DiG 9.4.2-P1 &lt;&lt;&gt;&gt; pop.gmail.com
;; global options: printcmd
;; Got answer:
;; -&gt;&gt;HEADER&lt;&lt;- opcode: QUERY, status: NOERROR, id: 1774
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 7, ADDITIONAL: 0
;; QUESTION SECTION:
;pop.gmail.com. IN A
;; ANSWER SECTION:
pop.gmail.com. <emphasis role="bold">300</emphasis> IN CNAME gmail-pop.l.google.com.
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.109
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.111</programlisting>
<para>Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five
minutes later, the answer may change!</para>
<para>So this rule may work for five minutes then suddently stop
working:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST
# PORT(S)
POP/ACCEPT loc net:pop.gmail.com</programlisting>
<para>If your firewall rules include DNS names then:</para>
<itemizedlist>
@ -849,125 +997,6 @@ DNAT net loc:192.168.1.3 tcp 4000:4100</programlisting>
</note>
</section>
<section id="Variables">
<title>Using Shell Variables</title>
<para>You may use the <filename>/etc/shorewall/params</filename> file to
set shell variables that you can then use in some of the other
configuration files.</para>
<para>It is suggested that variable names begin with an upper case letter
to distinguish them from variables used internally within the Shorewall
programs</para>
<para>Example:</para>
<blockquote>
<programlisting>    /etc/shorewall/params
NET_IF=eth0
NET_BCAST=130.252.100.255
NET_OPTIONS=routefilter,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 routefilter,norfc1918
</programlisting>
</blockquote>
<para>Variables may be used anywhere in the other configuration
files.<note>
<para>Shorewall-perl users: If you use "$FW" on the right side of
assignments in the <filename>/etc/shorewall/params</filename> file,
you must also set the FW variable in that file.</para>
<para>Example:<programlisting>/etc/shorewall/zones:
#ZONE TYPE OPTIONS
<emphasis role="bold">fw</emphasis> firewall
/etc/shorewall/params:
FW=<emphasis role="bold">fw</emphasis>
BLARG=$FW:206.124.146.176</programlisting></para>
</note></para>
<para>Because the <filename>/etc/shorewall/params</filename> file is
simply sourced into the shell, you can place arbitrary shell code in the
file and it will be executed each time that the file is read. Any code
included should follow these guidelines:</para>
<orderedlist>
<listitem>
<para>The code should not have side effects, especially on other
shorewall configuration files.</para>
</listitem>
<listitem>
<para>The code should be safe to execute multiple times without
producing different results.</para>
</listitem>
<listitem>
<para>Should not depend on where the code is called from (the params
file is sourced by both /sbin/shorewall and
/usr/lib/shorewall/firewall).</para>
</listitem>
<listitem>
<para>Should not assume anything about the state of Shorewall.</para>
</listitem>
<listitem>
<para>The names of any functions or variables declared should begin
with an upper case letter.</para>
</listitem>
<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
<filename><filename>params</filename></filename> file is only
processed by the compiler; it is not run by the compiled
script.</para>
</listitem>
<listitem>
<para>If you are using <ulink
url="CompiledPrograms.html#Lite">Shorewall Lite</ulink> and if the
<filename>params</filename> script needs to set shell variables based
on the configuration of the firewall system, you can use this
trick:</para>
<programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
<para>The <command>shorewall-lite call</command> command allows you to
to call interactively any Shorewall function that you can call in an
extension script.</para>
</listitem>
</orderedlist>
<para>When expanding a variable, the acceptable forms of expansion depend
on whether you are using Shorewall-shell or Shorewall-perl.</para>
<itemizedlist>
<listitem>
<para>Shorewall-shell and all Shorewall versions prior to 4.0 can use
any form of expansion supported by the shell ($VAR, ${VAR},
${VAR:=val}, ...).</para>
</listitem>
<listitem>
<para>Shorewall-perl only supports the $VAR and ${VAR} forms.</para>
</listitem>
</itemizedlist>
</section>
<section id="MAC">
<title>Using MAC Addresses</title>