Alpine Linux - User contributions [en]

Alpine Wall User's Guide

2012-09-13T22:33:39Z

Jiufpt: /* Rules */

== Configuration File Processing ==

[[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
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. 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 <tt>.json</tt> suffix. By default, the policies
listed there are processed before the importing policy.

The order of the generated iptables rules generally reflects the
processing order of their corresponding awall policies. The processing
order of policies can be adjusted by defining top-level attributes
'''after''' and '''before''' in policy files. These attributes are
lists of policies, after or before which the declaring policy shall be
processed. Putting a policy name to either of these lists does not by
itself import the policy. The ordering directives are ignored with
respect to those policies that are not enabled by the user or imported
by other policies. If not defined, '''after''' is assumed to be equal
to the '''import''' definition of the policy.

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
or ranges thereof, separated by the '''-''' character. 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.

The firewall host itself can be referred to using the special value
'''_fw''' as the zone name.

=== Logging Classes ===

A ''logging class'' specifies how packets matching certain rules are
logged. A top-level attribute '''log''' is a dictionary that maps
logging class names to setting objects.

A setting object may have an attribute named '''mode''', which
specifies which logging facility to use. Allowed values are '''log''',
'''nflog''', and '''ulog'''. The default is '''log''', i.e. in-kernel
logging. The object may also have a '''limit''' attribute, which is an
integer specifying the maximum number of matching packets to be logged
per second per rule. Optionally, the log entries are prefixed with a
string configured using the '''prefix''' attribute.

Filter and policy rules can have an attribute named '''log'''. If it
is a string, it is interpreted as a reference to a logging class, and
logging is performed according to the definitions. If the value of the
'''log''' attribute is '''true''' (boolean), logging is done using
default settings. If the value is '''false''' (boolean), logging is
disabled for the rule. If '''log''' is not defined, logging is done
using the default settings except for accept rules, for which logging
is omitted.

Default logging settings can be set by defining a logging class named
'''_default'''. Normally, default logging uses the '''log''' mode with
packets limited to one per second.

=== Rules ===

There are six types of rule objects:
* Filters rules
* Policies rules
* NAT rules
* Packet Marking rules
* MSS Clamping rules
* 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 Rules ====

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
|-
|'''tarpit'''
|Put incoming TCP connections into persist state and ignore attempts to close them. Silently drop non-TCP packets. (Connection tracking bypass is automatically enabled for the matching packets.)
|}

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.

Filter objects may have a boolean attribute named '''no-track'''. If
set to '''true''', connection tracking is bypassed for the matching
packets. In addition, if '''action''' is set to '''accept''', the
corresponding packets travelling to the reverse direction are also
allowed.

==== Policies Rules ====

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 may have an attribute named '''to-addr''' that
specifies the IPv4 address range to which the original source or
destination address is mapped. The value can be a single IPv4 address
or a range specified by two addresses, separated with the '''-'''
character. If not defined, it defaults to the primary address of the
ingress interface in case of destination NAT, or that of the egress
interface in case of source NAT.

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

==== Packet Marking Rules ====

Packet marking rules are used to mark incoming packets matching the
specified criteria. The mark can be used as a basis for the routing
decision. Each marking rule must specify the mark using the '''mark'''
attribute, which is a 32-bit integer.

Normal marking rules are contained by the top-level list attribute
named '''mark'''.

There is another top-level list attribute, named '''route-track''',
which contains route tracking rules. These are special marking rules
which cause all the subsequent packets related to the same connection
to be marked according to the rule.

==== MSS Clamping Rules ====

MSS Clamping Rules are used to deal with ISPs that block ICMP
Fragmentation Needed or ICMPv6 Packet Too Big packets. An MSS clamping
rule overwrites the MSS option with a value specified with the
'''mss''' attribute for the matching TCP connections. If '''mss''' is
not specified, a suitable value is automatically determined from the
path MTU.

==== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, 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 <tt>--force</tt> 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–5 and defaults to 0. More
information is displayed on higher levels.

[[Category:Networking]]
[[Category:Security]]

Alpine Wall User's Guide

2012-05-16T18:59:15Z

Jiufpt: /* Translating Policy Files to Firewall Configuration Files */

== Configuration File Processing ==

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

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 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 do not have other attributes than those
common to all rule 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.

=== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, which are read by the init scripts.

=== Run-Time Activation of New Firewall Configuration ===

'''awall activate'''

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, the configuration is saved to the
files. Otherwise, the old configuration is restored.

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

[[Category:Networking]]

Alpine Wall User's Guide

2012-05-16T18:58:24Z

Jiufpt: /* IP Sets */

== Configuration File Processing ==

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

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 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 do not have other attributes than those
common to all rule 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.

=== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, which are read by the init scripts.

=== Run-Time Activation of New Firewall Configuration ===

'''awall activate'''

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, the configuration is saved to the
files. Otherwise, the old configuration is restored.

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

[[Category:Networking]]

Alpine Wall User's Guide

2012-05-16T18:56:24Z

Jiufpt: /* Filters */

== Configuration File Processing ==

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

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 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 do not have other attributes than those
common to all rule 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.

=== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, which are read by the init scripts.

=== Run-Time Activation of New Firewall Configuration ===

'''awall activate'''

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, the configuration is saved to the
files. Otherwise, the old configuration is restored.

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

[[Category:Networking]]

Alpine Wall User's Guide

2012-05-16T18:54:24Z

Jiufpt: /* Rules */

== Configuration File Processing ==

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

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 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 do not have other attributes than those
common to all rule 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.

=== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, which are read by the init scripts.

=== Run-Time Activation of New Firewall Configuration ===

'''awall activate'''

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, the configuration is saved to the
files. Otherwise, the old configuration is restored.

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

[[Category:Networking]]

Alpine Wall User's Guide

2012-05-16T18:53:33Z

Jiufpt: /* Zones */

== Configuration File Processing ==

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

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 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 do not have other attributes than those
common to all rule 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.

=== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, which are read by the init scripts.

=== Run-Time Activation of New Firewall Configuration ===

'''awall activate'''

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, the configuration is saved to the
files. Otherwise, the old configuration is restored.

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

[[Category:Networking]]

Alpine Wall User's Guide

2012-05-16T18:49:55Z

Jiufpt: /* Zones */

== Configuration File Processing ==

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

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 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 do not have other attributes than those
common to all rule 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.

=== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, which are read by the init scripts.

=== Run-Time Activation of New Firewall Configuration ===

'''awall activate'''

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, the configuration is saved to the
files. Otherwise, the old configuration is restored.

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

[[Category:Networking]]

Alpine Wall User's Guide

2012-05-16T18:49:24Z

Jiufpt: /* Services */

== Configuration File Processing ==

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

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 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 do not have other attributes than those
common to all rule 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.

=== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, which are read by the init scripts.

=== Run-Time Activation of New Firewall Configuration ===

'''awall activate'''

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, the configuration is saved to the
files. Otherwise, the old configuration is restored.

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

[[Category:Networking]]

Alpine Wall User's Guide

2012-05-16T18:48:10Z

Jiufpt: /* Configuration File Processing */

== Configuration File Processing ==

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

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 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 do not have other attributes than those
common to all rule 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.

=== 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 <tt>ipset create</tt>
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 <tt>--verify</tt> 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 <tt>/etc/iptables</tt>
and <tt>/etc/ipset.d</tt>, which are read by the init scripts.

=== Run-Time Activation of New Firewall Configuration ===

'''awall activate'''

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, the configuration is saved to the
files. Otherwise, the old configuration is restored.

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

[[Category:Networking]]

Alpine Wall

2012-05-16T18:41:39Z

Jiufpt: /* Implementation Considerations */

This page is a design and implementation plan for a new firewall
management framework. The new framework addresses the limitations
of Shorewall, which is probably the most common solution used
with Alpine.

== Proposal ==

We evaluated serveral existing open source projects, none of which
satisfied our demanding taste. The existing solutions are either too
tied to specific (router) distributions, targeted to home users (with
too many assumptions built-in), or depedent on bloated frameworks
(usually Perl). Moreover, we would like to keep management of firewall
settings and activation of such settings as two separate workflows,
which would facilitate centralized management of firewall rules.

As no readily available solution was found, the proposal is to
implement a new management framework for <code>iptables</code>, which
would integrate with the
[[Alpine Configuration Framework Design|Alpine Configuration
Framework]]
(ACF). The framework is hereafter referred to as the Alpine Wall
(awall).

== Design ==

Awall would consist of three major components: data model, front-end,
and back-end. It also implements a plug-in architecture, which allows
extending the data model and functionality, in order to simplify
common organization-specific administrative tasks.

The '''data model''' would describe the firewall configuration using
concepts and terminology that is roughly compatible with Shorewall. It
would also borrow some useful concepts from other firewall solutions
we evaluated, such as the Service concept as defined in the
[http://www.turtlefirewall.com/manual-en/x161.html Turtle Firewall]
(but generalized a bit). Awall plug-ins can contain schema extension
modules augmenting the basic model provided by the framework.

The '''back-end''' is responsible for translating the model's data
into configuration files, most notably the files that can be read by
<code>iptables-restore</code> and
<code>ip6tables-restore</code>. Moreover, it can produce files into
e.g. <code>/etc/modprobe.d</code> and <code>/etc/sysctl.d</code> if
necessary. When a plug-in extends the data model, it must also provide
a back-end module that interprets model extension and translates the
data into <code>iptables</code> and other rules. The framework
includes a module for interpreting the base model. The framework is
responsible for ordering and aggregating the results produced by all
modules into actual configuration files.

The '''front-end''' is essentially an ACF module which allows editing
the data model and activating the changes with the help of the
back-end. The front-end implements also a fallback mechanism that
prevents the operator from locking himself out by a faulty
configuration. The configuration data is stored in text files which
can be directly edited. The front-end provides a command line tool for
validating and activating the configuration after manual changes.

== Base Model ==

The basic data model could roughly look like as follows:

;Zone
; <code>interface*, subnet*</code>
;Service
; <code>(protocol, port*)+</code>
;Forwarding policy
; <code>Zone:in*, Zone:out*, accept/reject/drop, masq_on/masq_off</code>
;Filtering rule
; <code>Zone:in*, Zone:out*, Service+, accept/reject/drop, conn_limit?, flow_limit?</code>
;NAT rule
; <code>snat/dnat, Zone:in*, Zone:out*, Service, ip4_range, port_range?</code>

Subnets in zone definitions can be declared using IPv4/IPv6 addresses
(CIDR notation), domain names, or as references to
[http://ipset.netfilter.org/ipset.man.html ipsets]. A domain name can
resolve to one or more IP addresses. The referred ipsets may be
managed manually or by some other tool.

If a packet with source address ''a'' arrives on interface ''i'', it
is considered to originate from zone ''Z = (I, S)'' (where ''I'' is
the set of interfaces and ''S'' is the set of subnets) if and only if
''I'' includes ''i'', and ''a'' belongs to any subnet of ''S''. In
zone definitions, ''I'' would default to the set of all interfaces and
''S'' to {0.0.0.0/0, ::}. The destination zone would be defined in a
similar way based on the packet's destination address and interface.

== Implementation Considerations ==

The data model should preferably be based on some existing format,
such as JSON, XML, or YAML. In order to allow extensions to the data
model, awall must define some kind of schema language. This language
would embed the necessary information the front-end needs to
automatically generate a user interface for the extension. For
example, the help texts shown to the user would be placed in the
schema modules.

Ideally, the base model would be described using the very same
language as the model extensions, but it would impose quite demanding
requirements on the language, e.g. support for complex data types. If
we select this approach and model the data using XML, we could use XML
Schema as the basis. There is also an (expired) Internet Draft on
[http://tools.ietf.org/html/draft-zyp-json-schema-03 JSON Schema], but
there seems to be no existing validator implementation in C or Lua.

Even though elegant from architecture point of view, it is unlikely
that support for complex data types would be required by typical
extensions. In most cases, a set of global variables of primitive
types would suffice. Therefore, we could just use a very simple
language for declaring such variables or implement support for a
limited subset of some well-known schema language. In this
alternative, the base model would not be described using this language
but rather hard-coded into the front-end.

The back-end modules are responsible for translating the configuration
data into configuration file fragments. As regards their
implementation, we have two alternatives. The first alternative is to
implement them as Lua functions invoked by the framework in a defined
way. The framework would provide a library that allows the said
functions to access the data model, and also otherwise assists in
their implementation. The functions would report the results back to
the framework, which finally would translate them into target files.

In the second alternative, the back-end modules would be implemented
using a template language rather than a general-purpose programming
language. An example of a firewall-related template language is
[http://ferm.foo-projects.org/download/2.1/ferm.html ferm], which
unfortunately is implemented in Perl. Ferm also lacks certain
capabilities required to implement e.g. the Zone and Service concepts
conveniently. However, we could introduce a new template language that
would better suit our purposes. Such a language would eliminate some
redundancy from the back-end modules which necessarily comes with the
use of a general-purpose language. On the other hand, developing and
maintaining such a language would take effort and might make the
framework initially more difficult to use.

The back-end will contain functionality for domain name resolution. In
the data model, hosts of groups thereof can be identified by their
domain names. The back-end will resolve these to IP addresses, which
will be stored in the target files, so there will be no need to
resolve anything when activating the configuration during boot.

[[Category:Networking]] [[Category:Development]]

Alpine Wall

2012-05-16T18:40:18Z

Jiufpt: /* Base Model */