FireHOL + FireQOS Reference

Transcription

1 FireHOL + FireQOS Reference FireHOL Team Release pre7 Built 13 Apr 2014

2 FireHOL + FireQOS Reference Release pre7 i Copyright Phil Whineray <phil@sanewall.org> Copyright 2004, Costa Tsaousis <costa@tsaousis.gr>

3 FireHOL + FireQOS Reference Release pre7 ii Contents 1 Introduction Latest version Who should read this manual Where to get help Manual Organisation Installation Licence I FireHOL 3 2 Configuration Getting started Language Use of bash What to avoid Security Important Security Note What happens when FireHOL Runs? Where to learn more Troubleshooting Reading log output

4 FireHOL + FireQOS Reference Release pre7 iii II FireQOS 11 5 Configuration 12 III FireHOL Reference 13 6 Running and Configuring FireHOL program: firehol FireHOL configuration: firehol.conf control variables: firehol-variables ipv4/ipv6 selection: firehol-modifiers Definition Commands interface definition: firehol-interface router definition: firehol-router Rule Subcommands policy command: firehol-policy protection command: firehol-protection server, route commands: firehol-server client command: firehol-client group command: firehol-group Optional Parameters and Actions optional rule parameters: firehol-rule-params actions for rules: firehol-actions Helper Commands iptables helper: firehol-iptables masquerade helper: firehol-masquerade tcpmss helper: firehol-tcpmss

5 FireHOL + FireQOS Reference Release pre7 iv 11 Configuration Helper Commands version config helper: firehol-version action config helper: firehol-action blacklist config helper: firehol-blacklist classify config helper: firehol-classify connmark config helper: firehol-connmark dscp config helper: firehol-dscp mac config helper: firehol-mac mark config helper: firehol-mark nat, snat, dnat, redirect config helpers: firehol-nat transparent_proxy, transparent_squid helpers: firehol-transparent_proxy tos config helper: firehol-tos tosfix config helper: firehol-tosfix Services Reference services list: firehol-services services list a: firehol-services-a services list b: firehol-services-b services list c: firehol-services-c services list d: firehol-services-d services list e: firehol-services-e services list f: firehol-services-f services list g: firehol-services-g services list h: firehol-services-h services list i: firehol-services-i services list j: firehol-services-j services list k: firehol-services-k services list l: firehol-services-l services list m: firehol-services-m services list n: firehol-services-n

6 FireHOL + FireQOS Reference Release pre7 v 12.16services list o: firehol-services-o services list p: firehol-services-p services list q: firehol-services-q services list r: firehol-services-r services list s: firehol-services-s services list t: firehol-services-t services list u: firehol-services-u services list v: firehol-services-v services list w: firehol-services-w services list x: firehol-services-x services list y: firehol-services-y services list z: firehol-services-z IV FireQOS Reference Running and Configuring FireQOS program: fireqos FireQOS configuration: fireqos.conf Organising Traffic interface definition: fireqos-interface traffic class: fireqos-class traffic match: fireqos-match Optional Parameters class/match parameters: fireqos-shared-params optional class parameters: fireqos-class-params optional match parameters: fireqos-match-params

7 FireHOL + FireQOS Reference Release pre7 vi V Appendices 203 A ICMPv6 Firewall Recommendations 204 A.1 Introduction A.2 Allow outbound echo requests from prefixes which belong to the site A.3 Allow inbound echo requests towards only predetermined hosts A.4 Allow incoming and outgoing echo reply messages only for existing sessions A.5 Deny icmps to/from link local addresses A.6 Drop echo replies which have a multicast address as a destination A.7 Allow incoming destination unreachable messages only for existing sessions A.8 Allow outgoing destination unreachable messages A.9 Allow incoming Packet Too Big messages only for existing sessions A.10 Allow outgoing Packet Too Big messages A.11 Allow incoming time exceeded code 0 messages only for existing sessions A.12 Allow incoming time exceeded code 1 messages A.13 Allow outgoing time exceeded code 0 messages A.14 Allow outgoing time exceeded code 1 messages A.15 Allow incoming parameter problem code 1 and 2 messages for an existing session A.16 Allow outgoing parameter problem code 1 and code 2 messages A.17 Allow incoming and outgoing parameter problem code 0 messages A.18 Drop NS/NA messages both incoming and outgoing A.19 Drop RS/RA messages both incoming and outgoing A.20 Drop Redirect messages both incoming and outgoing A.21 Drop incoming and outgoing Multicast Listener queries (MLDv1 and MLDv2) A.22 Drop incoming and outgoing Multicast Listener reports (MLDv1) A.23 Drop incoming and outgoing Multicast Listener Done messages (MLDv1) A.24 Drop incoming and outgoing Multicast Listener reports (MLDv2) A.25 Drop router renumbering messages A.26 Drop node information queries (139) and replies (140) A.27 If there are mobile ipv6 home agents present on the trusted side allow A.28 If there are roaming mobile nodes present on the trusted side allow A.29 Drop everything else

8 FireHOL + FireQOS Reference Release pre7 vii 16 Index 212

9 FireHOL + FireQOS Reference Release pre7 viii List of Tables 6.1 iptables/klogd levels

10 FireHOL + FireQOS Reference Release pre7 1 / 215 Chapter 1 Introduction 1.1 Latest version The latest version of this document will always be available here. There are PDF and HTML versions. 1.2 Who should read this manual This manual is aimed at those who wish to create and maintain firewalls with FireHOL or perform traffic shaping with FireQOS. For more information and tutorials, see the FireHOL website. 1.3 Where to get help The FireHOL website. The mailing lists and archives. The package comes with a complete set of manpages, a README and a brief INSTALL guide. 1.4 Manual Organisation FireHOL, the package, consists of two principal programs. The manual is split into four parts. For firewalling read about FireHOL in Part I with reference material in Part III For traffic shaping/qos read about FireQOS in Part II with reference material in Part IV.

11 FireHOL + FireQOS Reference Release pre7 2 / Installation You can download tar-file releases by visiting the FireHOL website download area. Unpack and change directory with: tar xfz firehol-version.tar.gz cd firehol-version Options for the configure program can be seen in the INSTALL file and by running:./configure --help To build and install taking the default options:./configure && make && sudo make install Alternatively, just copy the sbin/firehol.in and sbin/fireqos.in files to where you want them. All of the common SysVInit command line arguments are recognised which makes it easy to deploy the scripts as startup services. Packages are available for most distributions and you can use your distribution s standard commands (e.g. aptitude, yum, etc.) to install these. Note Distributions do not always offer the latest version. FireHOL website. You can see what the latest release is on the 1.6 Licence This manual is licensed under the same terms as the FireHOL package, the GNU GPL v2 or later. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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., 59 Temple Place, Suite 330, Boston, MA USA

12 FireHOL + FireQOS Reference Release pre7 3 / 215 Part I FireHOL

13 FireHOL + FireQOS Reference Release pre7 4 / 215 Chapter 2 Configuration 2.1 Getting started Please see the online tutorials for help getting started. 2.2 Language Use of bash FireHOL configuration files are normal BASH scripts. As such, you can use all BASH features within FireHOL configuration files, including functions, loops, variables, I/O, etc. BASH is used as the base configuration language for FireHOL since it is the common denominator for a language that all UNIX system administrators and developers should know and understand. The fact that FireHOL uses BASH for its configuration, allows development of add-ons and enables FireHOL to use programs to access SQL databases, directory structures, DBM or other files, web front ends or other means for the rules of the firewall. Exactly the same reason allows the build of remote managers for centralised administration of a large number of Linux hosts and routers What to avoid The only BASH commands a FireHOL configuration script should never use are trap and exit.

14 FireHOL + FireQOS Reference Release pre7 5 / 215 Traps are used by FireHOL for cleaning up all temporary files, and possibly restoring the previously running firewall in case FireHOL execution breaks, and the exit command will not just exit the configuration file, it will exit FireHOL. FireHOL has disabled these features by default, so that you will not be able to use them, unless you specifically enable them. Since a FireHOL configuration script runs inline with FireHOL, all variables and function names defined within the configuration file overwrite the ones defined by FireHOL so you should avoid some names. Avoid using variables that start with FIREHOL_, work_, server_, and client_ as many such variables are used by FireHOL internally. There are also a number of functions names you should avoid, but there is no generic pattern at the moment. I suggest you should avoid defining functions with the names of FireHOL commands (interface, router, client, server, etc) and functions starting with rules_. Note You may wish to overwrite a few variables and functions if you want to modify FireHOL services. See the section called Adding Services for details.

15 FireHOL + FireQOS Reference Release pre7 6 / 215 Chapter 3 Security This chapter discusses some of the security considerations of firewalls in general and using FireHOL in particular. 3.1 Important Security Note It should be observed that FireHOL can be no more secure than your use of it. You should audit the output results at least once to ensure you are happy with the rules produced. The rules that get output are extremely regular and should make the task fairly straightforward. In particular it is your responsibility to ensure the final firewall produced behaves as you expect. If in doubt we recommend that you seek help from a firewall/networking professional. Please consider signing up to the mailing lists to ensure you are kept informed in the event that a security problem is discovered. 3.2 What happens when FireHOL Runs? FireHOL is a BASH script. To run its configuration file, FireHOL first defines a set of functions and variables and then it "sources" (runs inline) its configuration file to be executed by BASH. The keywords interface, client, server, router, etc. are all BASH functions that are executed by BASH when and if they appear in the configuration file. Using shared variables these functions share some state information that allows them to know, for example, that a client command appears within an interface and not within a router and that the name given to an interface that has not been used before.

16 FireHOL + FireQOS Reference Release pre7 7 / 215 Instead of running iptables commands directly, each of these functions (i.e. FireHOL) just writes the generated iptables commands to a temporary file. This is done to prevent altering a running firewall before ensuring that the syntax of the configuration file is correct. So, a complete run of the configuration file actually produces all the iptables commands for the firewall, written to a temporary file (script). Even the iptables commands given within the configuration file use the same concept (they just generate iptables commands in this script). Finally, this script (the generated iptables commands) has to be run, but before doing so, FireHOL saves the running firewall to another temporary file. The saved firewall will be automatically restored if some of the generated iptables commands produces an error. Such an error is possible when for example, you specify an invalid IP address or hostname, or an invalid argument to some parameter that gets passed to iptables as-is. It is important to understand that during the run of the generated iptables script (including the possible restoration of the old firewall), FireHOL allows all traffic to reach its destination. This has been done to prevent a possible lock-out situation where you are SSHing to the server to alter its firewall, and suddenly you loose the connection (although this can still happen if your new firewall doesn t allow the connection). To control this behaviour, set the ACTIVATION variables (see control variables: firehol-variables(5)). If no error has been seen, FireHOL deletes all temporary files generated and exits. In case there was an error, FireHOL will make the most to restore your previous firewall and will present you details about the error and its line number in the original configuration file. 3.3 Where to learn more The FireHOL website contains more information and there are a number of iptables tutorials online.

17 FireHOL + FireQOS Reference Release pre7 8 / 215 Chapter 4 Troubleshooting The main tool you have for troubleshooting a running firewall is the system log, typically /var/log/ syslog, /var/log/messages or similar. 4.1 Reading log output The system log will log any packets dropped implicitly by FireHOL. This means any packets which do not match any rules in the configuration file. FireHOL always logs packets not matched by any rule, although it does not log every single packet, in order to protect you from an attack that could use all of your free hard disk space. The rate is controlled in the same way as loglimit. In the system log you will find entries that look like: Dec 21 20:01:07 gateway kernel: IN-internet:IN=ppp0 OUT= MAC= \ SRC= DST= LEN=78 TOS=0x00 PREC=0x00 \ TTL=111 ID=63816 PROTO=UDP SPT=34165 DPT=137 LEN=58 Dec 21 22:25:39 gateway kernel: OUT-unknown:IN= OUT=ppp0 \ SRC= DST= LEN=48 TOS=0x00 PREC=0x00 \ TTL=64 ID=0 DF PROTO=TCP SPT=139 DPT=1255 WINDOW=2128 \ RES=0x00 ACK SYN URGP=0 Dec 21 20:01:07 gateway kernel: PASS-unknown:IN=ppp0 OUT=eth0 \ SRC= DST= LEN=78 TOS=0x00 PREC=0x00 \ TTL=110 ID=64840 PROTO=UDP SPT=34132 DPT=137 LEN=58 Each of such lines represent one packet that did not satisfy the requirements of the configuration file rules.

18 FireHOL + FireQOS Reference Release pre7 9 / 215 FireHOL provides a reason text which indicates where a packet was dropped: IN-name IN-name refers to packets that were dropped at the end of the interface definition called name s input (see interface definition: firehol-interface(5)). These packets tried to come into this host (it is not routed traffic). There is also the special name unknown that matches packets which tried to come into this host but did not match any of the interfaces given in FireHOL s configuration file. OUT-name OUT-name refers to packets that were dropped at the end of the interface definition called name s output (see interface definition: firehol-interface(5)). These are packets the host tried to send (it is not routed traffic). There is also the special name unknown that matches packets which tried to come into this host but did not match any of the interfaces given in FireHOL s configuration file. PASS-unknown PASS-unknown refers to packets that that were dropped at the end of all router definitions (see router definition: firehol-router(5)). This matches forwarded traffic. There is no name here, since all FireHOL routers have only one policy RETURN. All packets are processed against all routers and then get dropped at the end of the firewall. Further information about the dropped packet is logged: IN= The real network interface name the packet came in from. It can be empty when the packet was generated locally. OUT= The real network interface name the packet tried to use to go out of this host. It can be empty when the packet was received by the firewall host. SRC= The IP address of the packet s sender. DST= The IP address of the packet s destination. PROTO= The protocol this packet is using (TCP, UDP, ICMP, etc). SPT= The source port number of this packet. DPT= The destination port number of this packet.

19 FireHOL + FireQOS Reference Release pre7 10 / 215 Generally, you should monitor the system log for such entries and decide if each entry was something useful or not. If it was something useful, you should have added another service somewhere in your FireHOL configuration to match that packet and allow it to reach its destination. If it was not something useful, then FireHOL did the right job and dropped it. Keep in mind that there are certain cases where packets get dropped even though FireHOL has specific rules that should allow them to pass. Such cases are not always errors, and here is why: The iptables connection tracker has a mechanism for matching request packets and reply packets. When an allowed request comes in, the connection tracker keeps it in a list and then waits for a matching reply to come in the opposite direction. This list of active connections is available for you to see at /proc/net/ip_conntrack. Simply cat this file to see all the current connections your system has. The connection tracker will wait for a reply a certain amount of time. This time is, for example, about 20 seconds for UDP traffic. After that time the connection tracker will remove the request from its list. A reply that is send after the connection tracker has removed the request from its list, will be dropped and therefore logged in the system log. This situation may, for example, produce a few log entries in your DNS server for cases where the DNS server could not respond within the time limits set by iptables, but this is not a problem because the DNS client had already timed out in 2 or 3 seconds. Note however that the above are common when the connection tracker is trying to keep a state on a stateless protocol (such as UDP or ICMP). Stateful protocols, such as TCP, always respond immediately to acknowledge the connection and therefore the time needed by the application server to respond does not make the connection tracker to remove the request from its list.

20 FireHOL + FireQOS Reference Release pre7 11 / 215 Part II FireQOS

21 FireHOL + FireQOS Reference Release pre7 12 / 215 Chapter 5 Configuration TODO

22 FireHOL + FireQOS Reference Release pre7 13 / 215 Part III FireHOL Reference

23 FireHOL + FireQOS Reference Release pre7 14 / 215 Chapter 6 Running and Configuring

24 FireHOL + FireQOS Reference Release pre7 15 / FireHOL program: firehol Name firehol an easy to use but powerful iptables stateful firewall Synopsis firehol sudo -E firehol panic [IP] firehol command [ -- conf-arg... ] firehol CONFIGFILE [start debug try] [ -- conf-arg... ] Description Running firehol invokes iptables(8) to manipulate your firewall. Run without any arguments, firehol will present some help on usage. When given CONFIGFILE, firehol will use the named file instead of /etc/firehol/firehol. conf as its configuration. If no command is given, firehol assumes try. It is possible to pass arguments for use by the configuration file separating any conf-arg values from the rest of the arguments with --. The arguments are accessible in the configuration using standard bash(1) syntax e.g. $1, $2, etc. Panic To block all communication, invoke firehol with the panic command. FireHOL removes all rules from the running firewall and then DROPs all traffic on all iptables tables (mangle, nat, filter) and pre-defined chains (PREROUTING, INPUT, FORWARD, OUTPUT, POSTROUT- ING). DROPing is not done by changing the default policy to DROP, but by adding one rule per table/chain to drop all traffic. This allows systems which do not reset all the chains to ACCEPT when starting to function correctly. When activating panic mode, FireHOL checks for the existence of the SSH_CLIENT shell environment variable, which is set by ssh. If it finds this, then panic mode will allow the established SSH connection specified in this variable to operate.

25 FireHOL + FireQOS Reference Release pre7 16 / 215 Note In order for FireHOL to see the environment variable you must ensure that it is preserved. For sudo use the -E and for su omit the - (minus sign). If SSH_CLIENT is not set, the IP after the panic argument allows you to give an IP address for which all established connections between the IP address and the host in panic will be allowed to continue. Commands start, restart Activates the firewall configuration from /etc/firehol/firehol.conf. try stop Use of the term restart is allowed for compatibility with common init implementations. Activates the firewall, waiting for the user to type the word commit. If this word is not typed within 30 seconds, the previous firewall is restored. Stops a running iptables firewall by clearing all of the tables and chains and setting the default policies to ACCEPT. This will allow all traffic to pass unchecked. condrestart Restarts the FireHOL firewall only if it is already active. This is the generally expected behaviour (but opposite to FireHOL prior to pre4). status Shows the running firewall, using /sbin/iptables -nxvl less. save Start the firewall and then save it using /sbin/iptables-save to /etc/sysconfig/iptables. The required kernel modules are saved to an executable shell script /var/spool/firehol/ last_save_modules.sh, which can be called during boot if a firewall is to be restored. Note External changes may cause a firewall restored after a reboot to not work as intended where starting the firewall with FireHOL will work. This is because as part of starting a firewall, FireHOL checks some changeable values. For instance the current kernel configuration is checked (for client port ranges), and RPC servers are queried (to allow correct functioning of the NFS service). debug Parses the configuration file but instead of activating it, FireHOL shows the generated iptables statements.

26 FireHOL + FireQOS Reference Release pre7 17 / 215 explain Enters an interactive mode where FireHOL accepts normal configuration commands and presents the generated iptables commands for each of them, together with some reasoning for its purpose. Additionally, FireHOL automatically generates a configuration script based on the successful commands given. Some extra commands are available in explain mode. SPECIAL COMMANDS IN EXPLAIN MODE help Present some help show Present the generated configuration quit Exit interactive mode and quit helpme, wizard Tries to guess the FireHOL configuration needed for the current machine. FireHOL will not stop or alter the running firewall. The configuration file is given in the standard output of firehol, thus firehol helpme > /tmp/firehol.conf will produce the output in /tmp/firehol.conf. The generated FireHOL configuration must be edited before use on your systems. You are required to take a number of decisions; the comments in the generated file will instruct you in the choices you must make. Files /etc/firehol/firehol.conf See Also FireHOL configuration: firehol.conf(5) control variables: firehol-variables(5) FireHOL Manual: firehol-manual.pdf FireHOL Online Documentation

27 FireHOL + FireQOS Reference Release pre7 18 / FireHOL configuration: firehol.conf Name firehol.conf FireHOL configuration file Description /etc/firehol/firehol.conf is the default configuration file for FireHOL program: firehol(1). It defines the stateful firewall that will be produced. A configuration file starts with an optional version indicator which looks like this: version 5 See version config helper: firehol-version(5) for full details. A configuration file contains one or more interface definitions, which look like this: interface eth0 lan client all accept # This host can access any remote service server ssh accept # Remote hosts can access SSH on local server #... The above definition has name "lan" and specifies a network interface (eth0). A definition may contain zero or more subcommands. See interface definition: firehol-interface(5) for full details. By default FireHOL will try to create both IPv4 and IPv6 rules for each interface. To make this explicit or restrict which rules are created write both interface, ipv4 interface or ipv6 interface. A configuration file contains zero or more router definitions, which look like this: DMZ_IF=eth0 WAN_IF=eth1 router wan2dmz inface ${WAN_IF} outface ${DMZ_IF} route http accept # Hosts on WAN may access HTTP on hosts in DMZ server ssh accept # Hosts on WAN may access SSH on hosts in DMZ client pop3 accept # Hosts in DMZ may access POP3 on hosts on WAN #... The above definition has name "wan2dmz" and specifies incoming and outgoing network interfaces (eth1 and eth0) using variables. A definition may contain zero or more subcommands. Note that a router is not required to specify network interfaces to operate on. See router definition: firehol-router(5) for full details. By default FireHOL will try to create both IPv4 and IPv6 rules for each router. To make this explicit or restrict which rules are created write both router, ipv4 router or ipv6 router.

28 FireHOL + FireQOS Reference Release pre7 19 / 215 It is simple to add extra service definitions which can then be used in the same way as those provided as standard. See the section called Adding Services. The configuration file is parsed as a bash(1) script, allowing you to set up and use variables, flow control and external commands. Special control variables: firehol-variables(5) may be set up and used outside of any definition as can the functions in the section called Configuration Helper Commands and the section called Helper Commands. Variables Available The following variables are made available in the FireHOL configuration file and can be accessed as ${VARIABLE}. UNROUTABLE_IPS This variable includes the IPs from both PRIVATE_IPS and RESERVED_IPS. It is useful to restrict traffic on interfaces and routers accepting Internet traffic, for example: interface eth0 internet src not "${UNROUTABLE_IPS}" PRIVATE_IPS This variable includes all the IP addresses defined as Private or Test by RFC You can override the default values by creating a file called /etc/firehol/private_ips. RESERVED_IPS This variable includes all the IP addresses defined by IANA as reserved. You can override the default values by creating a file called /etc/firehol/reserved_ips. Now that IPv4 address space has all been allocated there is very little reason that this value will need to change in future. MULTICAST_IPS This variable includes all the IP addresses defined as Multicast by RFC You can override the default values by creating a file called /etc/firehol/multicast_ips. Adding Services To define new services you add the appropriate lines before using them later in the configuration file. The following are required: server_myservice_ports="proto/sports" client_myservice_ports="cports"

29 FireHOL + FireQOS Reference Release pre7 20 / 215 proto is anything iptables(8) accepts e.g. "tcp", "udp", "icmp", including numeric protocol values. sports is the ports the server is listening at. It is a space-separated list of port numbers, names and ranges (from:to). The keyword any will match any server port. cports is the ports the client may use to initiate a connection. It is a space-separated list of port numbers, names and ranges (from:to). The keyword any will match any client port. The keyword default will match default client ports. For the local machine (e.g. a client within an interface) it resolves to sysctl variable net.ipv4.ip_local_port_range (or /proc/sys/net/ipv4/ip_local_port_ range). For a remote machine (e.g. a client within an interface or anything in a router) it resolves to the variable DEFAULT_CLIENT_PORTS (see control variables: firehol-variables(5)). The following are optional: require_myservice_modules="modules" require_myservice_nat_modules="nat-modules" The named kernel modules will be loaded when the definition is used. The NAT modules will only be loaded if FIREHOL_NAT is non-zero (see control variables: firehol-variables(5)). For example, for a service named daftnet that listens at two ports, port 1234 TCP and 1234 UDP where the expected client ports are the default random ports a system may choose, plus the same port numbers the server listens at, with further dynamic ports requiring kernel modules to be loaded: version 5 server_daftnet_ports="tcp/1234 udp/1234" client_daftnet_ports="default 1234" require_daftnet_modules="ip_conntrack_daftnet" require_daftnet_nat_modules="ip_nat_daftnet" interface eth0 lan0 server daftnet accept interface eth1 lan1 client daftnet reject router lan2lan inface eth0 outface eth1 route daftnet accept Where multiple ports are provides (as per the example), FireHOL simply determines all of the combinations of client and server ports and generates multiple iptables statements to match them. To create more complex rules, or stateless rules, you will need to create a bash function prefixed rules_ e.g. rules_myservice. The best reference is the many such functions in the main firehol executable. When adding a service which uses modules, or via a custom function, you may also wish to include the following:

30 FireHOL + FireQOS Reference Release pre7 21 / 215 ALL_SHOULD_ALSO_RUN="${ALL_SHOULD_ALSO_RUN} myservice" which will ensure your service is set-up correctly as part of the all service. Note To allow definitions to be shared you can instead create files and install them in the /etc/firehol/ services directory with a.conf extension. The first line must read: FHVER 1:213 1 is the service definition API version. It will be changed if the API is ever modified. The 213 originally referred to a FireHOL 1.x minor version but is no longer checked. FireHOL will refuse to run if the API version does not match the expected one. Definitions interface definition: firehol-interface(5) router definition: firehol-router(5) Subcommands policy command: firehol-policy(5) protection command: firehol-protection(5) server, route commands: firehol-server(5) client command: firehol-client(5) group command: firehol-group(5) Helper Commands These helpers can be used in interface and router definitions as well as before them. iptables helper: firehol-iptables(5) masquerade helper: firehol-masquerade(5) This helper can be used in router definitions as well as before any router or interface. tcpmss helper: firehol-tcpmss(5)

31 FireHOL + FireQOS Reference Release pre7 22 / 215 Configuration Helper Commands These helpers should only be used outside of interface and router definitions (i.e. before the first interface is defined). version config helper: firehol-version(5) action config helper: firehol-action(5) blacklist config helper: firehol-blacklist(5) classify config helper: firehol-classify(5) connmark config helper: firehol-connmark(5) dscp config helper: firehol-dscp(5) mac config helper: firehol-mac(5) mark config helper: firehol-mark(5) nat, snat, dnat, redirect config helpers: firehol-nat(5) transparent_proxy, transparent_squid helpers: firehol-transparent_proxy(5) tos config helper: firehol-tos(5) tosfix config helper: firehol-tosfix(5) See Also FireHOL program: firehol(1) control variables: firehol-variables(5) services list: firehol-services(5) actions for rules: firehol-actions(5) FireHOL Manual: firehol-manual.pdf FireHOL Online Documentation

32 FireHOL + FireQOS Reference Release pre7 23 / control variables: firehol-variables Name firehol-variables Variables controlling FireHOL Description There are a number of variables that control the behaviour of FireHOL. All variables may be set in the main FireHOL configuration file /etc/firehol/firehol.conf. Variables which affect the runtime but not the created firewall may also be set as environment variables before running firehol. These can change the default values but will be overwritten by values set in the configuration file. If a variable can be set by an environment variable it is specified below. FireHOL also sets some variables before processing the configuration file which you can use as part of your configuration. These are described in FireHOL configuration: firehol.conf(5). Variables DEFAULT_INTERFACE_POLICY This variable controls the default action to be taken on traffic not matched by any rule within an interface. It can be overridden using policy command: firehol-policy(5). Packets that reach the end of an interface without an action of return or accept are logged. You can control the frequency of this logging by altering FIREHOL_LOG_FREQUENCY. Default: DEFAULT_INTERFACE_POLICY="DROP" : DEFAULT_INTERFACE_POLICY="REJECT" DEFAULT_ROUTER_POLICY This variable controls the default action to be taken on traffic not matched by any rule within a router. It can be overridden using policy command: firehol-policy(5). Packets that reach the end of a router without an action of return or accept are logged. You can control the frequency of this logging by altering FIREHOL_LOG_FREQUENCY. Default: DEFAULT_ROUTER_POLICY="RETURN"

33 FireHOL + FireQOS Reference Release pre7 24 / 215 : DEFAULT_ROUTER_POLICY="REJECT" UNMATCHED_INPUT_POLICY, UNMATCHED_OUTPUT_POLICY, UNMATCHED_FORWARD_POLICY These variables control the default action to be taken on traffic not matched by any interface or router definition that was incoming, outgoing or for forwarding respectively. Any supported value from actions for rules: firehol-actions(5) may be set. All packets that reach the end of a chain are logged, regardless of these settings. You can control the frequency of this logging by altering FIREHOL_LOG_FREQUENCY. Defaults: UNMATCHED_INPUT_POLICY="DROP" UNMATCHED_OUTPUT_POLICY="DROP" UNMATCHED_FORWARD_POLICY="DROP" : UNMATCHED_INPUT_POLICY="REJECT" UNMATCHED_OUTPUT_POLICY="REJECT" UNMATCHED_FORWARD_POLICY="REJECT" FIREHOL_INPUT_ACTIVATION_POLICY, FIREHOL_OUTPUT_ACTIVATION_POLICY, FIREH OL_FORWARD_ACTIVATION_POLICY These variables control the default action to be taken on traffic during firewall activation for incoming, outgoing and forwarding respectively. Acceptable values are ACCEPT, DROP and REJECT. They may be set as environment variables. FireHOL defaults all values to ACCEPT so that your communications continue to work uninterrupted. If you wish to prevent connections whilst the new firewall is activating, set these values to DROP. This is important to do if you are using all or any to match traffic; connections established during activation will continue even if they would not be allowed once the firewall is established. Defaults: UNMATCHED_INPUT_POLICY="ACCEPT" UNMATCHED_OUTPUT_POLICY="ACCEPT" UNMATCHED_FORWARD_POLICY="ACCEPT" : FIREHOL_INPUT_ACTIVATION_POLICY="DROP" FIREHOL_OUTPUT_ACTIVATION_POLICY="DROP" FIREHOL_FORWARD_ACTIVATION_POLICY="DROP"

34 FireHOL + FireQOS Reference Release pre7 25 / 215 FIREHOL_LOG_MODE This variable controls method that FireHOL uses for logging. Acceptable values are LOG (normal syslog) and ULOG (netfilter ulogd). When ULOG is selected, FIREHOL_LOG_LEVEL is ignored. Default: FIREHOL_LOG_MODE="LOG" : FIREHOL_LOG_MODE="ULOG" To see the available options run: /sbin/iptables -j LOG --help or /sbin/iptables -j ULOG --help FIREHOL_LOG_LEVEL This variable controls the level at which events will be logged to syslog. To avoid packet logs appearing on your console you should ensure klogd only logs traffic that is more important than that produced by FireHOL. Use the following option to choose an iptables log level (alpha or numeric) which is higher than the -c of klogd. iptables klogd description emerg (0) 0 system is unusable alert (1) 1 action must be taken immediately crit (2) 2 critical conditions error (3) 3 error conditions warning (4) 4 warning conditions notice (5) 5 normal but significant condition info (6) 6 informational debug (7) 7 debug-level messages Table 6.1: iptables/klogd levels Note The default for klogd is generally to log everything (7 and lower) and the default level for iptables is to log as warnings (4). FIREHOL_LOG_OPTIONS This variable controls the way in which events will be logged to syslog. Default:

35 FireHOL + FireQOS Reference Release pre7 26 / 215 FIREHOL_LOG_OPTIONS="--log-level warning" : FIREHOL_LOG_OPTIONS="--log-level info \ --log-tcp-options --log-ip-options" To see the available options run: /sbin/iptables -j LOG --help FIREHOL_LOG_FREQUENCY, FIREHOL_LOG_BURST These variables control the frequency that each logging rule will write events to syslog. FIRE HOL_LOG_FREQUENCY is set to the maximum average frequency and FIREHOL_LOG_BURST specifies the maximum initial number. Default: FIREHOL_LOG_FREQUENCY="1/second" FIREHOL_LOG_BURST="5" : FIREHOL_LOG_FREQUENCY="30/minute" FIREHOL_LOG_BURST="2" To see the available options run: /sbin/iptables -m limit --help FIREHOL_LOG_PREFIX This value is added to the contents of each logged line for easy detection of FireHOL lines in the system logs. By default it is empty. Default: FIREHOL_LOG_PREFIX="" : FIREHOL_LOG_PREFIX="FIREHOL:" FIREHOL_DROP_INVALID If set to 1, this variable causes FireHOL to drop all packets matched as INVALID in the iptables(8) connection tracker. Note You can use protection command: firehol-protection(5) to control matching of INVALID packets and others on per-interface and per-router basis.

36 FireHOL + FireQOS Reference Release pre7 27 / 215 Default: FIREHOL_DROP_INVALID="0" : FIREHOL_DROP_INVALID="1" DEFAULT_CLIENT_PORTS This variable controls the port range that is used when a remote client is specified. For clients on the local host, FireHOL finds the exact client ports by querying the kernel options. Default: DEFAULT_CLIENT_PORTS="1000:65535" : DEFAULT_CLIENT_PORTS="0:65535" FIREHOL_NAT If set to 1, this variable causes FireHOL to load the NAT kernel modules. If you make use of the NAT helper commands, the variable will be set to 1 automatically. It may be set as an environment variable. Default: FIREHOL_NAT="0" : FIREHOL_NAT="1" FIREHOL_ROUTING If set to 1, this variable causes FireHOL to enable routing in the kernel. If you make use of router definitions or certain helper commands the variable will be set to 1 automatically. It may be set as an environment variable. Default: FIREHOL_ROUTING="0" : FIREHOL_ROUTING="1"

37 FireHOL + FireQOS Reference Release pre7 28 / 215 FIREHOL_AUTOSAVE This variable specifies the file of (IPv4) rules that will be created when FireHOL program: firehol(1) is called with the save argument. It may be set as an environment variable. If the variable is not set, a system-specific value is used which was defined at configure-time. If no value was chosen then the save fails. Default: FIREHOL_AUTOSAVE="" : FIREHOL_AUTOSAVE="/tmp/firehol-saved-ipv4.txt" FIREHOL_LOAD_KERNEL_MODULES If set to 0, this variable forces FireHOL to not load any kernel modules. It is needed only if the kernel has modules statically included and in the rare event that FireHOL cannot access the kernel configuration. It may be set as an environment variable. Default: FIREHOL_LOAD_KERNEL_MODULES="1" : FIREHOL_LOAD_KERNEL_MODULES="0" FIREHOL_TRUST_LOOPBACK If set to 0, the loopback device "lo" will not be trusted and you can write standard firewall rules for it. Warning If you do not set up appropriate rules, local processes will not be able to communicate with each other which can result in serious breakages. By default "lo" is trusted and all INPUT and OUTPUT traffic is accepted (forwarding is not included). Default: FIREHOL_TRUST_LOOPBACK="1" : FIREHOL_TRUST_LOOPBACK="0"

38 FireHOL + FireQOS Reference Release pre7 29 / 215 FIREHOL_DROP_ORPHAN_TCP_ACK_FIN If set to 1, FireHOL will drop all TCP connections with ACK FIN set without logging them. In busy environments the iptables connection tracker removes connection tracking list entries as soon as it receives a FIN. This makes the ACK FIN appear as an invalid packet which will normally be logged by FireHOL. Default: FIREHOL_DROP_ORPHAN_TCP_ACK_FIN="0" : FIREHOL_DROP_ORPHAN_TCP_ACK_FIN="1" FIREHOL_DEBUGGING If set to a non-empty value, switches on debug output so that it is possible to see what processing FireHOL is doing. Note This variable can only be set as an environment variable, since it is processed before any configuration files are read. Default: FIREHOL_DEBUGGING="" : FIREHOL_DEBUGGING="Y" WAIT_FOR_IFACE If set to the name of a network device (e.g. eth0), FireHOL will wait until the device is up (or until 60 seconds have elapsed) before continuing. Note This variable can only be set as an environment variable, since it determines when the main configuration file will be processed. A device does not need to be up in order to have firewall rules created for it, so this option should only be used if you have a specific need to wait (e.g. the network must be queried to determine the hosts or ports which will be firewalled). Default:

39 FireHOL + FireQOS Reference Release pre7 30 / 215 WAIT_FOR_IFACE="" : WAIT_FOR_IFACE="eth0" See also FireHOL program: firehol(1) FireHOL configuration: firehol.conf(5) nat, snat, dnat, redirect config helpers: firehol-nat(5) administration tool for IPv4 firewalls: iptables(8)

40 FireHOL + FireQOS Reference Release pre7 31 / ipv4/ipv6 selection: firehol-modifiers Name firehol-ipv4, firehol-ipv6 select IPv4 or IPv6 mode Synopsis ipv4 definition-or-command ipv6 definition-or-command Description Without a modifier, interface and router definitions and commands that come before either will be applied to both IPv4 and IPV6. Commands within an interface or router assume the same behaviour as the enclosing definition. When preceded by a modifier, the command or definition can be made to apply to IPv4 or IPv6 only. Note that you cannot create an IPv4 only command within and IPv6 interface or vice-versa. s: interface eth0 ifboth src /24 src6 2001:DB8::/24 ipv4 server http accept ipv6 server http accept ipv4 interface eth0 if4only src /24 server http accept ipv6 interface eth0 if6only src 2001:DB8::/24 server http accept Many definitions and commands have explicitly named variants (such as router4, router6, router46) which can be used as shorthand.

41 FireHOL + FireQOS Reference Release pre7 32 / 215 See Also FireHOL program: firehol(1) FireHOL configuration: firehol.conf(5) interface definition: firehol-interface(5) router definition: firehol-router(5) policy command: firehol-policy(5) protection command: firehol-protection(5) client command: firehol-client(5) server, route commands: firehol-server(5) group command: firehol-group(5) iptables helper: firehol-iptables(5) masquerade helper: firehol-masquerade(5)

42 FireHOL + FireQOS Reference Release pre7 33 / 215 Chapter 7 Definition Commands

43 FireHOL + FireQOS Reference Release pre7 34 / interface definition: firehol-interface Name firehol-interface, firehol-interface4, firehol-interface6, firehol-interface46 create an interface definition Synopsis interface interface46 real-interface name [rule-params] interface4 real-interface name [rule-params] interface6 real-interface name [rule-params] Description An interface definition creates a firewall for protecting the host on which the firewall is running. The default policy is DROP, so that if no subcommands are given, the firewall will just drop all incoming and outgoing traffic using this interface. The behaviour of the defined interface is controlled by adding subcommands (listed in the section called See Also ). Note Forwarded traffic is never matched by the interface rules, even if it was originally destined for the firewall but was redirected using NAT. Any traffic to be passed through the firewall for whatever reason must be in a router (see router definition: firehol-router(5)). Note Writing interface4 is equivalent to writing ipv4 interface and ensures the defined interface is created only in the IPv4 firewall along with any rules within it. Writing interface6 is equivalent to writing ipv6 interface and ensures the defined interface is created only in the IPv6 firewall along with any rules within it. Writing interface46 is equivalent to writing both interface and ensures the defined interface is created in both the IPv4 and IPv6 firewalls. Any rules within it will also be applied to both, unless they specify otherwise.

44 FireHOL + FireQOS Reference Release pre7 35 / 215 Parameters real-interface This is the interface name as shown by ip link show. Generally anything iptables accepts is valid. The + (plus sign) after some text will match all interfaces that start with this text. Multiple interfaces may be specified by enclosing them within quotes, delimited by spaces for example: interface "eth0 eth1 ppp0" myname name This is a name for this interface. You should use short names (10 characters maximum) without spaces or other symbols. A name should be unique for all FireHOL interface and router definitions. rule-params The set of rule parameters to further restrict the traffic that is matched to this interface. See optional rule parameters: firehol-rule-params(5) for information on the parameters that can be used. Some examples: interface eth0 intranet src /24 interface eth0 internet src not "${UNROUTABLE_IPS}" See FireHOL configuration: firehol.conf(5) for an explanation of ${UNROUTABLE_IPS}. See Also FireHOL program: firehol(1) FireHOL configuration: firehol.conf(5) ipv4/ipv6 selection: firehol-modifiers(5) router definition: firehol-router(5) policy command: firehol-policy(5) protection command: firehol-protection(5) client command: firehol-client(5) server, route commands: firehol-server(5) group command: firehol-group(5) iptables helper: firehol-iptables(5) masquerade helper: firehol-masquerade(5)