Alpine Linux - User contributions [en]

Setting up Homer

2017-12-19T16:10:40Z

Kunkku:

This page describes how to set up [http://sipcapture.org/ HOMER] on
Alpine Linux.

The packages are available in the community repository starting from
Alpine Linux 3.6. Make sure that this repository is enabled in
<code>/etc/apk/repositories</code>.

== Primary Node ==

Install the required packages, set up the database, and enable
required services:

<pre>apk add homer-api-doc homer-ui mariadb kamailio-mysql nginx php7-fpm

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start

cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php7/php-fpm.d/homer5.conf
rc-update add php-fpm7
rc-service php-fpm7 start
</pre>

Override the default nginx configuration with the HOMER template:

<pre>: > /etc/nginx/conf.d/default.conf
cp /usr/share/doc/homer-api/examples/web/homer5.nginx /etc/nginx/conf.d/homer5.conf
</pre>

Make the following changes in
<code>/etc/nginx/conf.d/homer5.conf</code>:

{|
|root
|<code>/usr/share/webapps/homer</code>
|-
|server_name
|your server's host name
|-
|fastcgi_pass
|<code>127.0.0.1:9001</code>
|}

If you are going to deploy database nodes in addition to this primary
node, change <code>SINGLE_NODE</code> to <code>0</code> in
<code>/etc/homer/configuration.php</code>.

Set <code>HOMER_TIMEZONE</code> in
<code>/etc/homer/preferences.php</code> according to your time zone.

Enable the <code>nginx</code> service:

<pre>rc-update add nginx
rc-service nginx start
</pre>

If using a firewall, you have to allow users to access the nginx
server using HTTP. In addition, reception of the captured SIP traffic
must be allowed on UDP port 9060.

=== LDAP Authentication ===

If you intend to authenticate the HOMER users using LDAP, install the
LDAP authentication module:

<pre>apk add homer-api-ldap
</pre>

In addition, you have to allow connections to the LDAP server if using
a firewall.

==== Changes in /etc/homer/preferences.php ====

Enable LDAP authentication:
<pre>define('AUTHENTICATION',"LDAP");
</pre>

Uncomment the LDAP section and add/update parameters according to your
server configuration:

<pre>define('LDAP_HOST',"localhost");
define('LDAP_PORT',389);
define('LDAP_VERSION',3);
define('LDAP_BIND_USER',"cn=HOMER,ou=Apps,dc=example,dc=com");
define('LDAP_BIND_PASSWORD',"secret");
define('LDAP_BASEDN',"ou=Users,dc=example,dc=com");
</pre>

Add one of the following lines, depending on whether the STARTTLS
mechanism shall be used to protect the LDAP connection:

<pre>define('LDAP_ENCRYPTION',"none");
define('LDAP_ENCRYPTION',"tls");
</pre>

If TLS is used, you have to make sure that the relevant root
certificate is trusted. If using a self-signed root certificate, one
way to achieve this is to add the <code>TLS_CACERT</code> parameter to
<code>/etc/openldap/ldap.conf</code>, specifying the path to the
trusted CA certificate.

Specify the users who should have admin rights:

<pre>define('LDAP_ADMIN_USERS',"donald,mike");
</pre>

Remove the parameters starting with <code>LDAP_GROUP_</code> unless
you want to authorize users based on group membership.

==== Nested Groups with Active Directory ====

The default settings in <code>/etc/homer/preferences.php</code> are
intended for LDAP schemas conforming to
[https://tools.ietf.org/rfc/rfc2307.txt RFC 2307]. Otherwise, you may
have to modify the parameters starting with
<code>LDAP_USERNAME_ATTRIBUTE_</code>. The following example
demonstrates how to authenticate and authorize users against Microsoft
Windows Active Directory based on nested group membership:

<pre>define('LDAP_USERNAME_ATTRIBUTE_OPEN',"(&(samaccountname=");
define('LDAP_USERNAME_ATTRIBUTE_CLOSE',")(memberof:1.2.840.113556.1.4.1941:=cn=HOMER,ou=Groups,dc=example,dc=com))");
</pre>

== Database Nodes ==

To make your HOMER system more scalable, you may want to deploy
multiple database nodes. This sections instructs how to set up an
additional database node.

Install the required packages on the new database node and enable the
database service:

<pre>apk add homer-api-doc homer-db mariadb kamailio-mysql

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
</pre>

Set up the database. You may want to disable remote root logins to the
database.

<pre>mysql_secure_installation
homer_db_init -r
</pre>

You may want to change the default password for the HOMER database
user. This can be done as follows:

<pre> mysql -e "SET PASSWORD FOR 'homer_user' = PASSWORD('<password>');"
</pre>

Enable the <code>crond</code> service:

<pre>rc-update add crond
rc-service crond start
</pre>

Override the Kamailio configuration with the HOMER template:

<pre>cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
</pre>

Change the <code>capture_node</code> parameter in
<code>/etc/kamailio/kamailio.cfg</code> to a unique value. If you
changed the database user password, update the
<code>HOMER_DB_PASSWORD</code> parameter accordingly.

Enable the <code>kamailio</code> service:

<pre>echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start
</pre>

If using a firewall, you have to allow the reception of captured SIP
packets on UDP port 9060. In addition, you have to allow the primary
node to access the local database.

Finally, you have to add the database node to the primary server
configuration via the web user interface. Log in as an admin
user. Click on ''Panels'', ''System Admin'', and then
''Add Node''. Use the following values:

{|
|Node
|Value of <code>capture_node</code> in <code>/etc/kamailio/kamailio.cfg</code>
|-
|Host
|Host name or IP address of the database node
|-
|Port
|<code>3306</code>
|-
|DB Name
|<code>homer_data</code>
|-
|DB Username
|<code>homer_user</code>
|-
|DB Password
|Database password, which is <code>homer_password</code> unless you changed it
|-
|DB Tables
|<code>sip_capture</code>
|}

== Capture Nodes ==

To capture packets on a SIP server, install the HOMER CaptAgent:

<pre>apk add captagent
</pre>

Configure the <code>capture-host</code> and <code>capture-port</code>
parameters in <code>/etc/captagent/transport_hep.xml</code>. The
capture host is the primary or an additional database node. The port
should be set to <code>9060</code>.

Enable the service:

<pre>rc-update add captagent
rc-service captagent start
</pre>

If using a firewall, you have to allow sending the captured SIP
packets to UDP port 9060 of the specified capture host.

== Retention Period of Captured Packets ==

A cron job takes care of removing obsolete data from the capture host
databases. The retention period can be adjusted by modifying
<code>/etc/homer/rotation.ini</code>.

Setting up Homer

2017-09-19T08:38:28Z

Kunkku: LDAP authentication

{{Draft}}

Rough notes for setting up [http://sipcapture.org Homer] on Alpine Linux from testing repository

<pre>apk add homer-api-doc homer-ui mariadb kamailio-mysql nginx php7-fpm

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start

cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php7/php-fpm.d/homer5.conf
rc-update add php-fpm7
rc-service php-fpm7 start

: > /etc/nginx/conf.d/default.conf
cp /usr/share/doc/homer-api/examples/web/homer5.nginx /etc/nginx/conf.d/homer5.conf
edit "root" in /etc/nginx/conf.d/homer5.conf to "/usr/share/webapps/homer"
edit "server_name" in /etc/nginx/conf.d/homer5.conf
edit "fastcgi_pass" in /etc/nginx/conf.d/homer5.conf to "127.0.0.1:9001"
edit "SINGLE_NODE" in /etc/homer/configuration.php to "0" if using DB nodes
edit "HOMER_TIMEZONE" in /etc/homer/preferences.php
rc-update add nginx
rc-service nginx start

configure DB nodes in web UI, default password is "homer_password"
</pre>

== LDAP Authentication ==

Install LDAP authentication module:
<pre>apk add homer-api-ldap
</pre>

=== Changes in /etc/homer/preferences.php ===

Enable LDAP authentication:
<pre>define('AUTHENTICATION',"LDAP");
</pre>

Uncomment the LDAP section and add/update parameters according to your server
configuration:
<pre>define('LDAP_HOST',"localhost");
define('LDAP_PORT',389);
define('LDAP_VERSION',3);
define('LDAP_BIND_USER',"cn=HOMER,ou=Apps,dc=example,dc=com");
define('LDAP_BIND_PASSWORD',"secret");
define('LDAP_BASEDN',"ou=Users,dc=example,dc=com");
</pre>

Add one of the following lines:
<pre>define('LDAP_ENCRYPTION',"none");
define('LDAP_ENCRYPTION',"tls");
</pre>

Remove the variables starting with LDAP_GROUP_ unless you want to authorize
users based on group membership.

== Database Nodes ==

<pre>apk add homer-api-doc homer-db mariadb kamailio-mysql

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init -r
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
edit "capture_node" in /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start
</pre>

== Capture Nodes ==

<pre>apk add captagent
edit "capture-host" in /etc/captagent/transport_hep.xml
edit "capture-port" in /etc/captagent/transport_hep.xml to "9060"
rc-update add captagent
rc-service captagent start
</pre>

Setting up Homer

2017-09-02T10:09:56Z

Kunkku:

{{Draft}}

Rough notes for setting up [http://sipcapture.org Homer] on Alpine Linux from testing repository

<pre>apk add homer-api-doc homer-ui mariadb kamailio-mysql nginx php7-fpm

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start

cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php7/php-fpm.d/homer5.conf
rc-update add php-fpm7
rc-service php-fpm7 start

: > /etc/nginx/conf.d/default.conf
cp /usr/share/doc/homer-api/examples/web/homer5.nginx /etc/nginx/conf.d/homer5.conf
edit "root" in /etc/nginx/conf.d/homer5.conf to "/usr/share/webapps/homer"
edit "server_name" in /etc/nginx/conf.d/homer5.conf
edit "fastcgi_pass" in /etc/nginx/conf.d/homer5.conf to "127.0.0.1:9001"
edit "SINGLE_NODE" in /etc/homer/configuration.php to "0" if using DB nodes
edit "HOMER_TIMEZONE" in /etc/homer/preferences.php
rc-update add nginx
rc-service nginx start

configure DB nodes in web UI, default password is "homer_password"
</pre>

== Database Nodes ==

<pre>apk add homer-api-doc homer-db mariadb kamailio-mysql

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init -r
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
edit "capture_node" in /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start
</pre>

== Capture Nodes ==

<pre>apk add captagent
edit "capture-host" in /etc/captagent/transport_hep.xml
edit "capture-port" in /etc/captagent/transport_hep.xml to "9060"
rc-update add captagent
rc-service captagent start
</pre>

Setting up Homer

2017-07-06T12:16:18Z

Kunkku:

{{Draft}}

Rough notes for setting up [http://sipcapture.org Homer] on Alpine Linux from testing repository

<pre>apk add homer-api-doc homer-ui mariadb kamailio-mysql nginx php7-fpm

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start

cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php7/php-fpm.d/homer5.conf
rc-update add php-fpm7
rc-service php-fpm7 start

rm /etc/nginx/conf.d/default.conf
cp /usr/share/doc/homer-api/examples/web/homer5.nginx /etc/nginx/conf.d/homer5.conf
edit "root" in /etc/nginx/conf.d/homer5.conf to "/usr/share/webapps/homer"
edit "server_name" in /etc/nginx/conf.d/homer5.conf
edit "fastcgi_pass" in /etc/nginx/conf.d/homer5.conf to "127.0.0.1:9001"
edit "SINGLE_NODE" in /etc/homer/configuration.php to "0" if using DB nodes
edit "HOMER_TIMEZONE" in /etc/homer/preferences.php
rc-update add nginx
rc-service nginx start

configure DB nodes in web UI, default password is "homer_password"
</pre>

== Database Nodes ==

<pre>apk add homer-api-doc homer-db mariadb kamailio-mysql

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init -r
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
edit "capture_node" in /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start
</pre>

== Capture Nodes ==

<pre>apk add captagent
edit "capture-host" in /etc/captagent/transport_hep.xml
edit "capture-port" in /etc/captagent/transport_hep.xml to "9060"
rc-update add captagent
rc-service captagent start
</pre>

Setting up Homer

2017-02-20T14:57:37Z

Kunkku:

{{Draft}}

Rough notes for setting up [http://sipcapture.org Homer] on Alpine Linux from testing repository

<pre>apk add homer-api-doc homer-ui mariadb kamailio-mysql nginx php5-fpm

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start

cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php5/fpm.d/homer5.conf
rc-update add php-fpm
rc-service php-fpm start

rm /etc/nginx/conf.d/default.conf
cp /usr/share/doc/homer-api/examples/web/homer5.nginx /etc/nginx/conf.d/homer5.conf
edit "root" in /etc/nginx/conf.d/homer5.conf to "/usr/share/webapps/homer"
edit "server_name" in /etc/nginx/conf.d/homer5.conf
edit "fastcgi_pass" in /etc/nginx/conf.d/homer5.conf to "127.0.0.1:9001"
edit "SINGLE_NODE" in /etc/homer/configuration.php to "0" if using DB nodes
edit "HOMER_TIMEZONE" in /etc/homer/preferences.php
rc-update add nginx
rc-service nginx start

configure DB nodes in web UI, default password is "homer_password"
</pre>

== Database Nodes ==

<pre>apk add homer-api-doc homer-db mariadb kamailio-mysql

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

homer_db_init -r
rc-update add crond
rc-service crond start

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
edit "capture_node" in /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
rc-service kamailio start
</pre>

== Capture Nodes ==

<pre>apk add captagent
edit "capture-host" in /etc/captagent/transport_hep.xml
edit "capture-port" in /etc/captagent/transport_hep.xml to "9060"
rc-update add captagent
rc-service captagent start
</pre>

Setting up Homer

2017-02-08T08:00:35Z

Kunkku:

{{Draft}}

Rough notes for setting up [http://sipcapture.org Homer] on Alpine Linux from testing repository

{{Cmd|apk add homer-api-doc homer-ui mariadb mariadb-client kamailio-mysql nginx php5-fpm

rc-service mariadb setup
rc-update add mariadb
rc-service mariadb start
mysql_secure_installation

mysql < /usr/share/homer-api/sql/homer_databases.sql
mysql < /usr/share/homer-api/sql/homer_user.sql
mysql homer_data < /usr/share/homer-api/sql/schema_data.sql
mysql homer_configuration < /usr/share/homer-api/sql/schema_configuration.sql
mysql homer_statistic < /usr/share/homer-api/sql/schema_statistic.sql
homer_rotate

cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
rc-update add kamailio
rc-service kamailio start

cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php5/fpm.d/homer5.conf
rc-update add php-fpm
rc-service php-fpm start

rm /etc/nginx/conf.d/default.conf
cp /usr/share/doc/homer-api/examples/web/homer5.nginx /etc/nginx/conf.d/homer5.conf
edit "root" in /etc/nginx/conf.d/homer5.conf to "/usr/share/webapps/homer"
edit "server_name" in /etc/nginx/conf.d/homer5.conf
edit "fastcgi_pass" in /etc/nginx/conf.d/homer5.conf to "127.0.0.1:9001"
edit "HOMER_TIMEZONE" in /etc/homer/preferences.php
rc-update add nginx
rc-service nginx start
}}

Alpine Wall User's Guide

2015-12-24T11:01:16Z

Kunkku: Replaced content with "The current Alpine Wall User's Guide is available [http://git.alpinelinux.org/cgit/awall/about/ here]."

The current Alpine Wall User's Guide is available [http://git.alpinelinux.org/cgit/awall/about/ here].

Alpine Wall User's Guide

2014-09-29T10:47:29Z

Kunkku: /* Filter Rules */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 relative complement of the '''before''' definition in 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 '''type''' attribute may be used. The
replies to ICMP messages have their own type codes, which may be
specified using the '''reply-type''' attribute.

If the protocol is '''icmp''' or '''icmpv6''', the scope of the
rule is also automatically limited to IPv4 or IPv6,
respectively. There are also other services which are specific to
IPv4 or IPv6. To constrain the scope of the service definition to
either protocol version, an optional '''family''' attribute can
be set to value '''inet''' or '''inet6''', respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== Limits ===

A ''limit'' specifies the maximum rate for a flow of packets or new
connections. Unlike the other auxiliary objects, limits are not named
members of a top-level dictionary but are embedded into other objects.

In its simplest form, a limit definition is an integer specifying the
maximum number of packets or connections per second. More complex
limits are defined as objects, where the '''count''' attribute define
the maximum during an interval defined by the '''interval'''
attribute. The unit of the '''interval''' attribute is second, and
the default value is 1.

The maximum rate defined by a limit may be absolute or specific to
blocks of IP addresses or pairs thereof. The number of most
significant bits taken into account when mapping the source and
destination IP addresses to blocks can be specified with the
'''mask''' attribute. The '''mask''' attribute is an object with two
attributes defining the prefix lengths, named '''src''' and
'''dest'''. Alternatively, the '''mask''' object may have object
attributes named '''inet''' and '''inet6''' which contain address
family–specific prefix length pairs. If '''mask''' is defined as
an integer, it is interpreted as the source address prefix length.

The default value for '''mask''' depends on the type of the enclosing
object. For [[#Filter Rules|filters]], the default behavior is to
apply the limit for each source address separately. For
[[#Logging Classes|logging classes]], the limit is considered absolute
by default.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged defined as [[#Limits|limit]]
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

[[#Filter Rules|Filter]] and [[#Policy Rules|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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy rules
* MSS Clamping rules
* Connection Tracking Bypass rules

All rule objects can have the '''in''' and '''out''' attributes
referring to [[#Zones|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 [[#Zones|zone objects]]
|Packet's source address matches the value
|-
|'''dest'''
|Similar to '''addr''' attribute of [[#Zones|zone objects]]
|Packet's destination address matches the value
|-
|'''ipset'''
|Object containing two attributes: '''name''' referring to an [[#IP Sets|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.

==== Filter Rules ====

Filter objects specify an action for packets fulfilling certain
criteria. The top-level attribute '''filter''' is a list of filter
objects.

Filter objects must have an attribute named '''action''', the value of
which can be one of the following:

{|
!Value!!Action
|-
|'''accept'''
|Accept the packet (default)
|-
|'''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
[[#Limits|limit objects]]. The '''drop''' action is applied to the
packets exceeding the limit. Optionally, the limit object may have an
attribute named '''log'''. It defines how the dropped packets should
be logged and is semantically similar to the '''log''' attribute of
rule objects.

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. If
also port translation is desired, the attribute may be defined as
an object consisting of attributes '''addr''' and '''port'''. The
format of the '''port''' attribute is similar to that of the
'''to-port''' attribute of [[#NAT Rules|NAT rules]]. 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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

==== Policy 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 Rules|filter rules]].

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

NAT rules, may have an '''action''' attribute set to value
'''include''' or '''exclude'''. The latter means that NAT is not
performed on the matching packets (unless they match an '''include'''
rule processed earlier). The default value is '''include'''.

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

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

Like [[#NAT Rules|NAT rules]], connection tracking bypass rules may
have an '''action''' attribute set to value '''include''' or
'''exclude'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2014-09-29T10:43:35Z

Kunkku: /* Filter Rules */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 relative complement of the '''before''' definition in 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 '''type''' attribute may be used. The
replies to ICMP messages have their own type codes, which may be
specified using the '''reply-type''' attribute.

If the protocol is '''icmp''' or '''icmpv6''', the scope of the
rule is also automatically limited to IPv4 or IPv6,
respectively. There are also other services which are specific to
IPv4 or IPv6. To constrain the scope of the service definition to
either protocol version, an optional '''family''' attribute can
be set to value '''inet''' or '''inet6''', respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== Limits ===

A ''limit'' specifies the maximum rate for a flow of packets or new
connections. Unlike the other auxiliary objects, limits are not named
members of a top-level dictionary but are embedded into other objects.

In its simplest form, a limit definition is an integer specifying the
maximum number of packets or connections per second. More complex
limits are defined as objects, where the '''count''' attribute define
the maximum during an interval defined by the '''interval'''
attribute. The unit of the '''interval''' attribute is second, and
the default value is 1.

The maximum rate defined by a limit may be absolute or specific to
blocks of IP addresses or pairs thereof. The number of most
significant bits taken into account when mapping the source and
destination IP addresses to blocks can be specified with the
'''mask''' attribute. The '''mask''' attribute is an object with two
attributes defining the prefix lengths, named '''src''' and
'''dest'''. Alternatively, the '''mask''' object may have object
attributes named '''inet''' and '''inet6''' which contain address
family–specific prefix length pairs. If '''mask''' is defined as
an integer, it is interpreted as the source address prefix length.

The default value for '''mask''' depends on the type of the enclosing
object. For [[#Filter Rules|filters]], the default behavior is to
apply the limit for each source address separately. For
[[#Logging Classes|logging classes]], the limit is considered absolute
by default.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged defined as [[#Limits|limit]]
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

[[#Filter Rules|Filter]] and [[#Policy Rules|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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy rules
* MSS Clamping rules
* Connection Tracking Bypass rules

All rule objects can have the '''in''' and '''out''' attributes
referring to [[#Zones|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 [[#Zones|zone objects]]
|Packet's source address matches the value
|-
|'''dest'''
|Similar to '''addr''' attribute of [[#Zones|zone objects]]
|Packet's destination address matches the value
|-
|'''ipset'''
|Object containing two attributes: '''name''' referring to an [[#IP Sets|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.

==== Filter Rules ====

Filter objects specify an action for packets fulfilling certain
criteria. The top-level attribute '''filter''' is a list of filter
objects.

Filter objects must have an attribute named '''action''', the value of
which can be one of the following:

{|
!Value!!Action
|-
|'''accept'''
|Accept the packet (default)
|-
|'''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
[[#Limits|limit objects]]. The '''drop''' action is applied to the
packets exceeding the limit. Optionally, the limit object may have an
attribute named '''log'''. It defines how the dropped packets should
be logged and is semantically similar to the '''log''' attribute of
rule objects.

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. If
also port translation is desired, the attribute may be defined as
an object consisting of attributes '''addr''' and '''port'''.
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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

==== Policy 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 Rules|filter rules]].

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

NAT rules, may have an '''action''' attribute set to value
'''include''' or '''exclude'''. The latter means that NAT is not
performed on the matching packets (unless they match an '''include'''
rule processed earlier). The default value is '''include'''.

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

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

Like [[#NAT Rules|NAT rules]], connection tracking bypass rules may
have an '''action''' attribute set to value '''include''' or
'''exclude'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2014-09-19T08:55:24Z

Kunkku: /* Configuration Objects */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 relative complement of the '''before''' definition in 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 '''type''' attribute may be used. The
replies to ICMP messages have their own type codes, which may be
specified using the '''reply-type''' attribute.

If the protocol is '''icmp''' or '''icmpv6''', the scope of the
rule is also automatically limited to IPv4 or IPv6,
respectively. There are also other services which are specific to
IPv4 or IPv6. To constrain the scope of the service definition to
either protocol version, an optional '''family''' attribute can
be set to value '''inet''' or '''inet6''', respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== Limits ===

A ''limit'' specifies the maximum rate for a flow of packets or new
connections. Unlike the other auxiliary objects, limits are not named
members of a top-level dictionary but are embedded into other objects.

In its simplest form, a limit definition is an integer specifying the
maximum number of packets or connections per second. More complex
limits are defined as objects, where the '''count''' attribute define
the maximum during an interval defined by the '''interval'''
attribute. The unit of the '''interval''' attribute is second, and
the default value is 1.

The maximum rate defined by a limit may be absolute or specific to
blocks of IP addresses or pairs thereof. The number of most
significant bits taken into account when mapping the source and
destination IP addresses to blocks can be specified with the
'''mask''' attribute. The '''mask''' attribute is an object with two
attributes defining the prefix lengths, named '''src''' and
'''dest'''. Alternatively, the '''mask''' object may have object
attributes named '''inet''' and '''inet6''' which contain address
family–specific prefix length pairs. If '''mask''' is defined as
an integer, it is interpreted as the source address prefix length.

The default value for '''mask''' depends on the type of the enclosing
object. For [[#Filter Rules|filters]], the default behavior is to
apply the limit for each source address separately. For
[[#Logging Classes|logging classes]], the limit is considered absolute
by default.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged defined as [[#Limits|limit]]
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

[[#Filter Rules|Filter]] and [[#Policy Rules|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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy rules
* MSS Clamping rules
* Connection Tracking Bypass rules

All rule objects can have the '''in''' and '''out''' attributes
referring to [[#Zones|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 [[#Zones|zone objects]]
|Packet's source address matches the value
|-
|'''dest'''
|Similar to '''addr''' attribute of [[#Zones|zone objects]]
|Packet's destination address matches the value
|-
|'''ipset'''
|Object containing two attributes: '''name''' referring to an [[#IP Sets|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.

==== Filter Rules ====

Filter objects specify an action for packets fulfilling certain
criteria. The top-level attribute '''filter''' is a list of filter
objects.

Filter objects must have an attribute named '''action''', the value of
which can be one of the following:

{|
!Value!!Action
|-
|'''accept'''
|Accept the packet (default)
|-
|'''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
[[#Limits|limit objects]]. The '''drop''' action is applied to the
packets exceeding the limit. Optionally, the limit object may have an
attribute named '''log'''. It defines how the dropped packets should
be logged and is semantically similar to the '''log''' attribute of
rule objects.

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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

==== Policy 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 Rules|filter rules]].

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

NAT rules, may have an '''action''' attribute set to value
'''include''' or '''exclude'''. The latter means that NAT is not
performed on the matching packets (unless they match an '''include'''
rule processed earlier). The default value is '''include'''.

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

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

Like [[#NAT Rules|NAT rules]], connection tracking bypass rules may
have an '''action''' attribute set to value '''include''' or
'''exclude'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2014-09-19T08:19:07Z

Kunkku: /* Configuration Objects */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 relative complement of the '''before''' definition in 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 '''type''' attribute may be used. The
replies to ICMP messages have their own type codes, which may be
specified using the '''reply-type''' attribute.

If the protocol is '''icmp''' or '''icmpv6''', the scope of the
rule is also automatically limited to IPv4 or IPv6,
respectively. There are also other services which are specific to
IPv4 or IPv6. To constrain the scope of the service definition to
either protocol version, an optional '''family''' attribute can
be set to value '''inet''' or '''inet6''', respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

[[#Filter Rules|Filter]] and [[#Policy Rules|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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy rules
* MSS Clamping rules
* Connection Tracking Bypass rules

All rule objects can have the '''in''' and '''out''' attributes
referring to [[#Zones|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 [[#Zones|zone objects]]
|Packet's source address matches the value
|-
|'''dest'''
|Similar to '''addr''' attribute of [[#Zones|zone objects]]
|Packet's destination address matches the value
|-
|'''ipset'''
|Object containing two attributes: '''name''' referring to an [[#IP Sets|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.

==== Filter Rules ====

Filter objects specify an action for packets fulfilling certain
criteria. The top-level attribute '''filter''' is a list of filter
objects.

Filter objects must have an attribute named '''action''', the value of
which can be one of the following:

{|
!Value!!Action
|-
|'''accept'''
|Accept the packet (default)
|-
|'''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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

==== Policy 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 Rules|filter rules]].

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

NAT rules, may have an '''action''' attribute set to value
'''include''' or '''exclude'''. The latter means that NAT is not
performed on the matching packets (unless they match an '''include'''
rule processed earlier). The default value is '''include'''.

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

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

Like [[#NAT Rules|NAT rules]], connection tracking bypass rules may
have an '''action''' attribute set to value '''include''' or
'''exclude'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2014-03-31T16:50:44Z

Kunkku: /* Connection Tracking Bypass Rules */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 relative complement of the '''before''' definition in 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 '''type''' attribute may be used. The
replies to ICMP messages have their own type codes, which may be
specified using the '''reply-type''' attribute.

If the protocol is '''icmp''' or '''icmpv6''', the scope of the
rule is also automatically limited to IPv4 or IPv6,
respectively. There are also other services which are specific to
IPv4 or IPv6. To constrain the scope of the service definition to
either protocol version, an optional '''family''' attribute can
be set to value '''inet''' or '''inet6''', respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

Filter objects must have an attribute named '''action''', the value of
which can be one of the following:

{|
!Value!!Action
|-
|'''accept'''
|Accept the packet (default)
|-
|'''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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

==== 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 NAT rules, connection tracking bypass rules may have an
'''action''' attribute set to value '''include''' or
'''exclude'''.

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

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

Like NAT rules, connection tracking bypass rules may have an
'''action''' attribute set to value '''include''' or
'''exclude'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2014-03-31T16:50:11Z

Kunkku:

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 relative complement of the '''before''' definition in 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 '''type''' attribute may be used. The
replies to ICMP messages have their own type codes, which may be
specified using the '''reply-type''' attribute.

If the protocol is '''icmp''' or '''icmpv6''', the scope of the
rule is also automatically limited to IPv4 or IPv6,
respectively. There are also other services which are specific to
IPv4 or IPv6. To constrain the scope of the service definition to
either protocol version, an optional '''family''' attribute can
be set to value '''inet''' or '''inet6''', respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

Filter objects must have an attribute named '''action''', the value of
which can be one of the following:

{|
!Value!!Action
|-
|'''accept'''
|Accept the packet (default)
|-
|'''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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

==== 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 NAT rules, connection tracking bypass rules may have an
'''action''' attribute set to value '''include''' or
'''exclude'''.

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

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

==== 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 '''include''' or '''exclude''', with
behavior similar to that of NAT rules.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2014-03-07T10:52:18Z

Kunkku: /* Services */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 '''type''' attribute may be used. The
replies to ICMP messages have their own type codes, which may be
specified using the '''reply-type''' attribute.

If the protocol is '''icmp''' or '''icmpv6''', the scope of the
rule is also automatically limited to IPv4 or IPv6,
respectively. There are also other services which are specific to
IPv4 or IPv6. To constrain the scope of the service definition to
either protocol version, an optional '''family''' attribute can
be set to value '''inet''' or '''inet6''', respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-10-07T19:34:57Z

Kunkku: /* Services */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 '''type''' attribute
may be used. In addition, the scope of the rule is also automatically
limited to IPv4 or IPv6, respectively.

There are also other services which are specific to IPv4 or IPv6. To
constrain the scope of the service definition to either protocol
version, an optional '''family''' attribute can be set to value
'''inet''' or '''inet6''', respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-10-07T19:25:24Z

Kunkku: /* Services */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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 '''type''' attribute
may be used. In addition, the scope of the rule is also automatically
limited to IPv4 or IPv6, respectively.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-02-19T11:21:46Z

Kunkku: /* Configuration Objects */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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.

Some services require the server or client to open additional
connections to dynamically allocated ports or even different
hosts. ''Connection tracking helpers'' are used to make the firewall
aware of such additional connections. The '''ct-helper''' attribute is
used to associate such a helper to a service definition when
required by the service.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

If one or more connection tracking helpers are associated with the
services referred to by an accept rule, additional iptables rules are
generated for the related connections detected by the helpers. The
'''related''' attribute can be used to override the default rules
generated by awall. It is a list of basic rule objects, the packets
matching to which are accepted, provided that they are also detected
by at least one of the helpers.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-02-19T08:15:16Z

Kunkku: /* Transparent Proxy Rules */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''awall_tproxy_mark''' variable can
be used to specify the mark for such packets, which defaults to 1.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-02-08T07:33:31Z

Kunkku: /* Configuration File Processing */

== Configuration File Processing ==

[[Alpine Wall]] (awall) reads its configuration from multiple
JSON-formatted files, called ''policy files''. The files located in
directory <tt>/usr/share/awall/mandatory</tt> are ''mandatory''
policies shipped with APK packages. In addition, there can be
installation-specific mandatory policies in <tt>/etc/awall</tt>.

The latter directory may also contain symbolic links to policy files
located in <tt>/usr/share/awall/optional</tt> and
<tt>/etc/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 imported policies may be
either optional policies or ''private'' policies, located in
<tt>/usr/share/awall/private</tt> or <tt>/etc/awall/private</tt>. 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.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''mark''' attribute of a proxy rule
specifies the mark to be used.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-02-08T07:13:28Z

Kunkku: /* 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> and
<tt>/etc/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.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* Packet Logging rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

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

==== Packet Logging Rules ====

Packet logging rules allow packets matching the specified criteria to
be logged before any filtering takes place. Such rules are contained
in the top-level list named '''packet-log'''.

Logging class may be specified using the '''log'''
attribute. Otherwise, default logging settings are used.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''mark''' attribute of a proxy rule
specifies the mark to be used.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-02-05T16:10:39Z

Kunkku: /* 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> and
<tt>/etc/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.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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 several types of rule objects:
* Filter rules
* Policy rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''mark''' attribute of a proxy rule
specifies the mark to be used.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-02-05T14:58:40Z

Kunkku: /* Logging Classes */

== 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> and
<tt>/etc/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.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 following table shows the optional attributes valid for all
logging modes:

{|
!Attribute!!Description
|-
|'''every'''
|Divide successive packets into groups, the size of which is specified by the value of this attribute, and log only the first packet of each group
|-
|'''limit'''
|Maximum number of packets to be logged per second per this rule
|-
|'''prefix'''
|String with which the log entries are prefixed
|-
|'''probability'''
|Probability for logging an individual packet (default: 1)
|}

With the in-kernel log mode '''log''', the level of logging may be
specified using the '''level''' attribute. Log modes '''nflog''' and
'''ulog''' are about copying the packets into user space, at least
partially. The following table shows the additional attributes valid
with these modes:

{|
!Attribute!!Description
|-
|'''group'''
|Netlink group to be used
|-
|'''range'''
|Number of bytes to be copied
|-
|'''threshold'''
|Number of packets to queue inside the kernel before copying them
|}

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:
* Filter rules
* Policy rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''mark''' attribute of a proxy rule
specifies the mark to be used.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-01-30T08:23:54Z

Kunkku: /* Filter 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> and
<tt>/etc/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.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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:
* Filter rules
* Policy rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 (default: 1). The
'''drop''' action is applied to the packets exceeding the
limit. Optionally, the limit object may have an attribute named
'''log'''. It defines how the dropped packets should be logged and is
semantically similar to the '''log''' attribute of rule objects. A
limit may also be specified by a plain integer, which is interpreted
as the count while using default interval and log settings.

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.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''mark''' attribute of a proxy rule
specifies the mark to be used.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-01-29T11:21:42Z

Kunkku: /* Configuration Objects */

== 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> and
<tt>/etc/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.

All rule objects, except for policies, may have an attribute named
'''service''', constraining the rule's scope to specific services
only. This attribute is a list of service names, referring to the keys
of the top-level service dictionary.

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

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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:
* Filter rules
* Policy rules
* NAT rules
* Packet Marking rules
* Transparent Proxy 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.

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

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 '''drop'''
action is applied to the packets exceeding the limit. Optionally, the
limit object may have an attribute named '''log'''. It defines how the
dropped packets should be logged and is semantically similar to the
'''log''' attribute of rule objects.

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.

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

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.

==== Transparent Proxy Rules ====

Transparent proxy rules divert the matching packets to a local proxy
process without altering their headers. Such rules are contained in
the top-level list named '''tproxy'''.

In addition to the firewall configuration, using a transparent proxy
requires a routing configuration where packets marked for proxying are
diverted to a local process. The '''mark''' attribute of a proxy rule
specifies the mark to be used.

Proxy rules may also have an attribute named '''to-port''' for
specifying the TCP or UDP port of the proxy if it is different from
the original destination port.

==== 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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

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

2013-01-18T17:27:34Z

Kunkku: /* 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> and
<tt>/etc/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.

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 '''drop'''
action is applied to the packets exceeding the limit. Optionally, the
limit object may have an attribute named '''log'''. It defines how the
dropped packets should be logged and is semantically similar to the
'''log''' attribute of rule objects.

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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

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

For bitmap-type IP sets, the '''range''' attribute specifies the
range of allowed IPv4 addresses. It may be given as a network
address or two addresses separated by the '''-''' character. It
is not necessary to specify '''family''' for bitmaps, since the
kernel supports only IPv4 bitmaps.

== 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-10-23T11:23:56Z

Kunkku: /* 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> and
<tt>/etc/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.

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 '''drop'''
action is applied to the packets exceeding the limit. Optionally, the
limit object may have an attribute named '''log'''. It defines how the
dropped packets should be logged and is semantically similar to the
'''log''' attribute of rule objects.

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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

==== 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-10-23T07:03:18Z

Kunkku: /* Filters 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.

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 '''drop'''
action is applied to the packets exceeding the limit. Optionally, the
limit object may have an attribute named '''log'''. It defines how the
dropped packets should be logged and is semantically similar to the
'''log''' attribute of rule objects.

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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

==== 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-10-17T13:16:15Z

Kunkku: /* MSS Clamping 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.

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 '''drop'''
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. The MSS clamping rules are located in the top-level
dictionary named '''clamp-mss'''.

==== 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-10-17T13:04:07Z

Kunkku: /* Filters 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.

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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 '''drop'''
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-10-03T07:31:00Z

Kunkku: /* 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. 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.

By default, awall does not generate iptables rules with identical
ingress and egress interfaces. This behavior can be changed per zone
by setting the optional '''route-back''' attribute of the zone to
'''true'''. Note that this attribute can have an effect also in the
case where '''in''' and '''out''' attributes of a rule are not equal
but their definitions overlap. In this case, the '''route-back'''
attribute of the '''out''' zone determines the behavior.

=== 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-10-03T07:24:30Z

Kunkku: /* 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. 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-09-13T10:12:24Z

Kunkku: /* NAT 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 five types of rule objects:
* policies
* filters
* 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 ====

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

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-09-12T08:32:45Z

Kunkku: /* Logging Classes */

== 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 five types of rule objects:
* policies
* filters
* 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 ====

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

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 '''ip-range''' 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 '''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.

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-09-03T11:21:51Z

Kunkku: /* 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. 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.

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 five types of rule objects:
* policies
* filters
* 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 ====

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

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 '''ip-range''' 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 '''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.

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-09-03T11:19:50Z

Kunkku: /* 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. 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. 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.

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 five types of rule objects:
* policies
* filters
* 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 ====

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

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 '''ip-range''' 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 '''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.

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-08-28T10:57:07Z

Kunkku: /* 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. 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. 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.

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 five types of rule objects:
* policies
* filters
* 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 ====

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.

==== 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 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 '''ip-range''' 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 '''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.

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-08-28T08:20:45Z

Kunkku:

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

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 five types of rule objects:
* policies
* filters
* 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 ====

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.

==== 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 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 '''ip-range''' 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 '''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.

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-07-19T05:59:37Z

Kunkku: /* 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. 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.

=== Rules ===

There are five types of rule objects:
* policies
* filters
* 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 ====

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
|-
|'''logreject'''
|Similar to '''reject''' but with kernel logging
|-
|'''logdrop'''
|Similar to '''drop''' but with kernel logging
|}

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.

==== 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 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 '''ip-range''' 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 '''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.

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-07-13T13:22:32Z

Kunkku: /* Debugging Policies */

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

=== Rules ===

There are five types of rule objects:
* policies
* filters
* NAT rules
* packet marking 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 ====

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
|-
|'''logreject'''
|Similar to '''reject''' but with kernel logging
|-
|'''logdrop'''
|Similar to '''drop''' but with kernel logging
|}

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.

==== 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 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 '''ip-range''' 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 '''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.

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.

==== 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-07-13T11:44:50Z

Kunkku: /* 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. 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.

=== Rules ===

There are five types of rule objects:
* policies
* filters
* NAT rules
* packet marking 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 ====

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
|-
|'''logreject'''
|Similar to '''reject''' but with kernel logging
|-
|'''logdrop'''
|Similar to '''drop''' but with kernel logging
|}

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.

==== 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 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 '''ip-range''' 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 '''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.

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.

==== 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–3 and defaults to 0. More
information is displayed on higher levels.

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

Alpine Wall User's Guide

2012-07-12T13:00:43Z

Kunkku: /* NAT Rules */

Alpine Wall User's Guide

2012-07-12T12:20:43Z

Kunkku: /* Connection Tracking Bypass Rules */

Alpine Wall User's Guide

2012-07-12T05:52:52Z

Kunkku: /* Rules */

Alpine Wall User's Guide

2012-07-12T05:44:13Z

Kunkku: /* Run-Time Configuration of Firewall */

Alpine Wall User's Guide

2012-07-12T05:41:55Z

Kunkku: /* Run-Time Activation of New Firewall Configuration */

Alpine Wall User's Guide

2012-07-12T05:38:03Z

Kunkku: /* Rules */

Alpine Wall User's Guide

2012-07-12T05:20:00Z

Kunkku: /* Zones */

Alpine Wall User's Guide

2012-07-12T05:16:53Z

Kunkku: /* Command Line Syntax */

Alpine Wall User's Guide

2012-05-03T06:19:07Z

Kunkku: /* Rules */

Alpine Wall User's Guide

2012-05-03T05:59:42Z

Kunkku: