Adding Services

If you intend to use a definition only once, you can consider using the custom service.

This Wikipedia list of ports and this list of port names and numbers may be useful when defining your own services.

Simple Service

To define new services you add the appropriate entries before using them later in the configuration file.

For example, consider a service named “daftnet” that listens at two ports, port 1234 TCP and 1234 UDP where the expected client ports are the default ports a system may choose plus the same port numbers the server listens at, with further dynamic ports for which we have some kernel modules which will do the tracking:

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

Even though multiple ports are used in both directions, this is still a simple service. FireHOL determines all of the combinations of client and server ports and generates multiple iptables statements to match them.

Required entries

The following are required for all simple services:

server_myservice_ports="proto/sports"
client_myservice_ports="cports"

myservice is the name we will give our service.

proto is anything that iptables accepts as a protocol e.g. “tcp”, “udp”, “icmp” and 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) the default client ports resolve 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) the default client ports resolve to the variable DEFAULT_CLIENT_PORTS. For more information see Control Variables in the manual.

Optional entries

The following entries are optional. They are only needed if a kernel module must be loaded to help track connections (typically because the protocol uses dynamic ports):

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).

Complex Service

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 script.

Adding your service to “all”

When adding a service with a custom function or which uses modules, 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. There is no need to do this with simple services which do not load modules.

Creating your service in a separate file

To allow definitions to be shared you can 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.