NethServer can work into two basic modes:

  • server mode: the system will be a standard host inside the network offering services like e-mail or file server.
  • gateway mode: the system is the gateway and firewall of the local network

The system has an abstraction layer for firewall base functions, like opening ports for running services. Actually two implementations are available:

  • server mode: standard lokkit (default on CentOS)
  • gateway mode: advanced Shorewall configuration

The gateway functionality is built around three modules:

  • nethserver-base: high-level abstraction of the firewall
  • nethserver-firewall-base: Shorewall-based implementation
  • nethserver-lsm: link status monitor for multi-wan configurations

Roles and zones

Each network interface has a role which maps to a firewall zone. The firewall has the following built-in zones, ordered from the most to the least privileged:

  • green: local network, it’s considered almost trusted. Hosts in this network can access any other zone. Hosts connected via VPN can be considered in green zone.
  • blue: guest network. Hosts in this network can access orange and red zones, can’t access green zone
  • orange: DMZ network. Hosts in this network can access red zone, can’t access green and blue zones
  • red: external/internet networks. Hosts in this network can access only firewall zone
  • a: (not implemented yet) traffic from/to this zone must be explicitly allowed

There is also a special firewall zone which represents the firewall itself. The firewall can access any other zone.

Each network interface with a configured role is a firewall zone. Roles are mapped to Shorewall zone as:

  • green -> loc
  • red -> net
  • blue -> blue
  • orange -> orang (in Shorewall, a zone name can’t be longer than 5 chars)
  • firewall -> FW

Custom zone names are directly mapped to Shorewall respecting the limit of 5 chars.

Red interfaces can be configured with static IP address or using DHCP. All other interfaces can be configured only with static IP addresses.

General configuration

Properties of firewall key inside configuration db:

  • event: event to call when firewall-adjust event is fired
  • tc: traffic shape mode (see below)
  • ExternalPing: if enabled, allow ping responses on external interface
  • WanMode: multi-wan mode. Default is balance, can be:
    • balance: traffic is balanced among red interfaces in weighted mode
    • backup: traffic is routed via wan interface with maximum weight, all other interfaces are used as fallback
  • nfq: if enabled, traffic from external networks will be passed to NFQ and scanned with Snort. See ips.
  • Policy: can be permissive or strict. See above.
  • MACValidation: if enabled, the firewall will check the traffic against a list of known MAC addresses (see: IP/MAC binding)
  • MACValidationPolicy: can be accept or drop. Default is drop. See man shorewall.conf for all valid values
  • InterfaceRoleList: list of network interface roles configurable from web interface. Default is: green,red,blue,orange
  • CheckIP: comma-separeted list of IP monitored by LSM, to check if a provider is up or down
  • MaxNumberPacketLoss: number of maximum consecutive packets lost, over this threshold the provider is considered down
  • MaxPercentPacketLoss: percentage of maximum packet lost, over this threshold the provider is considered down
  • PingInterval: seconds between ICMP packets sent by LSM, default is 5
  • NotifyWan: can be enabled or disabled, if enabled a mail is sent every time a provider changes its own state
  • NotifyWanFrom: sender address for mails sent if NotifyWAN is set to enabled
  • NotifyWanTo: recipient address for mails sent if NotifyWAN is set to enabled




The main event for firewall configuration is firewall-adjust. The event contains a single action which fires the event named in the property event inside the firewall key into the configuration database.

Other events:

  • lokkit-save: base firewall implementation using lokkit
  • nethserver-firewall-base-save: firewall implementation using Shorewall
  • wan-uplink-update: fired when the status of an external interface changes

The wan-uplink-event event takes at least two parameters:

  • provider name: name of the provider involved
  • action: can be up or down, describing the new provider status


signal-event wan-uplink-update down myisp


For every network packet traveling between firewall zones, the system will evaluate a list of rules to allow/block the specific traffic. Policies are default firewall rules which will be applied only if no other rule matches the ongoing traffic.

Firewall implements two standard policies:

  • Permissive: will enable all traffic from green (loc) zone to red (net) zone.
  • Strict: will block all traffic from green (loc) zone to red (net) zone. Permitted traffic should be explicitly allowed.

The firewall configures 4 default zones with built-in policies (see above). In the schema below, traffic is permitted from left to right and blocked from right to left:


To override a policy, you should create a firewall rule between zones.

IP/MAC binding

When MACValidation option is enabled, the firewall analyzes all the traffic based on a well-known list of IPs associated to MAC addresses. If the host generating the traffic is not inside the list, MACValidationPolicy will be applied. The list of IP/MAC association is created from DHCP reservations.

Thus, enabling MACValidation and leaving MACValidationPolicy set to drop, will block all traffic from hosts without a DHCP reservation.


Firewall rules can allow or deny traffic matching certain conditions. Rules are saved inside the fwrules database as records of type rule.

Each rule record has the following fields:

  • key: a unique key identifier
  • Position: integer sorting key
  • Src, Dst: {literal*|*reference} where
    • literal is an IP, a CIDR, any (any source/destination) or fw (the firewall itself)
    • reference has the form prefix;value, where prefix can be a DB type (host, host-group, zone) or the string role, value is a DB key or an interface role name (green, red…)
  • Action: can be ACCEPT, DROP or REJECT
    • ACCEPT allows the traffic
    • REJECT denies the traffic, an ICMP port unreachable packet is sent to the source address
    • DROP discards the traffic without informing the source address (the connection will timeout)
  • Service: (optional) can be a service object, a port number or a ndpi object. If a port number is used, both TCP and UDP protocols are matched.
  • Time: (optional) can be a time object, the rule will be enabled only if the time conditions is matched
  • Log: can be none or info. If value is info, all matched packets will be logged in /var/log/firewall.log. Defaults to none
  • status: can be enabled or disabled. Default is enabled
  • Description: (optional)

Example of a rule accepting traffic:


Accept all traffic from myhost to myserver for ssh service (port 22):

db fwrules set 1 rule Src "host;myhost" Dst "host;myserver" Service ssh Action ACCEPT Log none status enabled Position 8765

Drop all traffic from to on TCP and UDP port 25:

db fwrules set 2 rule Src Dst Service 22 Action DROP Log none status enabled Position 5469

Template Fragment

Rules in the firewall can be added manually by a template fragment in the folder /etc/e-smith/templates/etc/shorewall/rules

For example drop a file 40YourSpecificRule

## 40nethvoice

    my $iax = $nethvoice{'AllowExternalIAX'} || 'disabled';

    my $webrtc = $nethvoice{'AllowExternalWebRTC'} || 'disabled';

    if ($iax eq 'enabled') {

        $OUT .= "# Enable IAX from red interfaces\n";

        $OUT .= "?COMMENT Enable IAX from red interfaces\n";

        $OUT .= "ACCEPT\tnet\t\$FW\tudp\t4569,5036\n";

    if ($webrtc eq 'enabled') {

        $OUT .= "# Enable WebRTC from red interfaces\n";

        $OUT .= "?COMMENT Enable WebRTC from red interfaces\n";

        $OUT .= "ACCEPT\tnet\t\$FW\ttcp\t8089\n";

    $OUT .= "?COMMENT\n";

You can use all the settings below but you might be interested by the shorewall documentation also at

  • \t -> write a tab space (can be also written : $OUT .= "ACCEPT  net  $FW  tcp  8089\n";)
  • ACCEPT -> allows the traffic
  • REJECT -> denies the traffic, an ICMP port unreachable packet is sent to the source address
  • DROP -> discards the traffic without informing the source address (the connection will timeout)
  • REDIRECT -> redirect the traffic to another firewall zone

The target may optionally be followed by “:” and a syslog log level (e.g, REJECT:info or Web(ACCEPT):debug).

  • loc -> green (Local network)
  • net -> red (Internet network)
  • blue -> blue (Guest network)
  • orang -> orange (DMZ network)
  • $FW -> firewall
  • tcp -> tcp port (comma separated list of ports)
  • udp -> udp port (comma separated list of ports)

then you must expand your templates and restart your firewall by : signal-event firewall-adjust

Firewall objects

Firewall module uses objects to simplify rules creation. The use of objects is not mandatory but it’s strongly encouraged.

Supported objects are:

  • Host
  • Group of host
  • Service
  • CIDR
  • Ip range
  • Zone
  • Time

A host is an already defined entry inside the hosts db, or a new key of type host:


A host-group is a group of hosts inside the hosts db. Hosts in a host-group should always be reachable using the same interface. For example: a group of host inside the LAN or on the Internet. A host-group db entry can be something like:


A CIDR is a group of hosts defined as a CIDR network. It’s saved inside the hosts db:


A IP range is a group of hosts defined as a range of IP. It’s saved inside the hosts db:


A zone represents a network zone which can be associated to an interface or a set of IP address. A zone entry in networks database can be something like:


A configured network interface is automatically a zone.

A service can have a protocol and one or more ports. A service entry in fwservices database can be something like:

   Ports=port/port range

A service can also be a refence in the format ndpi;<protocol> where protocol is a supported protocol from nDPI kernel module. To see a list of supported protocols:

db NethServer::Database::Ndpi keys

A time condition is a time record entry in fwtimes database. All times are saved in local time and converted to UTC on template expansion.

Database example:

db fwtimes setprop officehours WeekDays 'Mon,Tue,Wed,Thu' TimeStart '09:00' TimeStop '18:00'

Rules based on mac address

It’s possible to create rules based on MAC address only using a template-custom. For example to block internet access to a host on local network using its MAC address:

mkdir -p /etc/e-smith/templates-custom/etc/shorewall/rules
echo "DROP      loc:~xx-xx-xx-xx-xx-xx          net" > /etc/e-smith/templates-custom/etc/shorewall/rules/90mymac

Where xx-xx-xx-xx-xx-xx is the MAC address to block.

See man shorewall-rules for more information.

Port forwarding

All port-forwards are saved inside the portforward db.

Each record has:

  • key: auto-increment id
  • type: pf
  • protocol: tcp/udp
  • src: can be a port number or a range in the form xxxx:yyyy
  • dst: can be a port number, if empty the value of src is used
  • dstHost: destination host, can be an IP address or a hos firewall object
  • allow: allowed ip address or network, see SOURCE at
  • status: enabled/disabled
  • oriDst: original destination ip, for example alias for a wan interface. If empty, the port forward is valid for all red interface
  • description: optional description

NAT 1:1

All NAT one-to-one configurations are stored in networks db.

Each value is a new attribute for an existing alias key and the name of attribute is FwObjectNat that contains the reference of an associated host:


During template-expanding phase, the associated host is mapping with referenced IP and added in shorewall nat configuration. The file is /etc/shorewall/nat.

More information are available here:

Traffic shaping

Traffic shaping is implemented using the Shorewall simple traffic shaping. See:

The feature is controlled by tc property in firewall key from configuration db. Possible values are:

  • Simple: default
  • No: disabled


The firewall needs to know how much inbound and outbound bandwidth has a red interface. The bandwidth value (expressed in kbit) is stored inside FwInBandwidth and FwOutBandwidth properties, wich are parts of the network interface record inside the networks db.



All traffic shaping rules are saved inside the fwrules database with the same format. Valid actions for traffic shaping rules are:

  • priority;high: set the priority to high (actually the value is normalized to 2 - medium)
  • priority;low: set the priority to low
  • provider;<name>: force the traffic to the provider specified by name

Assumptions and limitations

  1. All nDPI traffic is marked in forward chain. When a nDPI protocol is found, the whole connection is marked.
  2. Priority rules are in post chain and can use nDPI markers. If a priority rule uses a role (interface) as source, the rule can’t be added to postrouting chain since the packet is already natted: Shorewall will move the rule on top of forwarding chain.
  3. nDPI rules can’t block the http/https traffic if web proxy is enabled in transparent mode.
  4. All nDPI markers are read from /proc/net/xt_ndpi/proto and shifted by 8 bits.
  5. Divert rules can’t be used with nDPI, because an established TCP connection can’t be moved between providers.
  6. Prerouting table is reserved by Shorewall for handlind the multi wan scenario.

Divert rules

A divert rule is used to force traffic to a specific provider.

For example, this rules will route all traffic to port 22 via the provider named myadsl:



  • key: numeric id
  • Src: can be a ‘any’, role (execpt red), zone (not interface), host object, ip address, ip range or CIDR
  • Dst: can be a zone (not interface), host object, ip address, ip range or CIDR
  • Action: provider object, in the form of “provider;<name>”
  • Service: (optional) can be a service object
  • status: can be enabled or disabled. Default is enabled
  • Position: integer sorting key
  • Description: (optional)

A rule is ignored during template expansion if:

  • the source is red role
  • the destination is a role which is not red
  • source, destination and service are all set to any
  • the provider doesn’t exists
  • destination is set to any

Multi WAN

NethServer firewall can handle 15 red (WAN) interfaces. Implementation uses Shorewall with LSM (Link Status Monitor). The LSM daemon takes care of monitoring WAN connections (interface) using ICMP traffic and it informs Shorewall about interface up/down events. Each interface can be checked using multiple IPs (see checkip property below). At least one IP must be reachable to mark the WAN connection as usable. If no IP is specified (recommended option), the system will uses well-known default IPs (Google DNS and OpenDNS).

For each configured provider, LSM will send ping to a configured IP (checkip). When a provider status changes, the system will signal a wan-uplink-update event.

Inside the event, the action nethserver-shorewall-wan-update invokes:

  • shorewall enable <interface> when a red interface is usable
  • shorewall disable <interface> then a red interface is not usable

When an interface is disabled, all associated routes will be deleted.

When a new TCP connection is started, a route is selected and all successive packets will always be routed via same interface. If the used interfaces goes down, the connection is closed.

Actually two behaviors are implemented: balanced and active-backup.


All red interfaces are simultaneously used accordingly to the configured weight (see below).


Given a connection A with weight 2, and connection B with weight 1, the firewall will route a double number of connections via A over B.


Red interfaces are ordered using the configured weight: higher the weight, higher the route priority. The interface with maximum weight will be the active connection, all other interfaces will be used if the active one goes down.


Given 3 wan connections:

  • A with weight 3
  • B with weight 2
  • C with weight 1

All traffic is routed via A. On failure of A, all traffic is routed via B. When B goes down, C is used. Whenever A comes backup, all traffic is again routed through it.


Providers are an abstraction over red interfaces (see man shorewall-providers). All providers must have a weight which is used to select the route for packets.

A provider record inside the networks database has following properties:

  • key: name of provider
  • interface: associated red interface, it’s mandatory
  • weight: weight of connection expressed with an integer number, it’s mandatory
  • Description: (optional) custom description


  Description=my fast provider

Multi WAN example

  1. Configure two interfaces as red, for example eth1 and eth2
db networks setprop eth1 role red
db networks setprop eth2 role red
signal-event interface-update
  1. Create two providers:
db networks set firstisp provider interface eth1 weight 2
db networks set secondisp provider interface eth2 weight 1
  1. Re-configure the firewall:
signal-event firewall-adjust

See /var/log/firewall.log to check for up/down events.

Routes can be checked using:

shorewall show routing

Static routes

Static routes are saved inside the routes database with a record of type static. Example:
    Description=My route

Each record has the following properties:

  • key: network address
  • Mask: network mask
  • Router: gateway for the network
  • Description: a custom description (optional)

There is also a special type of static route called provider-static. These routes have the same properties as described above and are used to correctly route traffic for link monitor. This type of rules should never be manually edited.