=pod

=head1 NAME 

firehol.conf - Configuration file for firehol(1)

=head1 DESCRIPTION

F<firehol.conf> is the configuration file for firehol(1), which creates
an iptables firewall from the simple rules in this file.

This file is parsed as a bash(1) script, so it's no problem to use
variables or complex bashisms.

=head1 Commands

=head2 interface E<lt>real interfaceE<gt> E<lt>nameE<gt> [optional rule parameters]

=over 2

The interface command creates a firewall for protecting the host the
firewall is running, from the given interface.
The default interface policy is drop, so that if no subcommands are given,
the firewall will just drop all incoming and outgoing traffic using
this interface.

=head3 Parameters

=over 2

=item * real interface

This is the interface name as shown by ip link show. Generally anything
iptables accepts, including the pattern character + (the plus sign),
is valid. The plus sign after some text will match all interfaces that
start with this text. It is allowed to use more than one interfaces
separated by spaces, but all of them should be given within one 
quoted argument. Example:

  interface "eth0 eth1 ppp0" myname
       
=item * name

This is a name for this interface. Generally you should use short names
(10 characters max) without spaces or other symbols. You should not use 
the same name more than once in FireHOL primary commands.
       
=item * optional rule parameters

This is a set of rules that allow further restriction of the traffic that
gets matched for this interface. See section B<Optional Rules Parameters>
for more information. Examples:

=over 2

interface eth0 intranet src 10.0.0.0/16

interface eth0 internet src not "$UNROUTABLE_IPS" (note: UNROUTABLE_IPS
is a variable defined by FireHOL that includes all IPs that should not be
routable by the Internet).

=back

=back

=back

=head2 router E<lt>nameE<gt> [optional rule parameters]

=over 2

The router command creates a firewall for the traffic passing through 
the host running the firewall. The only acceptable policy on all router
commands is return and therefore the policy subcommand cannot be used on
routers. This means that no packets are dropped in a router. Packets not
matched by any router command will be dropped at the end of the firewall.

=head3 Parameters

=over 2

=item * name 

This is a name for this router. The same restrictions of interface names
apply here too.
 
=item * optional rule parameters

This is a set of rules that allow further restriction of the traffic that
gets matched for this router. See section B<Optional Rules Parameters>
for more information. 

=back

=head3 Description

=over 2

Router statements produce similar iptables commands the interface
statements produce. For each router statement an in_I<name> and
an out_I<name> chain are produced to match the traffic in both
directions of the router.

To match some client or server traffic the administrator has to specify
the input/output interface or the source/destination of the request. All
inface/outface, src/dst optional rule parameters can be given either on
the router statement in which case will be applied to all subcommands
for this router, or on each subcommand within a router. Both are valid. 

For example:

=over 2

router mylan inface ppp+ outface eth0
  server http accept
  client smtp accept
  
=back
	
The above says: Define a router that matches all requests that originate
from some PPP interface and go out to eth0. There is an HTTP server in
eth0 that client from the PPP interfaces are allowed to reach.
Clients on eth0 are allowed to get SMTP traffic from the PPP interfaces.

While:

=over 2

router mylan
  server http accept inface ppp+ outface eth0
  server smtp accept inface eth0 outface ppp+
  
=back

The above says: Define a router that matches any kind of forwarded traffic.
For HTTP traffic the clients are on a PPP interface and the servers on eth0.
For SMTP traffic the clients are on a eth0 interface and the servers o a 
PPP interface.

Please note that in the second example the SMTP traffic is matched again
with a server subcommand, not a client (as in the first example).

The client subcommand reverses all the optional rules that are applied 
indirectly to it. Indirect rule parameters are those that are inherited
from the parent command (router in this case).
To make it simple, for FireHOL a client is: "a server with all the
implicit optional rule parameters reversed".

So, in the first example, the client simply flipped the inface and outface
rules defined at the router and became an SMTP server.
In the second example there is nothing to be flipped, so server and client
are exactly the same.

I suggest to use client subcommands in routers only if you have 
inface/outface or src/dst in the router statements. If you are building
routers like the second example, don't use client, it is confusing.

Older versions of FireHOL did not allow server and client subcommands
in routers. Only the route subcommand was allowed. Today, route is just
an alias for server and can be used only in routers, not interfaces.

Any number of router statements can exist. Since the policy is RETURN
on all of them, any traffic not matched by a router will continue to be
checked against the second. 

=back

=back

=head1 Subcommands

Subcommands must be given within Primary commands.

=head2 policy E<lt>actionE<gt>

=over 2

The policy subcommand defines the default policy for an interface.

This directive accepts all the actions specified in the section
B<Actions>.

The policy of routers cannot be changed and is always RETURN. 

=back

=head2 protection [reverse] <type>

=over 2

The protection subcommand sets a number of protection rules 
on an interface.

In router configurations, protections are setup on inface.

=head3 Parameters

=over 2

=item reverse

The reverse keyword will make the protections setup on outface.

=item type

One of the following values:

=over 2

=item strong, full or all

Turns on all known protections

=item fragments

Drops all packet fragments. Please note that most probably this
rule will never match anything since iptables reconstructs all
packets automatically, before the iptables firewall rules are 
processed, when its connection tracker is running.

=item new-tcp-w/o-syn

Drops all TCP packets that initiate a socket but have no the SYN bit set.

=item syn-floods [requests/sec [burst]]

Allows only a certain amount of new TCP connections per second. The
optional two arguments [requests/sec] and [burst] are used by this
rule in order to provide control on the number of connections to be
allowed. The default is 100 connections per second that can match 50
(it was 4 in v1.38 and before) packets initially (this is implemented
using the limit module of iptables: see man iptables for more).
Note that this rule applies to all connections attempted regardless 
of their final result (rejected, dropped, established, etc). Therefore
it might not be a good idea to set it too low. 

=item icmp-floods [requests/sec [burst]]

Allows only a certain amount of ICMP echo requests per second. The 
optional two arguments [requests/sec] and [burst] are used by this
rule in order to provide control on the number of connections to be
allowed. The default is 100 connections per second that can match 50
(it was 4 in v1.38 and before) packets initially (this is implemented
using the limit module of iptables: see man iptables for more). 

=item malformed-xmas

Drops all TCP packets that have all TCP flags set. 

=item malformed-null

Drops all TCP packets that have all TCP flags unset. 

=item malformed-bad

Drops all TCP packets that have illegal combinations of TCP flags set. 

=back

=back 

=back

=head2 server E<lt>serviceE<gt> E<lt>actionE<gt> [optional rule parameters]

=over 2

The server subcommand defines a server of a service. For FireHOL a 
server is the destination of a request, and even if this is more
complex for multi-socket services, for FireHOL a server always
accepts requests.

The optional rule parameters given to the parent primary command
(interface or router) are inherited by the server as they have
been given.

This subcommand can be used on both interfaces and routers.

=head3 Parameters

=over 2

=item service

This is one of the supported service names. The command accepts more
than one services in the same argument if they are separated by 
space and quoted as a single argument. Example:

=over 2

server smtp accept

server "smtp pop3 imap" accept

=back
       
=item action

This tells FireHOL what to do with the traffic matching this rule.

FireHOL supports the actions defined in the section B<Actions>.
       
=item optional rule parameters

This is a set of rules that allow further restriction of the 
traffic that gets matched by this rule. See section 
B<Optional Rules Parameters> for more information. Examples:

=over 2

server smtp accept src 1.2.3.4

server smtp accept log "its mail" src 1.2.3.4 

=back

=back

=back

=head2 client E<lt>serviceE<gt> E<lt>actionE<gt> [optional rule parameters]

=over 2

The client subcommand defines a client of a service. For FireHOL
a client is the source of a request. FireHOL follows this simple
rule even on multi-socket complex protocols, so that for FireHOL
a client always sends requests.
The parameters are exactly the same with the server subcommand.

The optional rule parameters given to the parent primary command
(interface or router) are inherited by the client, but they are
reversed. For an explanation of this please refer to the 
documentation of the router primary command.

This subcommand can be used on both interfaces and routers.

=back

=head2 route E<lt>serviceE<gt> E<lt>actionE<gt> [optional rule parameters]

=over 2

The route subcommand is an alias for the server command that
can be used only on routers, not interfaces.

=back

=head1 Helper commands

=head2 version E<lt>numberE<gt>

=over 2

The version command states the FireHOL release the configuration file
was created for. In case the configuration file is newer than FireHOL,
FireHOL will deny to run it.

This command is here to allow you or anyone else design and distribute 
FireHOL configuration files, while ensuring that the correct FireHOL
version is going to run them.

The FireHOL release is increased every time the format of the
configuration file and the internals of FireHOL are changed.

Since FireHOL v1.67 version is not required to be present in
every configuration file. 

=back

=head2 iptables E<lt>argumentsE<gt>

=over 2

The iptables command passes all its arguments to the real iptables
command, during run-time.

You should not use /sbin/iptables directly to alter a FireHOL firewall
in its configurations. If you do, your commands will be run before
FireHOL activates its firewall and while the previous firewall is
still running. Also, since FireHOL will delete all previous firewall
rules in order to activate the new firewall, any changes you will
make, will be deleted too.

Always use the iptables directive to hook iptables commands in a
FireHOL firewall. Nothing else. 

=back

=head2 masquerade [reverse | interface] [optional rule parameters]

=over 2

Masquerading is a special from of SNAT (Source NAT) that changes the
source of requests when they go out and replaces their original source
when replies come in. This way a Linux box can become an internet
router for a LAN of clients having unroutable IP addresses.
Masquerading takes care to re-map IP addresses and ports as required.

Masquerading is "expensive" compared to SNAT because it checks the IP
address of the ougoing interface every time for every packet, and 
therefore it is suggested that if you connect to the internet with
a static IP address, to prefer SNAT.

The masquerade helper sets up masquerading on the output of a network
interface (not the interface command, but a real network interface).

If the masquerade command is placed within an interface command, its
network interface[s] will be used.

If the masquerade command is placed within a router command that has
an outface defined, then the outface network interface[s] will be used.

If placed within a router command but the keyword reverse is specified
and the router command has an inface defined, then the inface network
interface[s] will be used.

If placed outside and before all primary commands, an interface (or
list of space separated interfaces, within double quotes) can be
specified on the masquerade command.

In all cases, masquerade will setup itself on the output of the
given interface[s].

Please note that if masquerade is used within some interface or router,
it does not respect the optional rule parameters given to this interface
or router command. Masquerade uses only its own optional rule parameters.

inface and outface should not be given as parameters to masquerade 
(inface because iptables does not support this in the POSTROUTING chain,
and outface because it will be overwritten by the interface(s) mentioned
above).

Finally, the masquerade helper will turn on FIREHOL_NAT and instruct the
kernel to do packet forwarding (like the router commands do).

Examples:

=over 2

Before the first interface or router:
  masquerade eth0 src 10.0.0.0/8 dst not 10.0.0.0/8
  
Within an interface rule to masquerade on the output of this interface:
  masquerade
  
Within a router rule to masquerade on the output of the router's inface:
  masquerade reverse

=back

=back


=head2 transparent_squid E<lt>portE<gt> E<lt>userE<gt> [optional rule parameters]

=over 2

The transparent_squid helper sets up trasparent caching for HTTP traffic.
The squid proxy is assumed to be running on the firewall host at port 
I<port> (I<port> defaults to squid), with the credentials of the
local user I<user> (I<user> defaults to squid).

The transparent_squid helper can be used for two kinds of traffic:

=over 2

=item * Incoming HTTP traffic

Incoming HTTP traffic, which is either targeted to the firewall host
or passing through the firewall host.

The optional rule parameters can be used to specify which kind of 
incoming traffic to be catched (by using inface, src, dst, etc --
outface should not be used here, because the rules generated are
placed before the routing decision and therefore the outgoing
interface is not yet known).

If no optional rule parameters are given, then the transparent
cache will be setup on all network interfaces for all HTTP
traffic (use this with care since you are risking to serve
requests from the internet using your squid).
       
=item * Locally HTTP traffic

Locally generated HTTP traffic except traffic generated by processes
running as user I<user>. The optional rule parameters inface, outface
and src are ignored for this type of traffic.

This kind of matching makes it possible to support transparent caching
for WEB browsers running on the firewall host, as far as they do not
run as the user excluded. More than one users can be specified by 
space-separating and enclosing them in double quotes.

This rule can be disabled by specifing as user the empty string: ""

=back 

Examples:

=over 2

transparent_squid 3128 squid inface eth0 src 10.0.0.0/8

transparent_squid 8080 "squid privoxy root bin" inface not "ppp+ ipsec+" dst not "a.not.proxied.server" 

=back 

=back

=head2 nat E<lt>typeE<gt> E<lt>targetE<gt> [optional rule parameters]

=over 2

The nat helper sets up a NAT rule for routed traffic.

The type parameter can be:

=over 2

=item to-source

Defines a Source NAT (created in NAT/POSTROUTING).

The I<target> in this case is the source address to be set in packets 
matching the optional rule parameters (if no optional rule parameters,
all forwarded traffic will be matched). I<target> accepts all 
--to-source values iptables accepts (see iptables -j SNAT --help).
Multiple --to-source values can be given, if separated by space and
quoted as a single argument.

inface should not be used in SNAT, because iptables does provide
this information at this point.
       
=item to-destination

Defines a Destination NAT (created in NAT/PREROUTING).

The I<target> in this case is the destination address to be set in packets
matching the optional rule parameters (if no optional rule parameters,
all forwarded traffic will be matched). I<target> accepts all --to-destination
values iptables accepts (see iptables -j DNAT --help). Multiple
--to-destination values can be given, if separated by space and quoted
as a single argument.

outface should not be used in DNAT, because iptables does provide
this information at this point.
       
=item redirect-to

Catches traffic comming in and send it to the local machine (created
in NAT/PREROUTING).

The I<target> in this case is a port or a range of ports (XXX-YYY) that
packets matching the rule will be redirected to (if no optional rule
parameters are given, all incomming traffic will be matched). I<target>
accepts all --to-ports values iptables accepts (see iptables -j 
REDIRECT --help).

outface should not be used in REDIRECT, because iptables does provide
this information at this point.
        
=back

Please understand that the optional rule parameters are used only
to limit the traffic to be matched. Consider these examples:

=over 2

=item Sends to 1.1.1.1 all traffic comming in or passing trhough the firewall host:

nat to-destination 1.1.1.1	

=item Redirects to 1.1.1.1 all traffic comming in or passing through, and going to 2.2.2.2:

  nat to-destination 1.1.1.1 dst 2.2.2.2	

=item Redirects to 1.1.1.1 all TCP traffic comming in or passing through and going to 2.2.2.2:

  nat to-destination 1.1.1.1 proto tcp dst 2.2.2.2	

=item Redirects to 1.1.1.1 all traffic comming in or passing through and going to 2.2.2.2 to port tcp/25:

  nat to-destination 1.1.1.1 proto tcp dport 25 dst 2.2.2.2

=back

More examples:

=over 2
	
nat to-source 1.1.1.1 outface eth0 src 2.2.2.2 dst 3.3.3.3

nat to-destination 4.4.4.4 inface eth0 src 5.5.5.5 dst 6.6.6.6

nat redirect-to 8080 inface eth0 src 2.2.2.0/24 proto tcp dport 80 

=back

=back

=head2 snat [to] E<lt>targetE<gt> [optional rule parameters]

=over 2

The snat helper sets up a Source NAT rule for routed traffic, by calling
nat to-source I<target> [optional rule parameters]

See the nat helper.

Example:

=over 2

snat to 1.1.1.1 outface eth0 src 2.2.2.2 dst 3.3.3.3 

=back

=back

=head2 dnat [to] E<lt>targetE<gt> [optional rule parameters]

=over 2

The dnat helper sets up a Destination NAT rule for routed traffic, by calling
nat to-destination I<target> [optional rule parameters]

See the nat helper.

Example:

=over 2

dnat to 1.1.1.1 inface eth0 src 2.2.2.2 dst 3.3.3.3 

=back

=back

=head2 redirect [to] E<lt>targetE<gt> [optional rule parameters]

=over 2

The redirect helper catches all incomming traffic matching the optional rule
parameters given and redirects it to ports on the local host, by calling
nat redirect-to I<target> [optional rule parameters]

See the nat helper.

Example:

=over 2

nat redirect-to 8080 inface eth0 src 2.2.2.0/24 proto tcp dport 80 

=back

=back

=head1 Actions

Actions are the actions to be taken on services and traffic described
by other commands and functions. Please note that normally, FireHOL
will pass-through to the generated iptables statements all the possible
actions iptables accepts, but only the ones defined here can be used 
with lower case letters and currently it will be impossible to pass 
arguments to some unknown action. Also, keep in mind that the iptables
action LOG is a FireHOL optional rule parameter (see log and loglimit)
that can be defined together with one of the following actions and
FireHOL will actually produce multiple iptables statements to achieve
both the logging and the action.

=head2 accept

=over 2

accept allows the traffic matching the rules to reach its destination.

Example:

=over 2

server smtp accept, to allow SMTP requests and their replies to flow. 

=back

=back

=head2 reject [with message]

=over 2

reject discards the matching traffic but sends a rejecting message back to the sender.

with is used to offer control on the message to be returned to the sender. with accepts
all the arguments the --reject-with iptables expression accepts. For an updated list of
these messages type iptables -j REJECT --help. 

Examples:

=over 2

policy reject with host-unreach

server ident reject with tcp-reset

UNMATCHED_INPUT_POLICY="reject with host-prohib"

=back

=back


=head2 drop

=over 2

drop silently discards the matching traffic. The fact that the traffic
is silently discarded makes the sender timeout in order to conclude
that it is not possible to use the wanted service.

Example: 

=over 2

server smtp drop, to silently discard SMTP requests and their replies. 

=back

=back


=head2 deny

=over 2

deny is just an alias for drop, made for those who are used to ipchains
terminology.

Example: 

=over 2

server smtp deny, to silently discard SMTP requests and their replies. 

=back

=back

=head2 return

=over 2

return will return the flow of processing to the parent of the current command.
Currently, it has meaning to specify the action return only as a policy to some
interface.

Example: 

=over 2

=item policy return 

Traffic not matched by any rule within an interface continues traveling
through the firewall and is possibly matched by other interfaces bellow. 

=back

=back

=head2 mirror

=over 2

I<mirror> will return the traffic to the wanted port, back to the sending
host. Use this with care, and only if you understand what you doing.
Keep also in mind that FireHOL will apply this action to both requests
and replies comming in or passing through, and will replace it with 
REJECT for traffic generated by the local host.

=back

=head2 redirect [to-port port]

=over 2

I<redirect> is used internally by FireHOL Helper Commands to redirect 
traffic to ports on the local host. Unless you are a developer,
you will never need to use this directly.

=back

=head1 Optional Rule Parameters

Optional rule parameters are accepted by many commands to narrow 
the match they do by default. The parameters described bellow are
all that FireHOL supports. You should check the documentation of 
each command to find which parameters should not be used with it.
Normally, all FireHOL commands are designed so that if you specify
a parameters that is also used internally, the internal one will
overwrite the one given in the configuration file. In such a case,
FireHOL will present you a warning with the old and the new value.

Not all parameters should be used in all cases. For example I<sport>
and I<dport> should not be used in normal server and client commands
since such ports are internally defined by the services themselves.
In any case, FireHOL will complain about optional rule parameters
that should not be used in certain commands.


=head2 src [not] E<lt>hostE<gt>

=over 2

I<src> defines the source IP address of the REQUEST. If I<src> is 
defined on a server statement it matches the source of the request 
which is the remote host, while if it is defined on a client 
statement it matches again the source of the request, but this time
it is the local host. Focus on the REQUEST!!! Forget the reply.

=head3 Parameters

=over 2

=item not 

Optional argument that reverses the match. When defined, the rule will
match all hosts except the ones defined. Example: 
  server smtp accept src not 1.2.3.4
       
=item I<host>

An IP address, a hostname, or a subnet. Multiple hosts/networks can be
defined if separated by space and quoted as a single argument. Examples:
  server smtp accept src 1.2.3.4
  server smtp accept src not "1.2.3.0/24 5.6.7.8 badhost.example.com" 

=back

=back

=head2 dst [not] E<lt>hostE<gt>

=over 2

I<dst> defines the destination of the REQUEST. If dst is defined on a server
statement it matches the destination of the request which is the local
host, while if it is defined on a client statement it matches again
the destination of the request, but this time it is the remote host.
Focus on the REQUEST!!! Forget the reply.

I<dst> accepts the same parameters as src.

=back


=head2 inface [not] E<lt>interfaceE<gt>

=over 2

I<inface> defines the interface the REQUEST is received via. inface cannot
be used in interface commands.

=head3 Parameters

=over 2

=item not 

An optional argument that reverses the match. When defined, the rule will
match all interfaces except the ones defined. Example:
  server smtp accept inface not eth0
       
=item I<interface>

if an interface name in the same format the interface command accepts.
Multiple interfaces can be defined if separated by space and quoted as
a single argument. Examples:
  server smtp accept inface not eth0
  server smtp accept inface not "eth0 eth1"

=back

=back

=head2 outface [not] E<lt>interfaceE<gt>

=over 2

I<outface> defines the interface the REQUEST is send via. outface cannot
be used in interface commands.

I<outface> accepts the same parameters as inface. 

=back

=head2 custom E<lt>parametersE<gt>

=over 2

I<custom> passes its arguments to the generated iptables commands.

It is required to quote all the parameters given to custom. If the
parameters include a space character between some text that is 
required to be given to iptables as one argument, it is required
to escape another set of quotes in order. Another way is to use
double quotes externally and single quotes internally.

Examples:

  server smtp accept custom "--some-iptables-option and_its_value"
  
  server smtp accept custom "--some-iptables-option 'one_value another_value'

=back

=head2 log "E<lt>some textE<gt>" [level a_level]

=over 2

I<log> will log the matching packets to syslog. Note that this is not an
action (in iptables it is). FireHOL will actually produce multiple
iptables commands to accomplish both the action for the rule and the
logging. You can control how logging works, by altering the variables
FIREHOL_LOG_OPTIONS and FIREHOL_LOG_LEVEL. You can also change the
level of just one rule by using the level argument of the log parameter.

FireHOL logs traffic, exactly the same way iptables does. Many users have
complained about packet logs appearing at their console. To avoid this 
you will have to:

=over 2

=item * setup klogd to log only more important traffic

=item * change FIREHOL_LOG_LEVEL to log at a not so important log-level

=back

Actually klogd's -c option and iptables' --log-level option are the same
thing (iptables accepts also the numeric values klogd accepts). If
iptables logs at a higher priority than klogd is configured to use,
then your packets will appear in the console too.

=back

=head2 loglimit "E<lt>some textE<gt>"

=over 2

I<loglimit> is the same with log but limits the frequency of logging 
according to the setting of FIREHOL_LOG_FREQUENCY and FIREHOL_LOG_BURST.

=back

=head2 proto [not] E<lt>protocolE<gt>

=over 2

I<proto> sets the required protocol for the traffic. This command 
accepts anything iptables accepts as protocols.

=back

=head2 limit E<lt>frequencyE<gt> E<lt>burstE<gt>

=over 2

I<limit> will limit the match in both directions of the traffic 
(request and reply). This is used internally by FireHOL and its
effects has not been tested in the high level configuration file
directives.

=back

=head2 sport E<lt>portE<gt>

=over 2

I<sport> defines the source port of a request. It accepts port 
names, port numbers, port ranges (FROM:TO) and multiple ports
(or ranges) seperated by spaces and quoted as a single argument.
This parameter should not be used in normal services definitions
(client and server commands) or interface and router definitions,
unless you really understand what you are doing.

=back

=head2 dport E<lt>portE<gt>

=over 2

I<dport> defines the destination port of a request. It accepts port
names, port numbers, port ranges (FROM:TO) and multiple ports (or
ranges) seperated by spaces and quoted as a single argument. This 
parameter should not be used in normal services definitions (client
and server commands) or interface and router definitions, unless you
really understand what you are doing.

=back

=head2 uid [not] E<lt>userE<gt>
=head2 user [not] E<lt>userE<gt>

=over 2

I<uid> or I<user> define the operating system user sending this
traffic. The parameter can be a username, a user number or a list
of these two, seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server
commands) defined within interfaces, not routers. FireHOL is 
"smart" enough to apply this parameter only to traffic send by 
the localhost, i.e. the replies of servers and requests of 
clients. It is not possible, and FireHOL will simply ignore 
this parameter, on traffic coming in or passign through the 
firewall host.

Example 1:

=over 2

  client "pop3 imap" accept user not "user1 user2 user3" dst mymailer.example.com

=back

The above will allow local users except user1, user2 and user3 to use
POP3 and IMAP services on mymailer.example.com. You can use this, for
example, to allow only a few of the local users use the fetchmail
program to fetch their mail from the mail server.

Example 2: 

=over 2

  server http accept user apache

=back
  
The above will allow all HTTP to reach the local http server, but only
if the web server is running as user apache the replies will be send
back to the HTTP client. 

=back

=head2 gid E<lt>groupE<gt>
=head2 group E<lt>groupE<gt>

=over 2

I<gid> or I<group> define the operating system user group sending this
traffic. The parameter can be a group name, a group number or a list of
these two, seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server commands)
defined within interfaces, not routers. FireHOL is "smart" enough to
apply this parameter only to traffic send by the localhost, i.e. the 
replies of servers and requests of clients. It is not possible, and 
FireHOL will simply ignore this parameter, on traffic coming in or
passing through the firewall host. 

=back

=head2 pid E<lt>processE<gt>
=head2 process E<lt>processE<gt>

=over 2

I<pid> or I<process> define the operating system process ID (or PID) 
sending this traffic. The parameter can be a PID or a list of PIDs,
seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server
commands) defined within interfaces, not routers. FireHOL is "smart"
enough to apply this parameter only to traffic send by the localhost,
i.e. the replies of servers and requests of clients. It is not
possible, and FireHOL will simply ignore this parameter, on traffic
coming in or passign through the firewall host. 

=back

=head2 sid E<lt>sessionE<gt>
=head2 session E<lt>sessionE<gt>

=over 2

I<sid> or I<session> define the operating system session ID of the 
process sending this traffic (The session ID of a process is the 
process group ID of the session leader). The parameter can be a list
of such IDs, seperated by spaces and quoted as a single argument.

This parameter can be used only in services (client and server 
commands) defined within interfaces, not routers. FireHOL is "smart"
enough to apply this parameter only to traffic send by the localhost,
i.e. the replies of servers and requests of clients. It is not
possible, and FireHOL will simply ignore this parameter, on traffic
coming in or passign through the firewall host. 

=back

=head1 Variables that control FireHOL

=head2 DEFAULT_INTERFACE_POLICY

=over 2

I<DEFAULT_INTERFACE_POLICY> controls the default action to be taken
on traffic not matched by any rule within an interface. Actually, 
this is a global setting for what policy does for an interface.

All packets that reach the end of an interface are logged only if the
action is not return or accept. You can control the frequency of this
logging by altering the frequency loglimit uses.

 Default: DEFAULT_INTERFACE_POLICY="DROP"

 Example: DEFAULT_INTERFACE_POLICY="REJECT" 

=back

=head2 UNMATCHED_INPUT_POLICY

=head2 UNMATCHED_OUTPUT_POLICY

=head2 UNMATCHED_FORWARD_POLICY

=over 2

I<UNMATCHED_INPUT_POLICY> controls the default action to be taken for
incoming traffic not matched by any interface command.

I<UNMATCHED_OUTPUT_POLICY> controls the default action to be taken for
outgoing traffic not matched by any interface command.

I<UNMATCHED_FORWARD_POLICY> controls the default action to be taken for
forwarded traffic not matched by any router command.

All variables accept all the Actions FireHOL supports.

All packets that reach the end of firewall in all three chains are
logged (always, regardless of these settings). You can control the
frequency of this logging by altering the frequency loglimit uses.

 Default: UNMATCHED_INPUT_POLICY="DROP"
 
 Default: UNMATCHED_OUTPUT_POLICY="DROP"
 
 Default: UNMATCHED_FORWARD_POLICY="DROP"


 Example: UNMATCHED_INPUT_POLICY="REJECT"
 
 Example: UNMATCHED_OUTPUT_POLICY="REJECT"
 
 Example: UNMATCHED_FORWARD_POLICY="REJECT" 

=back

=head2 FIREHOL_LOG_LEVEL
=head2 FIREHOL_LOG_OPTIONS
=head2 FIREHOL_LOG_FREQUENCY
=head2 FIREHOL_LOG_BURST

=over 2

I<FIREHOL_LOG_LEVEL> controls the level at which iptables will log 
things to the syslog. For a description of the possible values
supported and for per-rule control of log level, see the log optional 
rule parameter.

I<FIREHOL_LOG_OPTIONS> controls the way iptables will log things to 
the syslog. The value of this variable is passed as is to iptables,
so use exact iptables parameters.

I<FIREHOL_LOG_FREQUENCY> and I<FIREHOL_LOG_BURST> (added in v1.39 of
FireHOL) control the frequency at each each logging rule will write
packets to the syslog. FIREHOL_LOG_FREQUENCY is set to the maximum
average frequency and FIREHOL_LOG_BURST specifies the maximum
initial number of packets to match.

 Default: FIREHOL_LOG_OPTIONS="--log-level warning"
 
 Default: FIREHOL_LOG_FREQUENCY="1/second"
 
 Default: FIREHOL_LOG_BURST="5"
 

 Example: FIREHOL_LOG_OPTIONS="--log-level info --log-tcp-options --log-ip-options"
 
 Example: FIREHOL_LOG_FREQUENCY="30/minute"
 
 Example: FIREHOL_LOG_BURST="2"

To see the available iptables log options, run C</sbin/iptables -j LOG --help>
To see what iptables accepts as frequencies and bursts, run
C</sbin/iptables -m limit --help> 

You can also check man iptables.

=back

=head2 DEFAULT_CLIENT_PORTS

=over 2

I<DEFAULT_CLIENT_PORTS> controls the port range to be used when a 
remote client is specified. For localhost clients, FireHOL finds 
the exact client ports by querying the kernel options.

 Default: 1000:65535
 
 Example: DEFAULT_CLIENT_PORTS="0:65535" 

=back

=head2 FIREHOL_NAT

=over 2

If I<FIREHOL_NAT> is set to 1, FireHOL will load NAT kernel modules
for those services that they are require such. FireHOL sets this 
to 1 automatically if you use the Helper Commands that do NAT.

 Default: FIREHOL_NAT="0"
 
 Example: FIREHOL_NAT="1" 

=back

=head2 FIREHOL_AUTOSAVE

=over 2

FIREHOL_AUTOSAVE controls the file that will be created when FireHOL
is called with the save command line argument. If this variable is
empty (the default), FireHOL will try to detect where to save the 
file. Currently, the RedHat way (/etc/sysconfig/iptables) and the
Debian way (/var/lib/iptables/autosave) are automatically detected
(in the order given here) based on the existance of the directory 
this file should be created in.

Default: FIREHOL_AUTOSAVE=""
Example: FIREHOL_AUTOSAVE="/tmp/firehol-saved.txt" 

=back

=head1 Variables that FireHOL offers

=head2 RESERVED_IPS

=over 2

This variable includes all the IP addresses defined as IANA - Reserved
by IANA.

 Example: interface eth0 internet src not "${RESERVED_IPS}" 

=back

=head2 PRIVATE_IPS

=over 2

This variable includes all the IP addresses defined as Private or
Test by RFC 3330.

 Example: interface eth0 internet src not "${PRIVATE_IPS}" 

=back

=head2 UNROUTABLE_IPS

=over 2

This variable is both I<RESERVED_IPS> and I<PRIVATE_IPS> together. I suggest
to use this variable on interfaces and routers accepting Internet traffic.

 Example: interface eth0 internet src not "${UNROUTABLE_IPS}" 

=back

=head1 FILES

F</etc/firehol/firehol.conf>

=head1 AUTHOR

firehol written by Costa Tsaousis E<lt>costa@tsaousis.grE<gt>.

Man page written by Marc Brockschmidt E<lt><marc@marcbrockschmidt.deE<gt>.

=head1 SEE ALSO

firehol(1), iptables(8), bash(1)

=cut
