|
|
| (61 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| == Configuration File Processing ==
| | {{Delete|All wikilinks on the entire wiki have already been changed to point to the awall guide on git. Nothing points to this article, nor should it}} |
|
| |
|
| [[Alpine Wall]] (awall) reads its configuration from multiple
| | The current Alpine Wall User's Guide is available [https://git.alpinelinux.org/awall/about/ here]. |
| JSON-formatted files, called ''policy files''. The processing starts
| |
| from directory <tt>/usr/share/awall/mandatory</tt>, which contains
| |
| mandatory policy files shipped with APK packages. After that,
| |
| installation-specific policy files in <tt>/etc/awall</tt> are
| |
| processed.
| |
| | |
| The latter directory may also contain symbolic links to policy files
| |
| located in <tt>/usr/share/awall/optional</tt>. These are optional
| |
| policies, which can be enabled on need basis. Such symbolic links are
| |
| easily created and destroyed using the <tt>awall enable</tt> and
| |
| <tt>awall disable</tt> commands. <tt>awall list</tt> 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 <tt>.json</tt> 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 <tt>required</tt> status in the output of <tt>awall
| |
| list</tt>.
| |
| | |
| == 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 <tt>--protocol</tt> option of iptables. The
| |
| protocol can be defined as a numerical value or string as defined in
| |
| <tt>/etc/protocols</tt>. 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.
| |
| | |
| 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 three types of rule objects: ''policies'', ''filters'', and
| |
| ''NAT 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'''
| |
| |List of IP set names
| |
| |Packet matches at least one IP set listed here
| |
| |-
| |
| |'''ipsec'''
| |
| |'''in''' or '''out'''
| |
| |IPsec decapsulation perfomed on ingress ('''in''') or encapsulation performed on egress ('''out''')
| |
| |}
| |
| | |
| Rule objects also 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
| |
| |}
| |
| | |
| 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 files do not have other attributes than those
| |
| listed above.
| |
| | |
| If a packet matches multiple policies, the one appearing earlier in
| |
| the list takes precedence. If the matching policies are in defined by
| |
| different policy files, the one that was processed earlier takes
| |
| precedence.
| |
| | |
| ==== 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 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.
| |
| | |
| ==== NAT Rules ====
| |
| | |
| === IP Sets ===
| |
| | |
| == Command Line Syntax ==
| |
| | |
| === Generating iptables and ipset Files ===
| |
| | |
| === Activating New Configuration ===
| |
| | |
| === Optional Policies ===
| |
