NAME

Fwctl - Perl module to configure the Linux kernel packet filtering firewall.

SYNOPSIS

use Fwctl;

my $fwctl = new Fwctl( %opts );
$fwctl->dump_acct;
$fwctl->reset_fw;
$fwctl->configure;

DESCRIPTION

Fwctl is a module to configure the Linux kernel packet filtering firewall using higher level abstraction than rules on input, output and forward chains. It supports masquerading and accounting as well.

Why Fwctl ? Well, say you are the kind of paranoid firewall administrator which likes his firewall's rules tight. Very tight. Say the kind, that likes to distinguish between a SYN and ACK packet when accepting a TCP connection (anybody configuring packet filters should care about that last point), or like to specify the interface name on each rules. (Whether this is really need, or such a stance is relevant, is not the point.) How would such an administrator proceed ? First of all you deny everything on all interfaces and on all chains (input, forward and output) and turn on logging. Now starting from this configuration (in which Fwctl puts the firewall on initialization), say you want to enable ping from the internal network to the internal ip. What rules do you need ? You need a rule on the input chain to accept the echo-request packet and a rule on the output chain to accept the echo-reply request. Right ? Well, what about the loopback. For sure, when we say from local net to local ip, this imply local ip to local ip ? Then you add a rule to the output chain with the loopback interface, and a rule on the input rule to the loopback chain. And we didn't even start forwarding yet ! Add masquerading to the lot and multi connections protocols like FTP and you got something unmanageable. So you start accepting things you shouldn't to get your job done and in the end your filters look like emmenthal.

Fwctl handles all the complexity of this, so that when you say

accept ftp -src FTP_PROXY -dst INTERNET -noport

you don't accept too much of what you didn't intend. (Well you just opened arbitrary TCP connections to unprivileged ports on the Internet from your proxy server, but that's because of the FTP protocol, not because your cheating on the firewall rules.)

Fwctl works with entity known as service. A service can be ftp, netbios, ping or anything else. The service abstraction handles all the communication necessary for that application. (The UDP and TCP communication in DNS, or the control, data and passive connections for FTP.)

Additionally, to handle all the special case with ANY specification, when the src of dst imply a local IP, or masquerading, in short for Fwctl to be able to deduce the interface implicated by the src and dst portion of a rules you need to provide it with your network topology. Fwctl must guess from your topology the routing decision that will be made in the kernel. In the best of worlds, Fwctl should contains the same routing algorithm as the one in the kernel. Well, it doesn't so if you are using fancy routing feature, Fwctl won't work. In fact, it can only handle something equivalent to simple static routing. You have been warned.

So in short, to configure your packet filters with Fwctl you need to

Define your network topology using the interfaces file.
(Optional) Define meaningful aliases for hosts and networks which are part of your configuration.
Implement your security policy using high level abstract rules in the rules file.

Finally, Fwctl is extensible. You can easily add services modules using the Fwctl::RuleSet module which contains all the primitive you need to handle all the special cases involved in the input, forward and output chain selection.

CONFIGURATION

Fwctl configures the Linux kernel packet filtering firewall using three files: the interfaces file that describes your network topology, the aliases file that can contains meaningful aliases and the rules files that contains the services policy for the firewall.

TOPOLOGY

The interfaces file (default to /etc/fwctl/interfaces) describes your firewall topology. This is a text file in which comments (starting by a # and continuing until the end of line) and blank lines are ignored.

Each non blank, non comment lines is an interface specification. The format of the interfaction specification is

NAME    INTERFACE	IP/MASK	    [NETWORK]*

NAME: This is the name of the interface. It can be anyting. (Well please keep to alphanumeric characters plus underscore). There are two reserved names and a magical one. LOCAL refers to the loopback interface and shouldn't be redefined. ANY refers to a interface matching all the defined interfaces. You should defined at least an interface named EXT which corresponds to the interface connected to the default route. This is the interface on which Internet traffic usually come and go.
INTERFACE: This should be set to the kernel interface name. (eth0, ppp0, tunl0, etc.) You may specifiy here alias interface (eth0:0) but the Fwctl will canonicalize the name to the master interface (eth0) to match the way the kernel 2.2 use them.
IP/MASK: This is the IP address and Netmask of the interface. The netmask can be specified in either netmask notation (255.255.255.0) or CIDR notation (24).
NETWORKS: This is an optional space separated list of IP/MASK networks connected to this interface. This is to handle internal network connected to WAN link.

The interfaces file should correspond to your firewall network configuration. It should adequatly represent its runtime interface and routing configuration or this module is useless.

ALIASES

The aliases file contains meaningful aliases for use in the rules file.

Comments (starts with # and continues untill the end of line) and blank lines are ignored.

Alias line are of the form :

ALIAS [:=]+ EXPANSION

ALIAS

This is the mnemonic alias. For example, you could use MAIL_SERVER, CORPORATE_OFFICE, aNotSoUsefulAlias, etc. Please restrict yourself to alphanumeric character plus underscore. And be sure to read the predefined aliases section.

EXPANSION

This is what the alias expands to. This can be a space separated list of host or network specification or other alias.

The host or network expansion can also be tagged with an interface name which specifies which interface is associated with that alias and that will be use for routing logic. If you don't specify an interface Fwctl will figure out which interface is associated to the host or network using conventional routing logic. Be warned though that if you have interfaces that shares the same IP or have the same network attached if won't do probably what you intended. If all interfaces have distinctive IP and networks it will be probably fine tough.

Example :

VPN_CLIENT1 = 192.168.2.10(VPN1)

Aliases are recursively expanded. Please avoid infinite recursion or you will get a complaint at parse time.

Here is a list of predefined aliases. (All those aliases are associated with their interface for routing pupose).

INTERNET

This alias represents any host or network connected through the EXT interface.

ANY

This alias represents any host or network connected through any interface.

<IF>_IP

The is an alias name IF_IP for each defined interface which corresponds to the IP address of this interface.

For example, if you have defined the EXT interface and a INTERNAL interface, the aliases LOCAL_IP, EXT_IP and INTERNAL_IP. (Remenber the automatic LOCAL interface).

<IF>_NET

The is an alias name IF_NET for each defined interface which corresponds to the network attached to this interface.

<IF>_BCAST

The is an alias name IF_IP for each defined interface which corresponds to the broadcast address of this interface.

<IF>_REM_NETS

The is an alias name IF_IP for each defined interface which corresponds to all the networks that are routed through this interface excepted the one directly connected.

<IF>_NETS

The is an alias name IF_IP for each defined interface which corresponds to all the networks attached to this interface, not only the direct one.

RULES

The rules file contains your firewall policy implementation. It is a text file that describes the policy for each services.

As usual, (do I even need to mention it?) comments (starts with # and continues until the end of line) and blanks line are ignored.

Rules format is :

ACTION  SERVICE OPTIONS

ACTION: What to do with this service can be one of accept, reject, deny or account. See POLICY section for explanation.
SERVICE: This is the name of the service which is the target of the action. The service is handled by a module called Fwctl::Services::<service>.pm but see AUTOMATIC SERVICES.
OPTIONS: This is a space separated list of options which further specify what is the actual policy. Option name starts with - or -- and can be abbreviated to uniquesess. Some options takes a paremeters some are flags. Read the doc. These options are module specific but see STANDARD OPTIONS section.

POLICY

There are four possible actions for a service. These are ACCEPT, DENY, REJECT or ACCOUNT. (These are actually case insensitive).

ACCEPT: This will accept the service.
DENY: This traffic part of this service will be drop without anyone knowing. (Except probably your logs.)
REJECT: Traffic part of this service will be dropped with a proper message being sent to the originating party.
ACCOUNT: Packets part of this service will be counted. This won't accept or deny the service. Use one of the other three actions to define the actual fate of this service.

SERVICE

A service are module that encapsulates the collection of IP traffic that are part of an application. For example, to accept or account the FTP service, you must accept two or three TCP connections, the rsh service uses two. DNS service need 1 TCP connection and an UDP circuit.

The SERVICE abstraction is needed to insulates the administrator from the idiosyncrasies of the service. Needless to say that the adminstrator should be familiar with the idiosyncrasies of the service to be able to make an appropriate security judgement about the service. It's just that it is easier once the judgement has been made to accept or deny the specific service.

Each service is a perl module named Fwctl::Services::name which knows the particular IP traffic that is part of this service.

AUTOMATIC SERVICES

As a convenience to the administrator (and programmer) simple one way TCP service are automatically created at runtime. For example, this distribution doesn't contains a telnet service. But since the telnet service is only a tcp connection from client to the server's telnet port. If you use ACCEPT telnet in your rules, a telnet service is automatically generated as a subclass of tcp_service with a destination port of telnet. You could use in this way pop-3, imap or any protocol which has only a client/server TCP connection.

OPTIONS

Each service can defined a number of options but here are the standard one that each service should implement.

--src

Specify the client part of the service. This can be a list of IP or network addresses, or aliases. Once the aliases are expanded only IP addresses must remains. When you configure your firewall DNS shouldn't be available. If you need name, that's what the aliases is for.

If there are more than one IP address, it is equivalent as if you had specified a different rule with each address. (i.e.: If you have 4 IPs, this is transformed in four rules).

If this option is not present. It is the same as --src ANY.

--dst

Specify the server part of the service. The syntax of this option is identical to the src one.

--masq or --nomasq

If this option is set, the firewall will masquerade this service on behalf of the client. This option is only meaningful with the ACCEPT or ACCOUNT action.

With the ACCOUNT action it properly account for masqueraded traffic. That is to say that if you want to accept masqueraded telnet and want to turn on accounting for this service, you should also use the masq option to the ACCOUNT action. (Or simply use the account option).

--log or --nolog

This option turn on or off packet header logging for this service. Default to log for DENY or REJECT action and nolog for ACCEPT and ACCOUNT.

--copy or --nocopy

This option turn on or off packet copying to the /dev/fwmonitor device for reading by a user space program.

--account

This adds an ACCOUNT rule for this service with the exact same options.

--mark

Marks the packet with the specified integer.

--name

Sets the accounting name for this rule. This is easier to read than the unique name generated internally.

--portfw [local_ip]

The service will be interpreted as being redirected from a local address to another host on a network attached to one of the firewall interface. The optional argument is one of the IP of a defined interface. If the local_ip from which the service will redirected is unspecified, the one attached to the incoming interface will be used.

When using portfw, the dst parameter can only contains hosts and all src must be compatible with the local_ip.

ACCOUNTING

Accounting data is dump to the file /var/log/fwctl_acct. You should run periodically the fwctl program to dump the accumulated accounted data.

The format of the file is:

timestamp chain packets bytes name

timestamp

chain

The unique internal name identifying this chain. (If you want to know, it is acct plus four digit number starting from 0 and incremented for each ACCOUNT chain added.)

If you need to translate this anything meaningful, please use the name option.

packets

The number of packets related to that service.

bytes

The number of bytes relating to that service.

name

The value of the name option.

BUGS AND LIMITATIONS

Please report bugs, suggestions, patches and thanks to <francis.lacoste@iNsu.COM>.

This package is probably useless if you have something a topology that cannot be described adequatly in a simple static routing scheme.

Documentation on writing services is lacking. But see the standard services for details.

AUTHOR

Francis J. Lacoste <francis.lacoste@iNsu.COM>

COPYRIGHT

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, you can get one at http://www.gnu.org/copyleft/gpl.html

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)