Alpine Wall User's Guide: Difference between revisions

From Alpine Linux
(57 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Configuration File Processing ==
The current Alpine Wall User's Guide is available [http://git.alpinelinux.org/cgit/awall/about/ here].


[[Alpine Wall]] (awall) reads its configuration from multiple
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
[[Category:Networking]]
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'''
|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 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
|}
 
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 ====
 
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 a '''-'''
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
rage specified by two numbers, separated with a '''-''' character. If
'''port-range''' is not specified, the original port number is kept
intact.
 
=== IP Sets ===
 
IP sets referred 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 <tt>ipset create</tt> command. The attribute named
'''family''' specifies whether the set is for IPv4 or IPv6
addresses. The possible values are '''inet''' and '''inet6''',
correspondingly.
 
== Command Line Syntax ==
 
=== Generating iptables and ipset Files ===
 
=== Activating New Configuration ===
 
=== Optional Policies ===

Revision as of 12:22, 13 September 2019

The current Alpine Wall User's Guide is available here.