Alpine Wall User's Guide: Difference between revisions

From Alpine Linux
(Service objects explained)
No edit summary
Line 11: Line 11:
located in <tt>/usr/share/awall/optional</tt>. These are optional
located in <tt>/usr/share/awall/optional</tt>. These are optional
policies, which can be enabled on need basis. Such symbolic links are
policies, which can be enabled on need basis. Such symbolic links are
easily created and destroyed using the <tt>awall --enable</tt> and
easily created and destroyed using the <tt>awall enable</tt> and
<tt>awall --disable</tt> commands. <tt>awall --list</tt> shows which
<tt>awall disable</tt> commands. <tt>awall list</tt> shows which
optional policies are enabled and disabled.
optional policies are enabled and disabled.


Sometimes a policy file depends on other policy files. In this case,
Sometimes a policy file depends on other policy files. In this case,
the policy file must have a top-level attribute <tt>import</tt>, the
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
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
names without the <tt>.json</tt> suffix. The policies listed there are
Line 28: Line 28:
policies that are not explicitly enabled by the user. Such policies
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
show up with the <tt>required</tt> status in the output of <tt>awall
--list</tt>.
list</tt>.


== List Parameters ==
== List Parameters ==
Line 40: Line 40:


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


A variable is referenced in policy files by a string which equals the
A variable is referenced in policy files by a string which equals the
variable name prepended with the <tt>$</tt> character. If the value of
variable name prepended with the '''$''' character. If the value of
the variable is a string, the reference can be embedded into a longer
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
string in order to substitute some part of that string (in shell
Line 75: Line 75:


A ''service'' represents a set of network protocols. A top-level
A ''service'' represents a set of network protocols. A top-level
attribute <tt>service</tt> is a dictionary that maps service names to
attribute '''service''' is a dictionary that maps service names to
lists of service definition objects. A service definition object
service definition objects, or lists thereof in more complex cases.
contains an attribute named <tt>proto</tt>, 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 <tt>tcp</tt> or <tt>udp</tt>, the scope of the
A service definition object contains an attribute named '''proto''',
service definition may be constrained by defining an attribute named
which corresponds to the <tt>--protocol</tt> option of iptables. The
<tt>port</tt>, which is a list of TCP or UDP port numbers.
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.


If the protocol is <tt>icmp</tt> or <tt>icmpv6</tt>, an analogous
=== Zones ===
<tt>icmp-type</tt> 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.


=== Zones ===
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 ===
=== 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
|}
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 ====
==== 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 ====

Revision as of 02:47, 3 May 2012

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

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

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