From acdf9b94a6c1f2e8f9405ea02ff802a30005767e Mon Sep 17 00:00:00 2001 From: teastep Date: Sat, 21 Aug 2004 15:42:31 +0000 Subject: [PATCH] Documentation Updates git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@1567 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb --- Shorewall-docs2/IPSEC-2.6.xml | 92 ++++- .../starting_and_stopping_shorewall.xml | 320 ++++++++++-------- 2 files changed, 271 insertions(+), 141 deletions(-) diff --git a/Shorewall-docs2/IPSEC-2.6.xml b/Shorewall-docs2/IPSEC-2.6.xml index 7afb4f2e2..cbf7496fc 100644 --- a/Shorewall-docs2/IPSEC-2.6.xml +++ b/Shorewall-docs2/IPSEC-2.6.xml @@ -15,7 +15,7 @@ - 2004-08-18 + 2004-08-19 2004 @@ -37,7 +37,7 @@ To use this support, your kernel and iptables must include the Netfilter+ipsec patches and policy match support and you must be running - Shorewall 2.1.4 or later. + Shorewall 2.1.5 or later. @@ -97,7 +97,60 @@ that is going to be encrypted and incoming traffic that has been decrypted must be matched against policies in the SPD. - + Shorewall provides support for policy matching in two ways: + + + + In /etc/shorewall/masq, traffic that will + later be encrypted is exempted from MASQUERADE/SNAT using existing + entries. If you want to MASQUERADE/SNAT outgoing traffic that will + later be encrypted, you must include an entry in the new IPSEC column + in that file. + + + + A new /etc/shorewall/ipsec file allows you + to associate zones with traffic that will be encrypted or that has + been decrypted. + + + + In summary, Shorewall 2.1.5 and later versions provide the + facilities to replace the use of ipsec pseudo-interfaces in zone and + MASQUERADE/SNAT definition. + + There are two cases to consider: + + + + Encrypted communication is used to/from all hosts in a + zone. + + The value Yes is placed in the + IPSEC column of the /etc/shorewall/ipsec entry + for the zone. + + + + Encrypted communication is used to/from only part of the hosts + in a zone. + + The value No is placed in the + IPSEC column of the /etc/shorewall/ipsec entry + for the zone and the new ipsec option + is specified in /etc/shorewall/hosts for those + hosts requiring secure communication. + + + + + For simple zones such as are shown in the following examples, the + two techniques are equivalent and are used interchangably. + + + Finally, the OPTIONS, IN OPTIONS and OUT OPTIONS columns in + /etc/shorewall/ipsec can be used to match the zone to a particular (set + of) SA(s) used to encrypt and decrypt traffic to/from the zone.
@@ -186,6 +239,16 @@ vpn eth0:192.168.1.0/24 ipsec #LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE + Assuming that you want to give each local network free access to the + remote network and vice versa, you would need the following + /etc/shorewall/policy entries on each system: + +
+ #SOURCE DESTINATION POLICY LEVEL BURST:LIMIT +loc vpn ACCEPT +vpn loc ACCEPT +
+ Once you have these entries in place, restart Shorewall (type shorewall restart); you are now ready to configure IPSEC.
@@ -212,6 +275,7 @@ vpn eth0:192.168.1.0/24 ipsec #ZONE DISPLAY COMMENTS net Internet The big bad internet vpn VPN Road Warriors +loc local Local Network (192.168.1.0/24) #LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE @@ -313,8 +377,8 @@ spdadd 192.168.20.40/32 192.168.20.10/32 any -P in ipsec esp/transport/192.168. /etc/shorewall/zones: #ZONE DISPLAY COMMENTS -loc Local Local Network net Net Internet +loc Local Local Network #LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE /etc/shorewall/interfaces: @@ -323,12 +387,30 @@ net Net Internet net eth0 detect routefilter,dhcp,tcpflags #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE + /etc/shorewall/tunnels: + + #TYPE ZONE GATEWAY GATEWAY +# ZONE +ipsec:noah net 192.168.20.0/24 loc + + /etc/shorewall/ipsec: + + #ZONE IPSEC OPTIONS IN OUT +# ONLY OPTIONS OPTIONS +loc Yes mode=transport + /etc/shorewall/hosts: #ZONE HOST(S) OPTIONS -loc eth0:192.168.20.0/24 ipsec +loc eth0:192.168.20.0/24 #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS LINE -- DO NOT REMOVE + It is worth noting that although loc is a + sub-zone of net, because loc + is an IPSEC-only zone it does not need to be defined before + net in + /etc/shorewall/zones. + /etc/shorewall/policy: #SOURCE DEST POLICY LOG LEVEL LIMIT:BURST diff --git a/Shorewall-docs2/starting_and_stopping_shorewall.xml b/Shorewall-docs2/starting_and_stopping_shorewall.xml index 399adb7d0..a60612676 100644 --- a/Shorewall-docs2/starting_and_stopping_shorewall.xml +++ b/Shorewall-docs2/starting_and_stopping_shorewall.xml @@ -29,7 +29,8 @@ 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. + GNU Free Documentation + License. @@ -41,8 +42,8 @@ - /sbin/shorewall ̶ The program that you use - to interact with Shorewall. Normally the root user's PATH includes + /sbin/shorewall — The program that you use + to interact with Shorewall. Normally the root user's PATH includes /sbin and the program can be run from a shell prompt by simply typing shorewall followed by a command. To see a list of supported commands, use the @@ -59,16 +60,17 @@ /etc/shorewall — The default directory where Shorewall looks for configuration files. See the section - entitled Alternate Configuration Directories - for information about how you can direct Shorewall to look in other - directories. + entitled Alternate Configuration + Directories for information about how you can direct Shorewall + to look in other directories. - /etc/init.d/shorewall (/etc/rc.d/firewall.rc - on Slackware) — The script run by init (the program - responsible for startup and shutdown of your system) to start - Shorewall at boot time and to stop Shorewall at shutdown. + /etc/init.d/shorewall + (/etc/rc.d/firewall.rc on Slackware) — The script + run by init (the program responsible for startup + and shutdown of your system) to start Shorewall at boot time and to + stop Shorewall at shutdown. @@ -79,8 +81,9 @@ /usr/share/shorewall/functions — A library - of Bourne Shell functions used by both /sbin/shorewall - and /usr/share/shorewall/firewall. + of Bourne Shell functions used by both + /sbin/shorewall and + /usr/share/shorewall/firewall. @@ -88,21 +91,23 @@
Starting, Stopping and Clearing - As explained in the Introduction, - Shorewall is not something that runs all of the time in your system. - Nevertheless, for integrating Shorewall into your initialization scripts - it is useful to speak of starting Shorewall and + As explained in the Introduction, Shorewall is not something + that runs all of the time in your system. Nevertheless, for integrating + Shorewall into your initialization scripts it is useful to speak of + starting Shorewall and stopping Shorewall. - Shorewall is started using the shorewall start - command. Once the start command completes successfully, Netfilter is - configured as described in your Shorewall configuration files. If - there is an error during shorewall start, then if - you have a saved configuration then that - configuration is restored. Otherwise, an implicit shorewall - stop is executed. + Shorewall is started using the shorewall + start command. Once the start command completes + successfully, Netfilter is configured as described in your Shorewall + configuration files. If there is an error during shorewall + start, then if you have a saved + configuration then that configuration is restored. + Otherwise, an implicit shorewall stop is + executed. @@ -113,7 +118,8 @@ The shorewall stop command does not remove all netfilter rules and open your firewall for all traffic to pass. It rather places your firewall in a safe state defined by the - contents of your /etc/shorewall/routestopped + contents of your /etc/shorewall/routestopped file and the setting of ADMINISABSENTMINDED in /etc/shorewall/shorewall.conf. @@ -139,16 +145,17 @@ Tracing Command Execution If you include the word trace as - the first parameter to an /sbin/shorewall command - that transfers control to /usr/share/shorewall/firewall, - execution of the latter program will be traced to STDERR. + the first parameter to an /sbin/shorewall command + that transfers control to + /usr/share/shorewall/firewall, execution of the + latter program will be traced to STDERR. Tracing <command>shorewall start</command> To trace the execution of shorewall start and write the trace to the file /tmp/trace, you would - enter:shorewall trace start 2> /tmp/trace + enter:shorewall trace start 2> /tmp/trace
@@ -159,26 +166,38 @@ that Shorewall will start automatically at boot time. If you are using the install.sh script from the .tgz and it cannot determine how to configure automatic startup, a message to that effect will be - displayed. You will need to consult your distribution's documentation - to see how to integrate the /etc/init.d/shorewall - script into the distribution's startup mechanism.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. + displayed. You will need to consult your distribution's documentation to + see how to integrate the /etc/init.d/shorewall script + into the distribution's startup mechanism. + + + 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. + + +
- Saving a Working Configuration for Error Recovery and Fast Startup + Saving a Working Configuration for Error Recovery and Fast + Startup Once you have Shorewall working the way that you want it to, you can use shorewall save to save the - commands necessary to recreate that configuration in a - restore script. + commands necessary to recreate that configuration in a restore + script. In its simplest form, the save command is just: @@ -191,9 +210,9 @@ different file name may also be specified in the save command: - shorewall save <filename> + shorewall save <filename> - Where <filename> is a simple file name + Where <filename> is a simple file name (no slashes). Once created, the default restore script serves several useful @@ -211,8 +230,9 @@ shorewall -f start) causes Shorewall to look for the default restore script and if it exists, the script is run. This is much faster than starting Shorewall using the normal mechanism of - reading the configuration files and running iptables - dozens or even hundreds of times. /etc/init.d/shorewall + reading the configuration files and running + iptables dozens or even hundreds of times. + /etc/init.d/shorewall (/etc/rc.d/firewall.rc) uses the -f option when it is processing a request to start Shorewall. @@ -221,11 +241,12 @@ The shorewall restore command can be used at any time to quickly configure the firewall. - shorewall restore [ <filename> ] + shorewall restore [ <filename> ] - If no <filename> is given, the + If no <filename> is given, the default restore script is used. Otherwise, the script - /var/lib/shorewall/<filename> is used. + /var/lib/shorewall/<filename> is + used. @@ -233,15 +254,16 @@ different Shorewall firewall configurations and switch between them quickly using the restore command. - Restore scripts may be removed using the shorewall forget - command: + Restore scripts may be removed using the shorewall + forget command: - shorewall forget [ <filename> ] + shorewall forget [ <filename> ] - If no <filename> is given, the default - restore script is removed. Otherwise, /var/lib/shorewall/<filename> - is removed (of course, you can also use the Linux rm - command from the shell prompt to remove these files). + If no <filename> is given, the default + restore script is removed. Otherwise, + /var/lib/shorewall/<filename> is removed (of + course, you can also use the Linux rm command from the + shell prompt to remove these files).
@@ -249,27 +271,29 @@ As explained above, Shorewall normally looks for configuration files in the directory /etc/shorewall. - The shorewall start, shorewall restart, - shorewall check, and shorewall try commands - allow you to specify a different directory for Shorewall to check before - looking in /etc/shorewall: + The shorewall start, shorewall + restart, shorewall check, and + shorewall try commands allow you to specify a different + directory for Shorewall to check before looking in /etc/shorewall: - shorewall [ -c <configuration-directory> ] {start|restart|check} - shorewall try <configuration-directory> [ <timeout> ] + shorewall [ -c <configuration-directory> ] {start|restart|check} + shorewall try <configuration-directory> [ <timeout> ] - If a <configuration-directory> is + 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: + class="directory">/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: - If you haven't saved the current working configuration, do - so using shorewall save. + If you haven't saved the current working configuration, do so + using shorewall save. @@ -281,8 +305,8 @@ - <copy any files that you need to change from /etc/shorewall - to . and change them here> + <copy any files that you need to change from /etc/shorewall + to . and change them here> @@ -290,7 +314,7 @@ - <correct any errors found by check and check again> + <correct any errors found by check and check again> @@ -298,10 +322,10 @@ - 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 restore your configuration. + 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 restore + your configuration. When the new configuration works then just: @@ -332,13 +356,14 @@ add - shorewall add <interface>[:<host>] - <zone> + shorewall add <interface>[:<host>] + <zone> Adds a host or subnet to a dynamic zone usually used with - VPN's. + VPN's. - Example: shorewall add ipsec0:192.0.2.24 vpn1 + Example: shorewall add ipsec0:192.0.2.24 + vpn1 adds the address 192.0.2.24 from interface ipsec0 to the zone vpn1. @@ -349,7 +374,7 @@ allow - shorewall allow <address> ... + shorewall allow <address> ... Re-enables receipt of packets from hosts previously blacklisted by a drop or reject command. @@ -363,7 +388,7 @@ check - shorewall [ -c <configuration-directory> ] + shorewall [ -c <configuration-directory> ] check Performs a cursory validation of the zones, interfaces, hosts, @@ -391,15 +416,16 @@ delete - shorewall delete <interface>[:<host>] - <zone> + shorewall delete <interface>[:<host>] + <zone> Deletes the specified interface (and host if included) from the specified zone. Example: - shorewall delete ipsec0:192.0.2.24 vpn1 + shorewall delete ipsec0:192.0.2.24 + vpn1 deletes the address 192.0.2.24 from interface ipsec0 from zone vpn1 @@ -410,10 +436,10 @@ drop - shorewall drop <address> ... + shorewall drop <address> ... - Causes packets from the specified <address> - to be ignored + Causes packets from the specified + <address> to be ignored @@ -421,11 +447,14 @@ forget - shorewall forget [ <filename> ] + shorewall forget [ <filename> + ] - Deletes /var/lib/shorewall/<filename>. - If no <filename> is given then the file - specified by RESTOREFILE in /etc/shorewall/shorewall.conf + Deletes + /var/lib/shorewall/<filename>. If no + <filename> is given then the file + specified by RESTOREFILE in /etc/shorewall/shorewall.conf is removed. @@ -434,9 +463,11 @@ help - shorewall help [<command> | host | address ] + shorewall help [<command> | host | address + ] - Display helpful information about the shorewall commands. + Display helpful information about the shorewall + commands. @@ -448,7 +479,8 @@ Produces several reports about the Shorewall packet log messages in the current log file specified by the LOGFILE option in - /etc/shorewall/shorewall.conf. + /etc/shorewall/shorewall.conf. @@ -456,11 +488,12 @@ ipcalc - shorewall ipcalc [ <address> <mask> | - <address>/<vlsm> ] + shorewall ipcalc [ <address> <mask> | + <address>/<vlsm> ] Ipcalc displays the network address, broadcast address, - network in CIDR notation and netmask corresponding to the input[s]. + network in CIDR notation and netmask corresponding to the + input[s]. Example: @@ -473,7 +506,7 @@ shorewall iprange - <address1>-<address2> + <address1>-<address2> Iprange decomposes the specified range of IP addresses into the equivalent list of network/host addresses. @@ -484,7 +517,8 @@ logwatch - shorewall logwatch [<refresh interval>] + shorewall logwatch [<refresh + interval>] Monitors the log file specified by theLOGFILE option in /etc/shorewall/shorewall.conf @@ -497,7 +531,8 @@ monitor - shorewall [-x] monitor [<refresh_interval>] + shorewall [-x] monitor + [<refresh_interval>] Continuously display the firewall status, last 20 log entries and nat. When the log entry display changes, an audible alarm is @@ -527,10 +562,10 @@ reject - shorewall reject <address> ... + shorewall reject <address> ... - Causes packets from the specified <address>s - to be rejected + Causes packets from the specified + <address>s to be rejected @@ -540,7 +575,8 @@ shorewall reset - All the packet and byte counters in the firewall are reset. + All the packet and byte counters in the firewall are + reset. @@ -548,8 +584,8 @@ restart - shorewall [ -q ] [ -c - <configuration-directory> ] restart + shorewall [ -q ] [ -c <configuration-directory> + ] restart Restart is similar to shorewall stop followed by shorewall start. Existing connections @@ -562,15 +598,19 @@ restore - shorewall [ -q ] restore [ <filename> ] + shorewall [ -q ] restore [ <filename> + ] Restore Shorewall to a state saved using the shorewall save command Existing connections are - maintained. The <filename> names a - restore file in /var/lib/shorewall - created using shorewall save; if no <filename> - is given then Shorewall will be restored from the file specified by - the RESTOREFILE option in /etc/shorewall/shorewall.conf. + maintained. The <filename> names a + restore file in /var/lib/shorewall created using + shorewall save; if no + <filename> is given then Shorewall will + be restored from the file specified by the RESTOREFILE option in + /etc/shorewall/shorewall.conf. @@ -578,14 +618,16 @@ save - shorewall save [ <filename> ] + shorewall save [ <filename> ] The dynamic data is stored in /var/lib/shorewall/save. The - state of the firewall is stored in /var/lib/shorewall/<filename> - for use by the shorewall restore and - shorewall -f start commands. If <filename> + state of the firewall is stored in + /var/lib/shorewall/<filename> for use by + the shorewall restore and shorewall -f + start commands. If <filename> is not given then the state is saved in the file specified by the - RESTOREFILE option in /etc/shorewall/shorewall.conf. + RESTOREFILE option in /etc/shorewall/shorewall.conf. @@ -593,12 +635,12 @@ show - shorewall [ -x ] show [ <chain> [ - <chain> ...] |classifiers|connections|log|nat|tc|tos] + shorewall [ -x ] show [ <chain> [ <chain> + ...] |classifiers|connections|log|nat|tc|tos] - shorewall [ -x ] show <chain> [ - <chain> ... ] - produce a verbose report about - the Netfilter chain(s). (iptables -L chain -n -v) + shorewall [ -x ] show <chain> [ <chain> + ... ] - produce a verbose report about the Netfilter + chain(s). (iptables -L chain -n -v) shorewall [ -x ] show nat - produce a verbose report about the nat table. (iptables -t nat -L -n @@ -630,14 +672,15 @@ shorewall [ -q ] [ -f ] [ -c - <configuration-directory> ] start + <configuration-directory> ] start Start shorewall. Existing connections through shorewall managed interfaces are untouched. New connections will be allowed only if they are allowed by the firewall rules or policies. If -q is specified, less detail is displayed making it easier to spot warnings If -f is specified, the saved configuration specified by - the RESTOREFILE option in /etc/shorewall/shorewall.conf + the RESTOREFILE option in /etc/shorewall/shorewall.conf will be restored if that saved configuration exists @@ -649,12 +692,14 @@ shorewall stop Stops the firewall. All existing connections, except those - listed in /etc/shorewall/routestopped + listed in /etc/shorewall/routestopped or permitted by the ADMINISABSENTMINDED option in /etc/shorewall/shorewall.conf, are taken down. The only new traffic permitted through the firewall - is from systems listed in /etc/shorewall/routestopped - or by ADMINISABSENTMINDED. + is from systems listed in + /etc/shorewall/routestopped or by + ADMINISABSENTMINDED. @@ -675,8 +720,8 @@ try - shorewall try <configuration-directory> [ - <timeout> ] + shorewall try <configuration-directory> [ + <timeout> ] Restart shorewall using the specified configuration. If an error occurs during the restart, then another shorewall restart is @@ -686,7 +731,8 @@ When restarting using the default configuration, if the default restore script (as specified by the RESTOREFILE setting in - /etc/shorewall/shorewall.conf) + /etc/shorewall/shorewall.conf) exists. then that script is used. @@ -712,7 +758,8 @@ 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; + That is because the actual transitions are done by + /usr/share/shorewall/firewall; /sbin/shorewall runs firewall according to the following table: @@ -757,7 +804,8 @@ firewall restart - Logically equivalent to firewall stop;firewall start + Logically equivalent to firewall stop;firewall + start @@ -805,7 +853,7 @@ shorewall try - firewall -c <new configuration> restart If + firewall -c <new configuration> restart If unsuccessful then firewall start (standard configuration) If timeout then firewall restart (standard configuration)