From 1b5df1870c0ad94f9c47f7dbc0716d204318311a Mon Sep 17 00:00:00 2001 From: teastep Date: Fri, 26 Dec 2003 17:54:10 +0000 Subject: [PATCH] Convert configuration_file_basics.htm to Docbook XML git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@973 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb --- Shorewall-docs/configuration_file_basics.htm | 339 ------------- Shorewall-docs/configuration_file_basics.xml | 485 +++++++++++++++++++ 2 files changed, 485 insertions(+), 339 deletions(-) delete mode 100644 Shorewall-docs/configuration_file_basics.htm create mode 100644 Shorewall-docs/configuration_file_basics.xml diff --git a/Shorewall-docs/configuration_file_basics.htm b/Shorewall-docs/configuration_file_basics.htm deleted file mode 100644 index 0afd22229..000000000 --- a/Shorewall-docs/configuration_file_basics.htm +++ /dev/null @@ -1,339 +0,0 @@ - - - - - - - - Configuration File Basics - - -

Configuration Files
-

-

Warning: If you copy or edit your -configuration files on a system running Microsoft Windows, you must -run them through dos2unix -before you use them with Shorewall.

-

Files

-

Shorewall's configuration files are in the directory /etc/shorewall.

- -

Comments

-

You may place comments in configuration files by making the first -non-whitespace character a pound sign ("#"). You may also place -comments at the end of any line, again by delimiting the comment from -the -rest of the line with a pound sign.

-

Examples:

-
# This is a comment
-
ACCEPT	net	fw	tcp	www	#This is an end-of-line comment
-

Line Continuation

-

You may continue lines in the configuration files using the usual -backslash ("\") followed immediately by a new line character.

-

Example:

-
ACCEPT	net	fw	tcp \
smtp,www,pop3,imap  #Services running on the firewall
-

INCLUDE -Directive

-Beginning with Shorewall version 1.4.2, any file may contain INCLUDE -directives. An INCLUDE directive consists of the word INCLUDE followed -by a file name and causes the contents of the named file to be -logically included into the file containing the INCLUDE. File names -given in an INCLUDE directive are assumed to reside in /etc/shorewall -or in an alternate configuration directory if one has been specified -for the command.
-
-INCLUDE's may be nested to a level of 3 -- further nested INCLUDE -directives are ignored with a warning message.
-
- Examples:
-
   shorewall/params.mgmt:
-
   MGMT_SERVERS=1.1.1.1,2.2.2.2,3.3.3.3
-   TIME_SERVERS=4.4.4.4
-   BACKUP_SERVERS=5.5.5.5
-
-   ----- end params.mgmt -----
-
-
   shorewall/params:
-
-
-
   # Shorewall 1.3 /etc/shorewall/params
-   [..]
-   #######################################
- 
-   INCLUDE params.mgmt   
- 
-   # params unique to this host here
-   #LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT -REMOVE
-
-
-
   ----- end params -----
-
-
   shorewall/rules.mgmt:
-
-
-
   ACCEPT -net:$MGMT_SERVERS          -$FW    tcp    22
-   ACCEPT -$FW          -net:$TIME_SERVERS    udp    123
-   ACCEPT -$FW          -net:$BACKUP_SERVERS  tcp    22
-
-
-
   ----- end rules.mgmt -----
-
-
   shorewall/rules:
-
-
-
   # Shorewall version 1.3 - Rules File
-   [..]
-   #######################################
- 
-   INCLUDE rules.mgmt    
- 
-   # rules unique to this host here
-   #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT -REMOVE
-
-
-
   ----- end rules -----
-
-

Using DNS Names

-

-

WARNING: I personally recommend strongly against -using DNS names in Shorewall configuration files. If you use DNS names -and you are called out of bed at 2:00AM because Shorewall won't start -as a result of DNS problems then don't say that you were not -forewarned.
-

-

    -Tom
-

-

Beginning with Shorewall 1.3.9, Host addresses in -Shorewall configuration files may be specified as either IP addresses -or DNS Names.
-
-DNS names in iptables rules aren't nearly as useful -as they first appear. When a DNS name appears in a rule, the iptables -utility resolves the name to one or more IP addresses and inserts those -addresses into the rule. So changes in the DNS->IP address -relationship that occur after the firewall has started have absolutely -no effect on the firewall's ruleset.

-

If your firewall rules include DNS names then:

- -

Each DNS name much be fully qualified and include a -minumum of two periods (although one may be trailing). This restriction -is imposed by Shorewall to insure backward compatibility with existing -configuration files.
-
-Examples of valid DNS names:
-

- -Examples of invalid DNS names:
- -DNS names may not be used as:
- -These restrictions are not imposed by Shorewall simply for your -inconvenience but are rather limitations of iptables.
-

Complementing an Address or Subnet

-

Where specifying an IP address, a subnet or an interface, you can -precede the item with "!" to specify the complement of the item. For -example, !192.168.1.4 means "any host but 192.168.1.4". There must be -no white space following the "!".

-

Comma-separated Lists

-

Comma-separated lists are allowed in a number of contexts within the -configuration files. A comma separated list:

- -

Port Numbers/Service Names

-

Unless otherwise specified, when giving a port number you can use -either an integer or a service name from /etc/services.

-

Port Ranges

-

If you need to specify a range of ports, the proper syntax is <low -port number>:<high port number>. For example, if -you want to forward the range of tcp ports 4000 through 4100 to local -host 192.168.1.3, the entry in /etc/shorewall/rules is:
-

-
     DNAT	net	loc:192.168.1.3	tcp	4000:4100
-If you omit the low port number, a value of zero is assumed; if you -omit the high port number, a value of 65535 is assumed.
-

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.

-

Using MAC Addresses

-

Media Access Control (MAC) addresses can be used to specify packet -source in several of the configuration files. To use this feature, your -kernel must have MAC Address Match support -(CONFIG_IP_NF_MATCH_MAC) included.

-

MAC addresses are 48 bits wide and each Ethernet Controller has a -unique MAC address.
-
-In GNU/Linux, MAC addresses are usually written as a series of 6 hex -numbers separated by colons. Example:
-
-     [root@gateway root]# ifconfig eth0
-     eth0 Link encap:Ethernet HWaddr 02:00:08:E3:FA:55
-     inet addr:206.124.146.176 -Bcast:206.124.146.255 Mask:255.255.255.0
-     UP BROADCAST RUNNING MULTICAST MTU:1500 -Metric:1
-     RX packets:2398102 errors:0 dropped:0 -overruns:0 frame:0
-     TX packets:3044698 errors:0 dropped:0 -overruns:0 carrier:0
-     collisions:30394 txqueuelen:100
-     RX bytes:419871805 (400.4 Mb) TX -bytes:1659782221 (1582.8 Mb)
-     Interrupt:11 Base address:0x1800
-
-Because Shorewall uses colons as a separator for address fields, -Shorewall requires MAC addresses to be written in another way. In -Shorewall, MAC addresses begin with a tilde ("~") and consist of 6 hex -numbers separated by hyphens. In Shorewall, the MAC address in the -example above would be written "~02-00-08-E3-FA-55".
-

-

Note: It is not necessary to use the special Shorewall -notation in the /etc/shorewall/maclist -file.
-

-

Shorewall Configurations

-

Shorewall allows you to have configuration directories other than -/etc/shorewall. The shorewall -check, start and restart commands allow you to specify an alternate -configuration directory and Shorewall will use the files in the -alternate directory rather than the corresponding files in -/etc/shorewall. The alternate directory need not contain a complete -configuration; those files not in the alternate directory will be read -from /etc/shorewall.

-

This facility permits you to easily create a test or temporary -configuration by:

-
    -
  1. copying the files that need modification from /etc/shorewall to -a separate directory;
    2. -
  2. modify those files in the separate directory; and
    3. -
  3. specifying the separate directory in a shorewall start or -shorewall restart command (e.g., shorewall -c /etc/testconfig -restart )
    4. -
-The try command -allows you to attempt to restart using an alternate configuration and -if an -error occurs to automatically restart the standard configuration.
-

Updated 11/20/2003 - Tom -Eastep -

-

Copyright -© 2001, 2002, 2003 Thomas M. Eastep.
-

-
- - diff --git a/Shorewall-docs/configuration_file_basics.xml b/Shorewall-docs/configuration_file_basics.xml new file mode 100644 index 000000000..d8525fd1f --- /dev/null +++ b/Shorewall-docs/configuration_file_basics.xml @@ -0,0 +1,485 @@ + + +
+ + + + Configuration Files + + + + Tom + + Eastep + + + + 2003-11-20 + + + 2001-2003 + + 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. + + + + + If you copy or edit your configuration files on a system running + Microsoft Windows, you must run them through dos2unix + before you use them with Shorewall. + + +
+ Files + + /etc/shorewall/shorewall.conf - used + to set several firewall parameters./etc/shorewall/params + - use this file to set shell variables that you will expand in other + files./etc/shorewall/zones - partition + the firewall's view of the world into zones./etc/shorewall/policy + - establishes firewall high-level policy./etc/shorewall/interfaces + - describes the interfaces on the firewall system./etc/shorewall/hosts + - allows defining zones in terms of individual hosts and subnetworks./etc/shorewall/masq + - directs the firewall where to use many-to-one (dynamic) Network Address + Translation (a.k.a. Masquerading) and Source Network Address Translation + (SNAT)./etc/shorewall/modules - directs + the firewall to load kernel modules./etc/shorewall/rules + - defines rules that are exceptions to the overall policies established in + /etc/shorewall/policy./etc/shorewall/nat + - defines one-to-one NAT rules./etc/shorewall/proxyarp + - defines use of Proxy ARP./etc/shorewall/routestopped + (Shorewall 1.3.4 and later) - defines hosts accessible when Shorewall is + stopped./etc/shorewall/tcrules - defines + marking of packets for later use by traffic control/shaping or policy + routing./etc/shorewall/tos - defines + rules for setting the TOS field in packet headers./etc/shorewall/tunnels + - defines IPSEC, GRE and IPIP tunnels with end-points on the firewall + system./etc/shorewall/blacklist - lists + blacklisted IP/subnet/MAC addresses./etc/shorewall/init + - commands that you wish to execute at the beginning of a "shorewall + start" or "shorewall restart"./etc/shorewall/start + - commands that you wish to execute at the completion of a "shorewall + start" or "shorewall restart"/etc/shorewall/stop + - commands that you wish to execute at the beginning of a "shorewall + stop"./etc/shorewall/stopped - + commands that you wish to execute at the completion of a "shorewall + stop"./etc/shorewall/ecn - disable + Explicit Congestion Notification (ECN - RFC 3168) to remote hosts or + networks./etc/shorewall/accounting - + define IP traffic accounting rules/etc/shorewall/usersets + and /etc/shorewall/users - define sets of users/groups with similar access + rights/etc/shorewall/actions and + /etc/shorewall/action.template - define your own actions for rules in + /etc/shorewall/rules (shorewall 1.4.9 and later). +
+ +
+ Comments + + You may place comments in configuration files by making the first + non-whitespace character a pound sign ("#"). You may also place + comments at the end of any line, again by delimiting the comment from the + rest of the line with a pound sign. + + + Comments in a Configuration File + + # This is a comment +ACCEPT net fw tcp www #This is an end-of-line comment + +
+ +
+ Line Continuation + + You may continue lines in the configuration files using the usual + backslash ("\") followed immediately by a new line character. + + + Line Continuation + + ACCEPT net fw tcp \ +smtp,www,pop3,imap #Services running on the firewall + +
+ +
+ INCLUDE Directive + + Beginning with Shorewall version 1.4.2, any file may contain INCLUDE + directives. An INCLUDE directive consists of the word INCLUDE followed by + a file name and causes the contents of the named file to be logically + included into the file containing the INCLUDE. File names given in an + INCLUDE directive are assumed to reside in /etc/shorewall or in an + alternate configuration directory if one has been specified for the + command. + + INCLUDE's may be nested to a level of 3 -- further nested + INCLUDE directives are ignored with a warning message. + + + Use of INCLUDE + + shorewall/params.mgmt: + +   MGMT_SERVERS=1.1.1.1,2.2.2.2,3.3.3.3 +    TIME_SERVERS=4.4.4.4 +    BACKUP_SERVERS=5.5.5.5 + +   ----- end params.mgmt ----- + +   shorewall/params: + +   # Shorewall 1.3 /etc/shorewall/params +    [..] +    ####################################### +   +    INCLUDE params.mgmt    +   +    # params unique to this host here +    #LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE + +   ----- end params ----- + +   shorewall/rules.mgmt: + +   ACCEPT net:$MGMT_SERVERS   $FW    tcp    22 +    ACCEPT $FW          net:$TIME_SERVERS    udp    123 +    ACCEPT $FW          net:$BACKUP_SERVERS  tcp    22 + +   ----- end rules.mgmt ----- + +   shorewall/rules: + +   # Shorewall version 1.3 - Rules File +    [..] +    ####################################### +   +    INCLUDE rules.mgmt     +   +    # rules unique to this host here +    #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE + +   ----- end rules ----- + +
+ +
+ Using DNS Names + + + I personally recommend strongly against using DNS names in + Shorewall configuration files. If you use DNS names and you are called + out of bed at 2:00AM because Shorewall won't start as a result of + DNS problems then don't say that you were not forewarned. + + + Beginning with Shorewall 1.3.9, Host addresses in Shorewall + configuration files may be specified as either IP addresses or DNS Names. + + DNS names in iptables rules aren't nearly as useful as they + first appear. When a DNS name appears in a rule, the iptables utility + resolves the name to one or more IP addresses and inserts those addresses + into the rule. So changes in the DNS->IP address relationship that + occur after the firewall has started have absolutely no effect on the + firewall's ruleset. + + If your firewall rules include DNS names then: + + + + If your /etc/resolv.conf is wrong then your firewall won't + start. + + + + If your /etc/nsswitch.conf is wrong then your firewall won't + start. + + + + If your Name Server(s) is(are) down then your firewall won't + start. + + + + If your startup scripts try to start your firewall before + starting your DNS server then your firewall won't start. + + + + Factors totally outside your control (your ISP's router is + down for example), can prevent your firewall from starting. + + + + You must bring up your network interfaces prior to starting your + firewall. + + + + Each DNS name much be fully qualified and include a minumum of two + periods (although one may be trailing). This restriction is imposed by + Shorewall to insure backward compatibility with existing configuration + files. + + + Valid DNS Names + + + + mail.shorewall.net + + + + shorewall.net. (note the trailing period). + + + + + + Invalid DNS Names + + + + mail (not fully qualified) + + + + shorewall.net (only one period) + + + + + DNS names may not be used as: + + + + The server address in a DNAT rule (/etc/shorewall/rules file) + + + + In the ADDRESS column of an entry in /etc/shorewall/masq. + + + + In the /etc/shorewall/nat file. + + + + These restrictions are imposed by Netfilter and not by Shorewall. +
+ +
+ Complementing an Address or Subnet + + Where specifying an IP address, a subnet or an interface, you can + precede the item with "!" to specify the complement of the item. + For example, !192.168.1.4 means "any host but 192.168.1.4". There + must be no white space following the "!". +
+ +
+ Comma-separated Lists + + Comma-separated lists are allowed in a number of contexts within the + configuration files. A comma separated list: + + + + Must not have any embedded white space. Valid: routefilter,dhcp,norfc1918 + Invalid: routefilter,     dhcp,     norfc1818 + + + + If you use line continuation to break a comma-separated list, + the continuation line(s) must begin in column 1 (or there would be + embedded white space) + + + + Entries in a comma-separated list may appear in any order. + + +
+ +
+ Port Numbers/Service Names + + Unless otherwise specified, when giving a port number you can use + either an integer or a service name from /etc/services. +
+ +
+ Port Ranges + + If you need to specify a range of ports, the proper syntax is + <low port number>:<high port number>. For example, if you + want to forward the range of tcp ports 4000 through 4100 to local host + 192.168.1.3, the entry in /etc/shorewall/rules is: + + + + + + ACTION + + SOURCE + + DESTINATION + + PROTOCOL + + PORT(S) + + SOURCE PORT(S) + + ORIGINAL DEST + + + + + + DNAT + + net + + loc:192.168.1.3 tcp + + tcp + + 4000:4100 + + + + + + + + + + If you omit the low port number, a value of zero is assumed; if you + omit the high port number, a value of 65535 is assumed. +
+ +
+ 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 + + + Using Shell Variables + +     /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. + +
+ +
+ Using MAC Addresses + + Media Access Control (MAC) addresses can be used to specify packet + source in several of the configuration files. To use this feature, your + kernel must have MAC Address Match support (CONFIG_IP_NF_MATCH_MAC) + included. + + MAC addresses are 48 bits wide and each Ethernet Controller has a + unique MAC address. + + In GNU/Linux, MAC addresses are usually written as a series of 6 hex + numbers separated by colons. + + + MAC Address of a NIC + +      [root@gateway root]# ifconfig eth0 +      eth0 Link encap:Ethernet HWaddr 02:00:08:E3:FA:55 +      inet addr:206.124.146.176 Bcast:206.124.146.255 Mask:255.255.255.0 +      UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 +      RX packets:2398102 errors:0 dropped:0 overruns:0 frame:0 +      TX packets:3044698 errors:0 dropped:0 overruns:0 carrier:0 +      collisions:30394 txqueuelen:100 +      RX bytes:419871805 (400.4 Mb) TX bytes:1659782221 (1582.8 Mb) +      Interrupt:11 Base address:0x1800 + + + + Because Shorewall uses colons as a separator for address fields, + Shorewall requires MAC addresses to be written in another way. In + Shorewall, MAC addresses begin with a tilde ("~") and consist of 6 + hex numbers separated by hyphens. In Shorewall, the MAC address in the + example above would be written "~02-00-08-E3-FA-55". + + + It is not necessary to use the special Shorewall notation in the + /etc/shorewall/maclist file. + +
+ +
+ Shorewall Configurations + + Shorewall allows you to have configuration directories other than + /etc/shorewall. The shorewall check, start and restart commands allow you + to specify an alternate configuration directory and Shorewall will use the + files in the alternate directory rather than the corresponding files in + /etc/shorewall. The alternate directory need not contain a complete + configuration; those files not in the alternate directory will be read + from /etc/shorewall. + + This facility permits you to easily create a test or temporary + configuration by + + + + copying the files that need modification from /etc/shorewall to + a separate directory; + + + + modify those files in the separate directory; and + + + + specifying the separate directory in a shorewall start or + shorewall restart command (e.g., shorewall -c + /etc/testconfig restart ) + + + + The try command + allows you to attempt to restart using an alternate configuration and if + an error occurs to automatically restart the standard configuration. +
+
\ No newline at end of file