diff --git a/docs/CompiledPrograms.xml b/docs/CompiledPrograms.xml index 0dde449a3..83d61e813 100644 --- a/docs/CompiledPrograms.xml +++ b/docs/CompiledPrograms.xml @@ -5,7 +5,7 @@ - Compiled Firewall Programs and Shorewall Lite + Shorewall Lite and Compiled Firewall Programs @@ -50,12 +50,548 @@ Lite installed and can serve as the firewall creation script for that system. +
+ Shorewall Lite + + Shorewall Lite is a companion product to Shorewall and is designed + to allow you to maintain all Shorewall configuration information on a + single system within your network. + + + + You install the full Shorewall release on one system within + your network. You need not configure Shorewall there and you may + totally disable startup of Shorewall in your init scripts. For ease + of reference, we call this system the 'administrative + system'. + + The administrative system may be a GNU/Linux system, a Windows + system running Cygwin or + an Apple MacIntosh + running OS X. Install from a shell prompt using the install.sh script. + + + + On each system where you wish to run a Shorewall-generated + firewall, you install Shorewall Lite. For ease of reference, we will + call these systems the 'firewall systems'. + + + The firewall systems do NOT + need to have the full Shorewall product installed but rather only + the Shorewall Lite product. Shorewall and Shorewall Lite may be + installed on the same system but that isn't encouraged. + + + + + On the administrative system you create a separate 'export + directory' for each firewall system. You copy the contents of + /usr/share/shorewall/configfiles into + each export directory. + + + Users of Debian and derivatives that install the package + from their distribution will be disappointed to find that + /usr/share/shorewall/configfiles does + not exist on their systems. They will instead need to + either: + + + + Copy the files in + /usr/share/doc/shorewall/default-config/ into each export + directory. + + + + Copy /etc/shorewall/shorewall.conf into each export + directory and remove /etc/shorewall from the CONFIG_PATH + setting in the copied files. + + + + or + + + + Download the Shorewall tarball corresponding to their + package version. + + + + Untar and copy the files from the + configfiles sub-directory in the untarred + shorewall-... directory. + + + + + + + The /etc/shorewall/shorewall.conf file is + used to determine the VERBOSITY setting which determines how much + output the compiler generates. All other settings are taken from the + shorewall.conf file in the remote systems + export directory. + + + If you want to be able to allow non-root users to manage + remote firewall systems, then the files + /etc/shorewall/params and + /etc/shorewall/shorewall.conf must be + readable by all users on the administrative system. Not all + packages secure the files that way and you may have to change the + file permissions yourself. + + + + + On each firewall system, If you are running Debian or one of + its derivatives like Ubuntu then edit + /etc/default/shorewall-lite and set + startup=1. + + + + On the administrative system, for each firewall system you do + the following (this may be done by a non-root user who has root ssh + access to the firewall system): + + + + modify the files in the corresponding export directory + appropriately (i.e., just as you would if you were + configuring Shorewall on the firewall system itself). + It's a good idea to include the IP address of the administrative + system in the routestopped + file. + + It is important to understand that with Shorewall Lite, + the firewall's export directory on the administrative system + acts as /etc/shorewall + for that firewall. So when the Shorewall documentation gives + instructions for placing entries in files in the firewall's + /etc/shorewall, when + using Shorewall Lite you make those changes in the firewall's + export directory on the administrative system. + + The CONFIG_PATH variable is treated as follows: + + + + The value of CONFIG_PATH in + /etc/shorewall/shorewall.conf is + ignored when compiling for export (the -e option in given) + and when the load or + reload command is being executed (see + below). + + + + The value of CONFIG_PATH in the + shorewall.conf file in the export + directory is used to search for configuration files during + compilation of that configuration. + + + + The value of CONFIG_PATH used when the script is run + on the firewall system is + "/etc/shorewall-lite:/usr/share/shorewall-lite". + + + + + + cd <export directory> +/sbin/shorewall load firewall + + The load + command compiles a firewall script from the configuration files + in the current working directory (using shorewall + compile -e), copies that file to the remote system via + scp and starts Shorewall Lite on the remote system via + ssh. + + Example (firewall's DNS name is 'gateway'): + + /sbin/shorewall load gateway + Although scp and ssh are used by default, you can use + other utilities by setting RSH_COMMAND and RCP_COMMAND in + /etc/shorewall/shorewall.conf. + + + The first time that you issue a load + command, Shorewall will use ssh to run + /usr/share/shorewall-lite/shorecap on the + remote firewall to create a capabilities file in the firewall's + administrative direction. See below. + + + + + + If you later need to change the firewall's configuration, + change the appropriate files in the firewall's export directory + then: + + cd <export directory> +/sbin/shorewall reload firewall + + The reload + command compiles a firewall script from the configuration files in + the current working directory (using shorewall compile + -e), copies that file to the remote system via scp and + restarts Shorewall Lite on the remote system via ssh. The reload command also supports the '-c' + option. + + I personally place a Makefile in each + export directory as follows: + +
+ # Shorewall Packet Filtering Firewall Export Directory Makefile - V3.3 +# +# This program is under GPL [http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt] +# +# (c) 2006 - Tom Eastep (teastep@shorewall.net) +# +# Shorewall documentation is available at http://www.shorewall.net +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of Version 2 of the GNU General Public License +# as published by the Free Software Foundation. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +################################################################################ +# Place this file in each export directory. Modify each copy to set HOST +# to the name of the remote firewall corresponding to the directory. +# +# To make the 'firewall' script, type "make". +# +# Once the script is compiling correctly, you can install it by +# typing "make install". +# +################################################################################ +# V A R I A B L E S +# +# Files in the export directory on which the firewall script does not depend +# +IGNOREFILES = firewall% Makefile% trace% %~ +# +# Remote Firewall system +# +HOST = gateway +# +# Save some typing +# +LITEDIR = /var/lib/shorewall-lite +# +# Set this if the remote system has a non-standard modules directory +# +MODULESDIR= +# +# Default target is the firewall script +# +################################################################################ +# T A R G E T S +# +all: firewall +# +# Only generate the capabilities file if it doesn't already exist +# +capabilities: + ssh root@$(HOST) "MODULESDIR=$(MODULESDIR) /usr/share/shorewall-lite/shorecap > $(LITEDIR)/capabilities" + scp root@$(HOST):$(LITEDIR)/capabilities . +# +# Compile the firewall script. Using the 'wildcard' function causes "*" to be expanded so that +# 'filter-out' will be presented with the list of files in this directory rather than "*" +# +firewall: $(filter-out $(IGNOREFILES) capabilities , $(wildcard *) ) capabilities + shorewall compile -e . firewall +# +# Only reload on demand. +# +install: firewall + scp firewall firewall.conf root@$(HOST):$(LITEDIR) + ssh root@$(HOST) "/sbin/shorewall-lite restart" +# +# Save running configuration +# +save: + ssh root@$(HOST) "/sbin/shorewall-lite save" +# +# Remove generated files +# +clean: + rm -f capabilities firewall firewall.conf reload + +
+ + That way, after I've changed the configuration, I can simply + type make or make + install. + + + The above Makefile is available at http://www.shorewall.net/pub/shorewall/contrib/Shorewall-lite/ + + + + I omit trace% because I often trace compiler execution while + I'm debugging new versions of Shorewall. + + + + + There is a shorewall-lite.conf file installed + as part of Shorewall Lite + (/etc/shorewall-lite/shorewall-lite.conf). You can + use that file on the firewall system to override some of the settings + from the shorewall.conf file in the export directory. + + Settings that you can override are: + +
+ + VERBOSITY + + LOGFILE + + LOGFORMAT + + IPTABLES + + PATH + + SHOREWALL_SHELL + + SUBSYSLOCK + + RESTOREFILE + +
+ + You will normally never touch + /etc/shorewall-lite/shorewall-lite.conf unless you + run Debian or one of its derivatives (see above). + + The /sbin/shorewall-lite program included + with Shorewall Lite supports the same set of commands as the + /sbin/shorewall program in a full Shorewall + installation with the following exceptions: + +
+ + add + + compile + + delete + + refresh + + reload + + try + + safe-start + + safe-restart + + show actions + + show macros + +
+ + On systems with only Shorewall Lite installed, I recommend that + you create a symbolic link /sbin/shorewall and + point it at /sbin/shorewall-lite. That way, you can + use shorewall as the command regardless of which + product is installed. + +
+ ln -sf shorewall-lite /sbin/shorewall +
+ +
+ Converting a system from Shorewall to Shorewall Lite + + Converting a firewall system that is currently running Shorewall + to run Shorewall Lite instead is straight-forward. + + + + On the administrative system, create an export directory for + the firewall system. + + + + Copy the contents of /etc/shorewall/ from the firewall + system to the export directory on the administrative + system. + + + + On the firewall system: + + Be sure that the IP address of the administrative system is + included in the firewall's export directory + routestopped file. + + shorewall stop + + We recommend that you uninstall + Shorewall at this point. + + + + Install Shorewall Lite on the firewall system. + + If you are running Debian or one of its derivatives like + Ubuntu then edit /etc/default/shorewall-lite + and set startup=1. + + + + On the administrative system: + + It's a good idea to include the IP address of the + administrative system in the firewall system's routestopped + file. + + Also, edit the shorewall.conf file in + the firewall's export directory and change the CONFIG_PATH setting + to remove /etc/shorewall. + You can replace it with /usr/share/shorewall/configfiles if + you like. + + Example: + +
+ Before editing: + + CONFIG_PATH=/etc/shorewall:/usr/share/shorewall + + After editing: + + CONFIG_PATH=/usr/share/shorewall/configfiles:/usr/share/shorewall +
+ + Changing CONFIG_PATH will ensure that subsequent + compilations using the export directory will not include any files + from /etc/shorewall other + than shorewall.conf and + params. + + If you set variables in the params file, there are a couple + of issues: + + The params file is not processed at run + time if you set EXPORTPARAMS=No in + shorewall.conf. For run-time setting of shell + variables, use the init extension + script. + + If the params file 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. + + After having made the above changes to the firewall's export + directory, execute the following commands. + +
+ cd <export directory> +/sbin/shorewall load <firewall system> + + + Example (firewall's DNS name is 'gateway'): + + /sbin/shorewall load gateway +
+ + The first time that you issue a load + command, Shorewall will use ssh to run + /usr/share/shorewall-lite/shorecap on the + remote firewall to create a capabilities file in the firewall's + administrative direction. See below. + + The load + command compiles a firewall script from the configuration files in + the current working directory (using shorewall compile + -e), copies that file to the remote system via + scp and starts Shorewall Lite on the remote + system via ssh. + + + + If you later need to change the firewall's configuration, + change the appropriate files in the firewall's export directory + then: + + cd <export directory> +/sbin/shorewall reload firewall + + The reload + command compiles a firewall script from the configuration files in + the current working directory (using shorewall compile + -e), copies that file to the remote system via + scp and restarts Shorewall Lite on the remote + system via ssh. + + + + If the kernel/iptables configuration on the firewall later + changes and you need to create a new + capabilities file, do the following on the + firewall system: + + /usr/share/shorewall-lite/shorecap > capabilities +scp capabilities <admin system>:<this system's config dir> + + Or simply use the -c option the next time that you use the + reload command (e.g., shorewall reload + -c gateway). + + +
+
+
Restrictions - While compiled Shorewall programs are useful in many cases, there - are some important restrictions that you should be aware of before - attempting to use them. + While compiled Shorewall programs (as are used in Shorewall Lite) + are useful in many cases, there are some important restrictions that you + should be aware of before attempting to use them. @@ -166,534 +702,6 @@
-
- Shorewall Lite - - Shorewall Lite is a companion product to Shorewall and is designed - to allow you to maintain all Shorewall configuration information on a - single system within your network. - - - - You install the full Shorewall release on one system within your - network. You need not configure Shorewall there and you may totally - disable startup of Shorewall in your init scripts. For ease of - reference, we call this system the 'administrative system'. - - The administrative system may be a GNU/Linux system, a Windows - system running Cygwin or - an Apple MacIntosh - running OS X. Install from a shell prompt using the install.sh script. - - - - On each system where you wish to run a Shorewall-generated - firewall, you install Shorewall Lite. For ease of reference, we will - call these systems the 'firewall systems'. - - - The firewall systems do NOT - need to have the full Shorewall product installed but rather only - the Shorewall Lite product. Shorewall and Shorewall Lite may be - installed on the same system but that isn't encouraged. - - - - - On the administrative system you create a separate 'export - directory' for each firewall system. You copy the contents of - /usr/share/shorewall/configfiles into - each export directory. - - - Users of Debian and derivatives that install the package from - their distribution will be disappointed to find that /usr/share/shorewall/configfiles does - not exist on their systems. They will instead need to either: - - - - Copy the files in /usr/share/doc/shorewall/default-config/ - into each export directory. - - - - Copy /etc/shorewall/shorewall.conf into each export - directory and remove /etc/shorewall from the CONFIG_PATH setting - in the copied files. - - - - or - - - - Download the Shorewall tarball corresponding to their - package version. - - - - Untar and copy the files from the - configfiles sub-directory in the untarred - shorewall-... directory. - - - - - - - The /etc/shorewall/shorewall.conf file is - used to determine the VERBOSITY setting which determines how much - output the compiler generates. All other settings are taken from the - shorewall.conf file in the remote systems export - directory. - - - If you want to be able to allow non-root users to manage - remote firewall systems, then the files - /etc/shorewall/params and - /etc/shorewall/shorewall.conf must be readable - by all users on the administrative system. Not all packages secure - the files that way and you may have to change the file permissions - yourself. - - - - - On each firewall system, If you are running Debian or one of its - derivatives like Ubuntu then edit - /etc/default/shorewall-lite and set - startup=1. - - - - On the administrative system, for each firewall system you do - the following (this may be done by a non-root user who has root ssh - access to the firewall system): - - - - modify the files in the corresponding export directory - appropriately (i.e., just as you would if you were - configuring Shorewall on the firewall system itself). - It's a good idea to include the IP address of the administrative - system in the routestopped - file. - - It is important to understand that with Shorewall Lite, the - firewall's export directory on the administrative system acts as - /etc/shorewall for that - firewall. So when the Shorewall documentation gives instructions - for placing entries in files in the firewall's /etc/shorewall, when using Shorewall - Lite you make those changes in the firewall's export directory on - the administrative system. - - The CONFIG_PATH variable is treated as follows: - - - - The value of CONFIG_PATH in - /etc/shorewall/shorewall.conf is ignored - when compiling for export (the -e option in given) and when - the load or reload - command is being executed (see below). - - - - The value of CONFIG_PATH in the - shorewall.conf file in the export - directory is used to search for configuration files during - compilation of that configuration. - - - - The value of CONFIG_PATH used when the script is run on - the firewall system is - "/etc/shorewall-lite:/usr/share/shorewall-lite". - - - - - - cd <export directory> -/sbin/shorewall load firewall - - The load - command compiles a firewall script from the configuration files in - the current working directory (using shorewall compile - -e), copies that file to the remote system via scp and - starts Shorewall Lite on the remote system via ssh. - - Example (firewall's DNS name is 'gateway'): - - /sbin/shorewall load gateway - Although scp and ssh are used by default, you can use - other utilities by setting RSH_COMMAND and RCP_COMMAND in - /etc/shorewall/shorewall.conf. - - - The first time that you issue a load - command, Shorewall will use ssh to run - /usr/share/shorewall-lite/shorecap on the - remote firewall to create a capabilities file in the firewall's - administrative direction. See below. - - - - - - If you later need to change the firewall's configuration, change - the appropriate files in the firewall's export directory then: - - cd <export directory> -/sbin/shorewall reload firewall - - The reload - command compiles a firewall script from the configuration files in the - current working directory (using shorewall compile - -e), copies that file to the remote system via scp and - restarts Shorewall Lite on the remote system via ssh. The reload command also supports the '-c' - option. - - I personally place a Makefile in each - export directory as follows: - -
- # Shorewall Packet Filtering Firewall Export Directory Makefile - V3.3 -# -# This program is under GPL [http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt] -# -# (c) 2006 - Tom Eastep (teastep@shorewall.net) -# -# Shorewall documentation is available at http://www.shorewall.net -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of Version 2 of the GNU General Public License -# as published by the Free Software Foundation. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. -################################################################################ -# Place this file in each export directory. Modify each copy to set HOST -# to the name of the remote firewall corresponding to the directory. -# -# To make the 'firewall' script, type "make". -# -# Once the script is compiling correctly, you can install it by -# typing "make install". -# -################################################################################ -# V A R I A B L E S -# -# Files in the export directory on which the firewall script does not depend -# -IGNOREFILES = firewall% Makefile% trace% %~ -# -# Remote Firewall system -# -HOST = gateway -# -# Save some typing -# -LITEDIR = /var/lib/shorewall-lite -# -# Set this if the remote system has a non-standard modules directory -# -MODULESDIR= -# -# Default target is the firewall script -# -################################################################################ -# T A R G E T S -# -all: firewall -# -# Only generate the capabilities file if it doesn't already exist -# -capabilities: - ssh root@$(HOST) "MODULESDIR=$(MODULESDIR) /usr/share/shorewall-lite/shorecap > $(LITEDIR)/capabilities" - scp root@$(HOST):$(LITEDIR)/capabilities . -# -# Compile the firewall script. Using the 'wildcard' function causes "*" to be expanded so that -# 'filter-out' will be presented with the list of files in this directory rather than "*" -# -firewall: $(filter-out $(IGNOREFILES) capabilities , $(wildcard *) ) capabilities - shorewall compile -e . firewall -# -# Only reload on demand. -# -install: firewall - scp firewall firewall.conf root@$(HOST):$(LITEDIR) - ssh root@$(HOST) "/sbin/shorewall-lite restart" -# -# Save running configuration -# -save: - ssh root@$(HOST) "/sbin/shorewall-lite save" -# -# Remove generated files -# -clean: - rm -f capabilities firewall firewall.conf reload - -
- - That way, after I've changed the configuration, I can simply - type make or make - install. - - - The above Makefile is available at http://www.shorewall.net/pub/shorewall/contrib/Shorewall-lite/ - - - - I omit trace% because I often trace compiler execution while - I'm debugging new versions of Shorewall. - - - - - There is a shorewall-lite.conf file installed - as part of Shorewall Lite - (/etc/shorewall-lite/shorewall-lite.conf). You can - use that file on the firewall system to override some of the settings from - the shorewall.conf file in the export directory. - - Settings that you can override are: - -
- - VERBOSITY - - LOGFILE - - LOGFORMAT - - IPTABLES - - PATH - - SHOREWALL_SHELL - - SUBSYSLOCK - - RESTOREFILE - -
- - You will normally never touch - /etc/shorewall-lite/shorewall-lite.conf unless you - run Debian or one of its derivatives (see above). - - The /sbin/shorewall-lite program included with - Shorewall Lite supports the same set of commands as the - /sbin/shorewall program in a full Shorewall - installation with the following exceptions: - -
- - add - - compile - - delete - - refresh - - reload - - try - - safe-start - - safe-restart - - show actions - - show macros - -
- - On systems with only Shorewall Lite installed, I recommend that you - create a symbolic link /sbin/shorewall and point it - at /sbin/shorewall-lite. That way, you can use - shorewall as the command regardless of which product is - installed. - -
- ln -sf shorewall-lite /sbin/shorewall -
- -
- Converting a system from Shorewall to Shorewall Lite - - Converting a firewall system that is currently running Shorewall - to run Shorewall Lite instead is straight-forward. - - - - On the administrative system, create an export directory for - the firewall system. - - - - Copy the contents of /etc/shorewall/ from the firewall - system to the export directory on the administrative system. - - - - On the firewall system: - - Be sure that the IP address of the administrative system is - included in the firewall's export directory - routestopped file. - - shorewall stop - - We recommend that you uninstall - Shorewall at this point. - - - - Install Shorewall Lite on the firewall system. - - If you are running Debian or one of its derivatives like - Ubuntu then edit /etc/default/shorewall-lite - and set startup=1. - - - - On the administrative system: - - It's a good idea to include the IP address of the - administrative system in the firewall system's routestopped - file. - - Also, edit the shorewall.conf file in the - firewall's export directory and change the CONFIG_PATH setting to - remove /etc/shorewall. You - can replace it with /usr/share/shorewall/configfiles if you - like. - - Example: - -
- Before editing: - - CONFIG_PATH=/etc/shorewall:/usr/share/shorewall - - After editing: - - CONFIG_PATH=/usr/share/shorewall/configfiles:/usr/share/shorewall -
- - Changing CONFIG_PATH will ensure that subsequent compilations - using the export directory will not include any files from /etc/shorewall other than - shorewall.conf and - params. - - If you set variables in the params file, there are a couple of - issues: - - The params file is not processed at run - time if you set EXPORTPARAMS=No in - shorewall.conf. For run-time setting of shell - variables, use the init extension - script. - - If the params file 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. - - After having made the above changes to the firewall's export - directory, execute the following commands. - -
- cd <export directory> -/sbin/shorewall load <firewall system> - - - Example (firewall's DNS name is 'gateway'): - - /sbin/shorewall load gateway -
- - The first time that you issue a load - command, Shorewall will use ssh to run - /usr/share/shorewall-lite/shorecap on the - remote firewall to create a capabilities file in the firewall's - administrative direction. See below. - - The load - command compiles a firewall script from the configuration files in - the current working directory (using shorewall compile - -e), copies that file to the remote system via - scp and starts Shorewall Lite on the remote - system via ssh. - - - - If you later need to change the firewall's configuration, - change the appropriate files in the firewall's export directory - then: - - cd <export directory> -/sbin/shorewall reload firewall - - The reload - command compiles a firewall script from the configuration files in - the current working directory (using shorewall compile - -e), copies that file to the remote system via - scp and restarts Shorewall Lite on the remote - system via ssh. - - - - If the kernel/iptables configuration on the firewall later - changes and you need to create a new - capabilities file, do the following on the - firewall system: - - /usr/share/shorewall-lite/shorecap > capabilities -scp capabilities <admin system>:<this system's config dir> - - Or simply use the -c option the next time that you use the - reload command (e.g., shorewall reload - -c gateway). - - -
-
-
The /etc/shorewall/capabilities file and the shorecap program