Sanewall configuration: sanewall.conf

5
sanewall.conf

sanewall.conf

Sanewall configuration file

## Description

`/etc/sanewall/sanewall.conf` is the default configuration file for sanewall. 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 helpconf-version 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 def-interface for full details.

A configuration file contains one 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 def-router for full details.

It is simple to add extra service definitions which can then be used in the same way as those provided as standard. See 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 sanewall-variables may be set up and used outside of any definition as can the functions in sanewall-config-helpers and sanewall-helpers.

## Variables Available

The following variables are made available in the Sanewall 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 3330.

  You can override the default values by creating a file called `/etc/sanewall/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/sanewall/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 3330.

  You can override the default values by creating a file called `/etc/sanewall/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"

`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 sanewall-variables).

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 `SANEWALL_NAT` is non-zero (see sanewall-variables).

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), Sanewall 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 `sanewall` executable.

When adding a service which uses modules, or via a custom function, you may also wish to include the following:

    ALL_SHOULD_ALSO_RUN="${ALL_SHOULD_ALSO_RUN} myservice"

which will ensure your service is set-up correctly as part of the `all` service.

To allow definitions to be shared you can instead create files and install them in the `/etc/sanewall/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. 213 refers to a FireHOL version and is retained for compatibility.

Sanewall will refuse to run if the API version does not match the expected one. The minor number is ignored.

At version 1:213, the API and therefore service definitions are compatible with FireHOL.

## Definitions

- def-interface
- def-router

## Subcommands

- cmd-policy
- cmd-protection
- cmd-server
- cmd-client
- cmd-group

## Helper Commands

These helpers can be used in `interface` and `router` definitions as well as before them.

- helpcmd-iptables
- helpcmd-masquerade

This helper can be used in `router` definitions as well as before any `router` or `interface`.

- helpcmd-tcpmss

## Configuration Helper Commands

These helpers should only be used outside of `interface` and `router` definitions (i.e. before the first interface is defined).

- helpconf-version
- helpconf-action
- helpconf-blacklist
- helpconf-classify
- helpconf-connmark
- helpconf-dscp
- helpconf-mac
- helpconf-mark
- helpconf-nat
- helpconf-proxy
- helpconf-tos
- helpconf-tosfix

## See Also

- sanewall
- sanewall-variables
- ref-services
- ref-actions
- Sanewall Manual: sanewall-manual.pdf
- Sanewall Online Documentation