Alpine Wall User's Guide

From Alpine Linux
Revision as of 13:04, 17 October 2012 by Kunkku (talk | contribs) (Filters Rules)
Jump to: navigation, search

Configuration File Processing

Alpine Wall (awall) reads its configuration from multiple JSON-formatted files, called policy files. The processing starts from directory /usr/share/awall/mandatory, which contains mandatory policy files shipped with APK packages. After that, installation-specific policy files in /etc/awall are processed.

The latter directory may also contain symbolic links to policy files located in /usr/share/awall/optional. These are optional policies, which can be enabled on need basis. Such symbolic links are easily created and destroyed using the awall enable and awall disable commands. awall list shows which optional policies are enabled and disabled. The command also prints the description of the optional policy if defined in the file using a top-level attribute named description.

Sometimes a policy file depends on other policy files. In this case, the policy file must have a top-level attribute import, the value of which is a list of policy names, which correspond to the file names without the .json suffix. By default, the policies listed there are processed before the importing policy.

The order of the generated iptables rules generally reflects the processing order of their corresponding awall policies. The processing order of policies can be adjusted by defining top-level attributes after and before in policy files. These attributes are lists of policies, after or before which the declaring policy shall be processed. Putting a policy name to either of these lists does not by itself import the policy. The ordering directives are ignored with respect to those policies that are not enabled by the user or imported by other policies. If not defined, after is assumed to be equal to the import definition of the policy.

As the import directive does not require the path name to be specified, awall expects policies to have unique names, even if located in different directories. It is allowed to import optional policies that are not explicitly enabled by the user. Such policies show up with the required status in the output of awall list.

List Parameters

Several awall parameters are defined as lists of values. In order to facilitate manual editing of policy files, awall also accepts single values in place of lists. Such values are semantically equivalent to lists containing one element.

Variable Expansion

Awall allows variable definitions in policy files. The top-level attribute variable is a dictionary containing the definitions. The value of a variable can be of any type (string, integer, list, or dictionary).

A variable is referenced in policy files by a string which equals the variable name prepended with the $ character. If the value of the variable is a string, the reference can be embedded into a longer string in order to substitute some part of that string (in shell style). Variable references can be used when defining other variables, as long as the definitions are not circular.

Policy files can reference variables defined in other policy files. Policy files can also override variables defined elsewhere by redefining them. In this case, the new definition affects all policy files, also those processed before the overriding policy. Awall variables are in fact simple macros, since each variable remains constant thoughout a single processing round. If multiple files define the same variable, the definition in the file processed last takes effect.

If defined as an empty string, all non-embedded references to a variable evaluate as if the attribute in question was not present in the configuration. This is also the case when a string containing embedded variable references finally evaluates to an empty string.

Configuration Objects

Configuration objects can be divided into two main types. Auxiliary objects model high-level concepts such as services and zones. Rule objects translate into one or more iptables rules, and are often defined with the help of some auxiliary objects.


A service represents a set of network protocols. A top-level attribute service is a dictionary that maps service names to service definition objects, or lists thereof in more complex cases.

A service definition object contains an attribute named proto, which corresponds to the --protocol option of iptables. The protocol can be defined as a numerical value or string as defined in /etc/protocols. If the protocol is tcp or udp, the scope of the service definition may be constrained by defining an attribute named port, which is a list of TCP or UDP port numbers or ranges thereof, separated by the - character. If the protocol is icmp or icmpv6, an analogous icmp-type attribute may be used. In addition, the scope of the rule is also automatically limited to IPv4 or IPv6, respectively.


A zone represents a set of network hosts. A top-level attribute zone is a dictionary that maps zone names to zone objects. A zone object has an attribute named iface, addr, or both. iface is a list of network interfaces and addr is a list of IPv4/IPv6 host and network addresses (CIDR notation). addr may also contain domain names, which are expanded to IP addresses using DNS resolution. If not defined, addr defaults to the entire address space and iface to all interfaces. An empty zone can be defined by setting either addr or iface to an empty list.

Rule objects contain two attributes, in and out, which are lists of zone names. These attributes control whether a packet matches the rule or not. If a particular zone is referenced by the in attribute, the rule applies to packets whose ingress interface and source address are covered by the zone definition. Correspondingly, if a zone is referenced by the out attribute, the rule applies to packets whose egress interface and destination address are included in the zone. If both in and out are defined, the packet must fulfill both criteria in order to match the rule.

The firewall host itself can be referred to using the special value _fw as the zone name.

By default, awall does not generate iptables rules with identical ingress and egress interfaces. This behavior can be changed per zone by setting the optional route-back attribute of the zone to true. Note that this attribute can have an effect also in the case where in and out attributes of a rule are not equal but their definitions overlap. In this case, the route-back attribute of the out zone determines the behavior.

Logging Classes

A logging class specifies how packets matching certain rules are logged. A top-level attribute log is a dictionary that maps logging class names to setting objects.

A setting object may have an attribute named mode, which specifies which logging facility to use. Allowed values are log, nflog, and ulog. The default is log, i.e. in-kernel logging. The object may also have a limit attribute, which is an integer specifying the maximum number of matching packets to be logged per second per rule. Optionally, the log entries are prefixed with a string configured using the prefix attribute.

Filter and policy rules can have an attribute named log. If it is a string, it is interpreted as a reference to a logging class, and logging is performed according to the definitions. If the value of the log attribute is true (boolean), logging is done using default settings. If the value is false (boolean), logging is disabled for the rule. If log is not defined, logging is done using the default settings except for accept rules, for which logging is omitted.

Default logging settings can be set by defining a logging class named _default. Normally, default logging uses the log mode with packets limited to one per second.


There are six types of rule objects:

  • Filters rules
  • Policies rules
  • NAT rules
  • Packet Marking rules
  • MSS Clamping rules
  • Connection Tracking Bypass rules

All rule objects can have the in and out attributes referring to zones as described in the previous section. In addition, the scope of the rule can be further constrained with the following attributes:

Attribute Value format Effect
src Similar to addr attribute of zone objects Packet's source address matches the value
dest Similar to addr attribute of zone objects Packet's destination address matches the value
ipset Object containing two attributes: name referring to an IP set and args, which is a list of strings in and out Packet matches the IP set referred here when the match arguments are taken from the source (in) and destination (out) address or port in the order specified by args
ipsec in or out IPsec decapsulation perfomed on ingress (in) or encapsulation performed on egress (out)

Rule objects are declared in type-specific top-level dictionaries in awall policy files. If a packet matches multiple rules, the one appearing earlier in the list takes precedence. If the matching rules are defined in different policy files, the one that was processed earlier takes precedence in the current implementation, but this may change in future versions.

Filters Rules

Filter objects specify an action for packets fulfilling certain criteria. The top-level attribute filter is a list of filter objects. The precedence rules are similar to those of policy objects.

In addition to the common rule attributes, filter objects can have a service attribute constraining the scope to specific services only. This attribute is a list of service names, referring to the keys of the top-level service dictionary.

Filter objects must have an attribute named action, the value of which can be one of the following:

Value Action
accept Accept the packet
reject Reject the packet with an ICMP error message
drop Silently drop the packet
tarpit Put incoming TCP connections into persist state and ignore attempts to close them. Silently drop non-TCP packets. (Connection tracking bypass is automatically enabled for the matching packets.)

Filter objects, the action of which is accept, may also contain limits for packet flow or new connections. These are specified with the flow-limit and conn-limit attributes, respectively. The values of these attributes are limit objects that have two attributes: count and interval. count specifies how many new connections or packets are allowed within the time frame specified by interval (in seconds). The drop action is applied to the packets exceeding the limit.

Filter objects may have an attribute named dnat, the value of which is an IPv4 address. If defined, this enables destination NAT for all IPv4 packets matching the rule, such that the specified address replaces the original destination address. This option has no effect on IPv6 packets.

Filter objects may have a boolean attribute named no-track. If set to true, connection tracking is bypassed for the matching packets. In addition, if action is set to accept, the corresponding packets travelling to the reverse direction are also allowed.

Policies Rules

Policy objects describe the default action for packets that did not match any filter. The top-level attribute policy is a list of policy objects.

Policy objects must have the action attribute defined. The possible values and their semantics are the same as in filter objects.

NAT Rules

NAT rules come in two flavors: source NAT rules and destination NAT rules. These are contained in two top-level lists named snat and dnat, respectively.

Each NAT rule may have an attribute named to-addr that specifies the IPv4 address range to which the original source or destination address is mapped. The value can be a single IPv4 address or a range specified by two addresses, separated with the - character. If not defined, it defaults to the primary address of the ingress interface in case of destination NAT, or that of the egress interface in case of source NAT.

Optionally, a NAT rule can specify the TCP and UDP port range to which the original source or destination port is mapped. The attribute is named to-port, and the value can be a single port number or a range specified by two numbers, separated with the - character. If to-port is not specified, the original port number is kept intact.

Like filters, NAT rules can have a service attribute constraining their scope to specific services.

NAT rules may have an action attribute set to value accept. In this case, NAT is not performed on the packets reaching and matching this rule.

Packet Marking Rules

Packet marking rules are used to mark incoming packets matching the specified criteria. The mark can be used as a basis for the routing decision. Each marking rule must specify the mark using the mark attribute, which is a 32-bit integer.

Normal marking rules are contained by the top-level list attribute named mark.

There is another top-level list attribute, named route-track, which contains route tracking rules. These are special marking rules which cause all the subsequent packets related to the same connection to be marked according to the rule.

MSS Clamping Rules

MSS Clamping Rules are used to deal with ISPs that block ICMP Fragmentation Needed or ICMPv6 Packet Too Big packets. An MSS clamping rule overwrites the MSS option with a value specified with the mss attribute for the matching TCP connections. If mss is not specified, a suitable value is automatically determined from the path MTU.

Connection Tracking Bypass Rules

Connection tracking bypass rules are used to disable connection tracking for packets matching the specified criteria. The top-level attribute no-track is a list of such rules.

Connection tracking bypass rules may have an action attribute set to value accept. The effect is similar to corresponding NAT rules, i.e. connection tracking is not bypassed for the matching packets.

IP Sets

Any IP set referenced by rule objects should be created by awall. Auxiliary IP set objects are used to defined them in awall policy files. The top-level attribute ipset is a dictionary, the keys of which are IP set names. The values are IP set objects, which have two mandatory attributes. The attribute named type corresponds to the type argument of the ipset create command. family specifies whether the set is for IPv4 or IPv6 addresses, and the possible values are inet and inet6, correspondingly.

Command Line Syntax

Translating Policy Files to Firewall Configuration Files

awall translate [-o|--output DIRECTORY] [-V|--verify]

The --verify option makes awall verify the configuration using the test mode of iptables-restore before overwriting the old files.

Specifying the output directory allows testing awall policies without overwriting the current iptables and ipset configuration files. By default, awall generates the configuration to /etc/iptables and /etc/ipset.d, which are read by the init scripts.

Run-Time Configuration of Firewall

awall activate [-f|--force]

This command genereates firewall configuration from the policy files and enables it. If the user confirms the new configuration by hitting the Return key within 10 seconds or the --force option is used, the configuration is saved to the files. Otherwise, the old configuration is restored.

There is also a command for deleting all firewall rules:

awall flush

This command configures the firewall to drop all packets.

Optional Policies

Optional policies can be enabled or disabled using this command:

awall {enable|disable} POLICY...

Optional policies can be listed using this command:

awall list

The enabled status means that the policy has been enabled by the user. The disabled status means that the policy is not in use. The required status means that the policy has not been enabled by the user but is in use because it is required by another policy which is in use.

Debugging Policies

This command can be used to dump variable, zone, and other definitions as well as their source policies:

awall dump [LEVEL]

The level is an integer in range 0–5 and defaults to 0. More information is displayed on higher levels.