Alpine Wall User's Guide
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.
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 lists of service definition objects. 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.