diff --git a/docs/Anatomy.xml b/docs/Anatomy.xml index a41f60a4a..38ef38ad1 100644 --- a/docs/Anatomy.xml +++ b/docs/Anatomy.xml @@ -37,17 +37,17 @@
Products - Shorewall 4.0 consists of four products. + Shorewall 4.0 consists of four packages. - Shorewall. This product must be + Shorewall. This package must be installed on at least one system in your network. That system must also have Shorewall-shell and/or Shorewall-perl installed. - Shorewall-shell. This product + Shorewall-shell. This package includes the legacy Shorewall configuration compiler written in Bourne Shell. This compiler is very portable but suffers from performance problems and has become hard to maintain. diff --git a/docs/Introduction.xml b/docs/Introduction.xml index 892f959aa..c8d91fd02 100644 --- a/docs/Introduction.xml +++ b/docs/Introduction.xml @@ -35,7 +35,7 @@
Introduction - The information in this document applies only to 3.x releases of + The information in this document applies only to 4.x releases of Shorewall.
@@ -288,10 +288,10 @@ ACCEPT net $FW tcp 22 The QuickStart - guildes provide links to download pre-populated files for use - in common setups and the Shorewall Setup Guide shows - you examples for use with other more complex setups. + guildes point to pre-populated files for use in common setups + and the Shorewall Setup + Guide shows you examples for use with other more complex + setups. @@ -305,6 +305,48 @@ ACCEPT net $FW tcp 22
+
+ Shorewall Packages + + Shorewall 4.0 consists of four packages. + + + + Shorewall. This package must be + installed on at least one system in your network. That system must + also have Shorewall-shell and/or Shorewall-perl installed. + + + + Shorewall-shell. This package + includes the legacy Shorewall configuration compiler written in Bourne + Shell. This compiler is very portable but suffers from performance + problems and has become hard to maintain. + + + + Shorewall-perl. An alternative + to Shorewall-shell written in the Perl language. This compiler is + highly portable to those Unix-like platforms that support Perl + (including Cygwin) and is the compiler of choice for new Shorewall + installations. + + + + Shorewall-lite. Shorewall + allows for central administration of multiple firewalls through use of + Shorewall lite. The full Shorewall product (along with Shorewall-shell + and/or Shorewall-perl) are installed on a central administrative + system where compiled Shorewall scripts are generated. These scripts + are copied to the firewall systems where they run under the control of + Shorewall-lite. + + + + It is suggested that new users install Shorewall and + Shorewall-perl +
+
License @@ -323,4 +365,4 @@ ACCEPT net $FW tcp 22 along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA
- + \ No newline at end of file diff --git a/docs/ScalabilityAndPerformance.xml b/docs/ScalabilityAndPerformance.xml index d77e77df2..7571dca6a 100644 --- a/docs/ScalabilityAndPerformance.xml +++ b/docs/ScalabilityAndPerformance.xml @@ -41,10 +41,13 @@ The performance of the shorewall start and shorewall restart - commands is a frequent topic of questions. This article attempts to - explain the scalability issues involved and to offer some tips for - reducing the time required to compile a Shorewall configuration and to - execute the compiled script. + commands when using Shorewall-shell is a frequent topic of questions. This + article attempts to explain the scalability issues involved and to offer + some tips for reducing the time required to compile a Shorewall + configuration and to execute the compiled script. + + Ultimately, the solution to these performance problems is to migrate + to the use of Shorewall-perl if at all possible.
diff --git a/docs/Shorewall-perl.xml b/docs/Shorewall-perl.xml index 5e3ad9985..667ef974c 100644 --- a/docs/Shorewall-perl.xml +++ b/docs/Shorewall-perl.xml @@ -475,7 +475,7 @@ eth0 eth1:!192.168.4.9 ...
-
+
Shorewall-perl - Prerequisites In addition to Shorewall-3.4.2 or later, you need: diff --git a/docs/Shorewall_Doesnt.xml b/docs/Shorewall_Doesnt.xml index 5915ba20a..c90f72cf5 100644 --- a/docs/Shorewall_Doesnt.xml +++ b/docs/Shorewall_Doesnt.xml @@ -46,7 +46,8 @@ Act as a Personal Firewall that allows internet - access by application. If that's what you are looking for, try TuxGuardian. diff --git a/docs/User_defined_Actions.xml b/docs/User_defined_Actions.xml deleted file mode 100644 index 08cebb5c4..000000000 --- a/docs/User_defined_Actions.xml +++ /dev/null @@ -1,480 +0,0 @@ - - -
- - - - User-defined Actions - - - - Tom - - Eastep - - - - - - - 2003 - - 2004 - - 2005 - - Thomas M. Eastep - - - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, Version - 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. - - - -
- Creating a New Action - - Prior to Shorewall version 1.4.9, rules in - /etc/shorewall/rules were limited to those defined by - Netfilter (ACCEPT, DROP, REJECT, etc.). Beginning with Shorewall version - 1.4.9, users may use sequences of these elementary operations to define - more complex actions. - - To define a new action: - - - - Add a line to - /etc/shorewall/actions that - names your new action. Action names must be valid shell variable names - ((must begin with a letter and be composed of letters, digits and - underscore characters) as well as valid Netfilter chain names. If you - intend to log from the action, the name must have a maximum of 11 - characters. It is recommended that the name you select for a new - action begins with a capital letter; that way, the name won't conflict - with a Shorewall-defined chain name. - - Beginning with Shorewall-2.0.0-Beta1, the name of the action may - be optionally followed by a colon (:) and ACCEPT, DROP - or REJECT. When this is done, the named action will become the - default action for policies of type ACCEPT, DROP - or REJECT respectively. The default action is applied immediately - before the policy is enforced (before any logging is done under that - policy) and is used mainly to suppress logging of uninteresting - traffic which would otherwise clog your logs. The same policy name can - appear in multiple actions; the last such action for each policy name - is the one which Shorewall will use. - - Shorewall includes pre-defined actions for DROP and REJECT -- - see below. - - - - Once you have defined your new action name (ActionName), then - copy /usr/share/shorewall/action.template to - /etc/shorewall/action.ActionName (for example, if - your new action name is Foo then copy - /usr/share/shorewall/action.template to - /etc/shorewall/action.Foo). - - - - Now modify the new file to define the new action. - - - - Columns in the action.template file are as follows: - - - - TARGET - Must be ACCEPT, DROP, REJECT, LOG, CONTINUE, QUEUE or - <action> where - <action> is a previously-defined action - (that is, it must precede the action being defined in this file in - your /etc/shorewall/actions file). These actions - have the same meaning as they do in the - /etc/shorewall/rules file (CONTINUE terminates - processing of the current action and returns to the point where that - action was invoked). The TARGET may optionally be followed by a colon - (:) and a syslog log level (e.g, REJECT:info or - ACCEPT:debugging). This causes the packet to be logged at the - specified level. You may also specify ULOG (must be in upper case) as - a log level.This will log to the ULOG target for routing to a separate - log through use of ulogd (http://www.netfilter.org/projects/ulogd/index.html). - - - - SOURCE - Source hosts to which the rule applies. A - comma-separated list of subnets and/or hosts. Hosts may be specified - by IP or MAC address; mac addresses must begin with ~ - and must use - as a separator. - - Alternatively, clients may be specified by interface name. For - example, eth1 specifies a client that communicates with the firewall - system through eth1. This may be optionally followed by another colon - (:) and an IP/MAC/subnet address as described above - (e.g., eth1:192.168.1.5). - - - - DEST - Location of Server. Same as above with the exception that - MAC addresses are not allowed. - - Unlike in the SOURCE column, you may specify a range of up to - 256 IP addresses using the syntax <first - ip>-<last ip>. - - - - PROTO - Protocol - Must be tcp, - udp, icmp, a number, or - all. - - - - DEST PORT(S) - Destination Ports. A comma-separated list of Port - names (from /etc/services), port numbers or port - ranges; if the protocol is icmp, this column is - interpreted as the destination icmp-type(s). - - A port range is expressed as <low - port>:<high port>. - - This column is ignored if PROTOCOL = all but must be entered if - any of the following fields are supplied. In that case, it is - suggested that this field contain -. - - If your kernel contains multi-port match support, then only a - single Netfilter rule will be generated if in this list and in the - CLIENT PORT(S) list below: - - - - There are 15 or less ports listed. - - - - No port ranges are included. - - - - Otherwise, a separate rule will be generated for each - port. - - - - SOURCE PORT(S) - Port(s) used by the client. If omitted, any - source port is acceptable. Specified as a comma-separated list of port - names, port numbers or port ranges. - - If you don't want to restrict client ports but need to specify - an ADDRESS in the next column, then place "-" in this column. - - If your kernel contains multi-port match support, then only a - single Netfilter rule will be generated if in this list and in the - DEST PORT(S) list above: - - - - There are 15 or less ports listed. - - - - No port ranges are included. - - - - Otherwise, a separate rule will be generated for each - port. - - - - RATE LIMIT - You may rate-limit the rule by placing a value in - this column: - - <rate>/<interval>[:<burst>]where - <rate> is the number of connections per - <interval> (sec or - min) and <burst> is the - largest burst permitted. If no <burst> is - given, a value of 5 is assumed. There may be no whitespace embedded in - the specification. - - Example: 10/sec:20 - - - - USER/GROUP - For output rules (those with the firewall as their - source), you may control connections based on the effective UID and/or - GID of the process requesting the connection. This column can contain - any of the following: - - - [!]<user number>[:] - - [!]<user name>[:] - - [!]:<group number> - - [!]:<group name> - - [!]<user - number>:<group - number> - - [!]<user - name>:<group - number> - - [!]<user - inumber>:<group - name> - - [!]<user - name>:<group name> - - - - - Omitted column entries should be entered using a dash ("-:). - - Example: - - /etc/shorewall/actions: - - LogAndAccept/etc/shorewall/action.LogAndAccept LOG:info - ACCEPT - - To use your action, in /etc/shorewall/rules you - might do something like: - - #ACTION SOURCE DEST PROTO DEST PORT(S) -LogAndAccept loc $FW tcp 22 - - Prior to Shorewall 2.1.2, specifying a log level (and optionally a - log tag) on a rule that specified a user-defined (or Shorewall-defined) - action would log all traffic passed to the action. Beginning with - Shorewall 2.1.2, specifying a log level in a rule that specifies a user- - or Shorewall-defined action will cause each rule in the action to be - logged with the specified level (and tag). - - The extent to which logging of action rules occur is governed by the - following: - - - - When you invoke an action and specify a log level, only those - rules in the action that have no log level will be changed to log at - the level specified at the action invocation. - - Example: - - /etc/shorewall/action.foo - - #TARGET SOURCE DEST PROTO DEST PORT(S) -ACCEPT - - tcp 22 -bar:info - - /etc/shorewall/rules: - - #ACTION SOURCE DEST PROTO DEST PORT(S) -foo:debug $FW net - - Logging in the invoke 'foo' action will be as if foo had been - defined as: - - #TARGET SOURCE DEST PROTO DEST PORT(S) -ACCEPT:debug - - tcp 22 -bar:info - - - - If you follow the log level with "!" then logging will be at - that level for all rules recursively invoked by the action. - - Example: - - /etc/shorewall/action.foo - - #TARGET SOURCE DEST PROTO DEST PORT(S) -ACCEPT - - tcp 22 -bar:info - - /etc/shorewall/rules: - - #ACTION SOURCE DEST PROTO DEST PORT(S) -foo:debug! $FW net - - Logging in the invoke 'foo' action will be as if foo had been - defined as: - - #TARGET SOURCE DEST PROTO DEST PORT(S) -ACCEPT:debug - - tcp 22 -bar:debug - - - - The change in Shorewall 2.1.2 has an effect on extension scripts - used with user-defined actions. If you define an action 'acton' and you - have an /etc/shorewall/acton script then when that - script is invoked, the following three variables will be set for use by - the script: - - - - $CHAIN = the name of the chain where your rules are to be - placed. When logging is used on an action invocation, Shorewall - creates a chain with a slightly different name from the action - itself. - - - - $LEVEL = Log level. If empty, no logging was specified. - - - - $TAG = Log Tag. - - - - Example: - - /etc/shorewall/rules: - - #ACTION SOURCE DEST -acton:info:test $FW net - - Your /etc/shorewall/acton file will be run with: - - - - $CHAIN="%acton1" - - - - $LEVEL="info" - - - - $TAG="test" - - -
- -
- Standard Actions In Shorewall 2.0 - - Beginning with Shorewall 2.0.0-Beta1, Shorewall includes a number of - pre-defined actions. These defined actions are listed in - /usr/share/shorewall/actions.std. - - - Example of Using a Standard Action - - Suppose that you wish to enable ftp from your local network to - your firewall. In /etc/shorewall/rules: - - #ACTION SOURCE DEST PROTO ... -AllowFTP loc $FW - - - /usr/share/shorewall/actions.std is processed - before /etc/shorewall/actions and if you have any - actions defined with the same name as one in - /usr/share/shorewall/actions.std, your version in - /etc/shorewall will be the one - used. So if you wish to modify a standard action, simply copy the - associated action file from /usr/share/shorewall to /etc/shorewall and modify it to suit your - needs. The next shorewall restart will cause your - action to be installed in place of the standard one. In particular, if you - want to modify the default actions Drop or - Reject, simply copy action.Drop or - Action.Reject to /etc/shorewall and modify that copy as - desired. - - - Some of the standard actions are built-ins. - This means that there is no corresponding action.* file and that - Shorewall constructs the rules for the actions using direct - iptables commands. If you need to modify one of these - built-in actions, you will need to use the Extension Script mechanism described below - and you will need to give the action a different name. - -
- -
- Default Actions (Formerly Common Actions) - - Also beginning with Shorewall version 2.2.0-Beta1, when an ACCEPT, - DROP or REJECT policy is about to be enforced, a default - action can first be invoked. In /etc/shorewall/actions.std are - found these two entries: - - Drop:DROP #Default Action for DROP policy -Reject:REJECT #Default Action for REJECT policy - - These entries designate the action named Drop - as the default action for DROP policies and the default action - Reject as the default action for REJECT - policies. - - The purpose of default actions is: - - - - To avoid filling your log with useless clutter. For example, one - of the things that the Drop action does is to silently drop SMB - traffic by invoking the DropSMB action. - - - - To ensure proper behavior. For example, both the Drop and Reject - actions invoke the RejectAuth action to REJECT - connection requests on TCP port 113. If these requests are simply - dropped, connection timeouts can occur when you connect to a server - that uses AUTH identification. - - - - It should be stressed that the default actions - do not cause any traffic to be dropped or rejected that isn't about to be - dropped or rejected anyway (remember that these actions are - invoked just before the connection request is going to be dropped or - rejected by policy anyway). Their main function is to avoid log - clutter. -
- -
- Creating an Action using an Extension Script - - There may be cases where you wish to create a chain with rules that - can't be constructed using the tools defined in the action.template. In - that case, you can use an extension script. - If you actually need an action to drop broadcast packets, use - the dropBcast standard action rather than create - one like this. - - - - An action to drop all broadcast packets - - /etc/shorewall/actionsDropBcasts - - /etc/shorewall/action.DropBcasts# This file is empty - - /etc/shorewall/DropBcastsrun_iptables -A DropBcasts -m pkttype --pkttype broadcast -j DROP - -
-
\ No newline at end of file diff --git a/docs/shorewall_prerequisites.xml b/docs/shorewall_prerequisites.xml index 2cdd69f54..e02952bc1 100644 --- a/docs/shorewall_prerequisites.xml +++ b/docs/shorewall_prerequisites.xml @@ -92,4 +92,15 @@
+ +
+ Shorewall-perl Requirements + + Shorewall-perl is a + re-implementation of the Shorewall configuration compiler written in Perl. + It is much faster than the classic Shorewall-shell compiler and produces a + firewall script that runs much faster. It's prerequisites are described in + the Shorewall-perl + article. +
\ No newline at end of file diff --git a/docs/upgrade_issues.xml b/docs/upgrade_issues.xml index b2e27a115..ff0e88968 100644 --- a/docs/upgrade_issues.xml +++ b/docs/upgrade_issues.xml @@ -69,6 +69,65 @@ command to see the groups associated with each of your zones.
+
+ Versions >= 4.0.0-Beta1 + + + + This is the first Shorewall release that fully integrates the + new Shorewall-perl compiler. You are now offered a choice as to which + compiler(s) you install. In Shorewall 4.0.0, there are the following + packages: + + Shorewall ( common files ) + + + + Shorewall-shell ( the shell-based compiler ) + + + + Shorewall-perl (the Perl-based compiler ) + + + + Shorewall-lite + + You must install Shorewall and at least one of the + compiler packages (you may install them both). + + You cannot simply upgrade your existing Shorewall package. You + must upgrade Shorewall and install + one or both of the compilers. + + If you attempt to upgrade using the RPM, you get this + result:gateway:~ # rpm -Uvh shorewall-4.0.0.noarch.rpm +error: Failed dependencies: +shorewall_compiler is needed by shorewall-4.0.0-1.noarch +gateway:~ # You must either:rpm -U shorewall-4.0.0.noarch.rpm shorewall-shell-4.0.0.noarch.rpmorrpm -U shorewall-4.0.0.noarch.rpm shorewall-perl-4.0.0.noarch.rpmorrpm -i shorewall-shell-4.0.0.noarch.rpm +rpm -U shorewall-4.0.0.noarch.rpmorrpm -i shorewall-perl-4.0.0.noarch.rpm +rpm -U shorewall-4.0.0.noarch.rpmIf you are upgrading using + the tarball, you must install either shorewall-shell or shorewall-perl + before you upgrade Shorewall. Otherwise, the install.sh script fails + with: + ERROR: No Shorewall compiler is installed + The shorewall-shell and shorewall-perl packages are + installed from the tarball in the expected way; untar the package, and + run the install.sh script. + + + + The ROUTE_FILTER and LOG_MARTIANS options in shorewall.conf work + slightly differently in Shorewall 4.0.0. In prior releases, leaving + these options empty was equivalent to setting them to 'No' which + caused the corresponding flag in /proc to be reset for all interfaces. + Beginning in Shorewall 4.0.0, leaving these options empty causes + Shorewall to leave the flags in /proc as they are. You must set the + option to 'No' in order to obtain the old behavior. + + +
+
Versions >= 3.4.0-Beta1 @@ -266,7 +325,7 @@ all all REJECT:MyReject info - This issue only applies if you run Shorewall Lite. + This issue only applies if you run Shorewall Lite. The /etc/shorewall-lite/shorewall.conf file has been renamed @@ -1327,4 +1386,4 @@ z2 z1 NONE
- + \ No newline at end of file