From a902e71a0af2604020dc1da658b16ec3968c8bb0 Mon Sep 17 00:00:00 2001 From: teastep Date: Sun, 9 Nov 2008 20:14:58 +0000 Subject: [PATCH] Some documentation updates git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@8863 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb --- docs/FAQ.xml | 15 +- docs/configuration_file_basics.xml | 267 ++++++++++++++++------------- 2 files changed, 162 insertions(+), 120 deletions(-) diff --git a/docs/FAQ.xml b/docs/FAQ.xml index 7c90b0044..d339bde31 100644 --- a/docs/FAQ.xml +++ b/docs/FAQ.xml @@ -2013,6 +2013,19 @@ iptables: Invalid argument +
+ Using DNS Names + +
+ (FAQ 79) Can I use DNS names in Shorewall configuration file + entries in place of IP addresses? + + Answer: Yes, but we advise + strongly against it. +
+
+
Traffic Shaping @@ -2637,4 +2650,4 @@ loc $FW ACCEPT policies.
- \ No newline at end of file + diff --git a/docs/configuration_file_basics.xml b/docs/configuration_file_basics.xml index e0b21b66d..2be565353 100644 --- a/docs/configuration_file_basics.xml +++ b/docs/configuration_file_basics.xml @@ -484,6 +484,125 @@ SHELL cat /etc/shorewall/rules.d/*.rules +
+ Using Shell Variables + + You may use the /etc/shorewall/params file to + set shell variables that you can then use in some of the other + configuration files. + + It is suggested that variable names begin with an upper case letter + to distinguish them from variables used internally within the Shorewall + programs + + Example: + +
+     /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 + +
+ + Variables may be used anywhere in the other configuration + files. + Shorewall-perl users: If you use "$FW" on the right side of + assignments in the /etc/shorewall/params file, + you must also set the FW variable in that file. + + Example:/etc/shorewall/zones: + + #ZONE TYPE OPTIONS + fw firewall + +/etc/shorewall/params: + + FW=fw + BLARG=$FW:206.124.146.176 + + + Because the /etc/shorewall/params 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: + + + + The code should not have side effects, especially on other + shorewall configuration files. + + + + The code should be safe to execute multiple times without + producing different results. + + + + Should not depend on where the code is called from (the params + file is sourced by both /sbin/shorewall and + /usr/lib/shorewall/firewall). + + + + Should not assume anything about the state of Shorewall. + + + + The names of any functions or variables declared should begin + with an upper case letter. + + + + The /etc/shorewall/params 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 shorewall.conf, then the + params file is only + processed by the compiler; it is not run by the compiled + script. + + + + If you are using Shorewall Lite and if the + params script needs to set shell variables based + on the configuration of the firewall system, you can use this + trick: + + EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0") + + The shorewall-lite call command allows you to + to call interactively any Shorewall function that you can call in an + extension script. + + + + When expanding a variable, the acceptable forms of expansion depend + on whether you are using Shorewall-shell or Shorewall-perl. + + + + Shorewall-shell and all Shorewall versions prior to 4.0 can use + any form of expansion supported by the shell ($VAR, ${VAR}, + ${VAR:=val}, ...). + + + + Shorewall-perl only supports the $VAR and ${VAR} forms. + + +
+
Embedded Shell and Perl @@ -592,6 +711,35 @@ use Shorewall::Config qw/shorewall/; the firewall has started have absolutely no effect on the firewall's rule set. + For some sites, using DNS names is very risky. Here's an + example: + + teastep@ursa:~$ dig pop.gmail.com + +; <<>> DiG 9.4.2-P1 <<>> pop.gmail.com +;; global options: printcmd +;; Got answer: +;; ->>HEADER<<- 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. 300 IN CNAME gmail-pop.l.google.com. +gmail-pop.l.google.com. 300 IN A 209.85.201.109 +gmail-pop.l.google.com. 300 IN A 209.85.201.111 + + Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five + minutes later, the answer may change! + + So this rule may work for five minutes then suddently stop + working: + + #ACTION SOURCE DEST PROTO DEST +# PORT(S) +POP/ACCEPT loc net:pop.gmail.com + If your firewall rules include DNS names then: @@ -849,125 +997,6 @@ DNAT net loc:192.168.1.3 tcp 4000:4100
-
- Using Shell Variables - - You may use the /etc/shorewall/params file to - set shell variables that you can then use in some of the other - configuration files. - - It is suggested that variable names begin with an upper case letter - to distinguish them from variables used internally within the Shorewall - programs - - Example: - -
-     /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 - -
- - Variables may be used anywhere in the other configuration - files. - Shorewall-perl users: If you use "$FW" on the right side of - assignments in the /etc/shorewall/params file, - you must also set the FW variable in that file. - - Example:/etc/shorewall/zones: - - #ZONE TYPE OPTIONS - fw firewall - -/etc/shorewall/params: - - FW=fw - BLARG=$FW:206.124.146.176 - - - Because the /etc/shorewall/params 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: - - - - The code should not have side effects, especially on other - shorewall configuration files. - - - - The code should be safe to execute multiple times without - producing different results. - - - - Should not depend on where the code is called from (the params - file is sourced by both /sbin/shorewall and - /usr/lib/shorewall/firewall). - - - - Should not assume anything about the state of Shorewall. - - - - The names of any functions or variables declared should begin - with an upper case letter. - - - - The /etc/shorewall/params 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 shorewall.conf, then the - params file is only - processed by the compiler; it is not run by the compiled - script. - - - - If you are using Shorewall Lite and if the - params script needs to set shell variables based - on the configuration of the firewall system, you can use this - trick: - - EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0") - - The shorewall-lite call command allows you to - to call interactively any Shorewall function that you can call in an - extension script. - - - - When expanding a variable, the acceptable forms of expansion depend - on whether you are using Shorewall-shell or Shorewall-perl. - - - - Shorewall-shell and all Shorewall versions prior to 4.0 can use - any form of expansion supported by the shell ($VAR, ${VAR}, - ${VAR:=val}, ...). - - - - Shorewall-perl only supports the $VAR and ${VAR} forms. - - -
-
Using MAC Addresses