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. The policies listed there are
always processed before the importing policy. The order of the
generated iptables rules generally reflects the processing order of
their corresponding awall policies.

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.

Services

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

Zones

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.

Rules

There are four types of rule objects: policies, filters,
NAT rules, and 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

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

logreject

Similar to reject but with kernel logging

logdrop

Similar to drop but with kernel logging

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

Policies

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 must have an attribute named ip-range that
specifies the IPv4 address range to which the original source or
destinatinon address is mapped. The value can be a single IPv4 address
or a range specified by two addresses, separated with the -
character.

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 port-range, and the value can be a single port number or a
range specified by two numbers, separated with the -
character. If port-range 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.

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–3 and defaults to 0. More
information is displayed on higher levels.