|
|
| (49 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| == Configuration File Processing ==
| | {{Delete|All wikilinks on the entire wiki have already been changed to point to the awall guide on git. Nothing points to this article, nor should it}} |
|
| |
|
| [[Alpine Wall]] (awall) reads its configuration from multiple
| | The current Alpine Wall User's Guide is available [https://git.alpinelinux.org/awall/about/ here]. |
| JSON-formatted files, called ''policy files''. The processing starts
| |
| from directory <tt>/usr/share/awall/mandatory</tt>, which contains
| |
| mandatory policy files shipped with APK packages. After that,
| |
| installation-specific policy files in <tt>/etc/awall</tt> are
| |
| processed.
| |
| | |
| The latter directory may also contain symbolic links to policy files
| |
| located in <tt>/usr/share/awall/optional</tt>. These are optional
| |
| policies, which can be enabled on need basis. Such symbolic links are
| |
| easily created and destroyed using the <tt>awall enable</tt> and
| |
| <tt>awall disable</tt> commands. <tt>awall list</tt> shows which
| |
| optional policies are enabled and disabled. The command also prints
| |
| the description of the optional policy if defined in the file using
| |
| a top-level attribute named '''description'''.
| |
| | |
| Sometimes a policy file depends on other policy files. In this case,
| |
| the policy file must have a top-level attribute '''import''', the
| |
| value of which is a list of policy names, which correspond to the file
| |
| names without the <tt>.json</tt> suffix. The policies listed there are
| |
| always processed before the importing policy. The order of the
| |
| generated iptables rules generally reflects the processing order of
| |
| their corresponding awall policies.
| |
| | |
| As the import directive does not require the path name to be
| |
| specified, awall expects policies to have unique names, even if
| |
| located in different directories. It is allowed to import optional
| |
| policies that are not explicitly enabled by the user. Such policies
| |
| show up with the <tt>required</tt> status in the output of <tt>awall
| |
| list</tt>.
| |
| | |
| == List Parameters ==
| |
| | |
| Several awall parameters are defined as lists of values. In order to
| |
| facilitate manual editing of policy files, awall also accepts single
| |
| values in place of lists. Such values are semantically equivalent to
| |
| lists containing one element.
| |
| | |
| == Variable Expansion ==
| |
| | |
| Awall allows variable definitions in policy files. The top-level
| |
| attribute '''variable''' is a dictionary containing the
| |
| definitions. The value of a variable can be of any type (string,
| |
| integer, list, or dictionary).
| |
| | |
| A variable is referenced in policy files by a string which equals the
| |
| variable name prepended with the '''$''' character. If the value of
| |
| the variable is a string, the reference can be embedded into a longer
| |
| string in order to substitute some part of that string (in shell
| |
| style). Variable references can be used when defining other variables,
| |
| as long as the definitions are not circular.
| |
| | |
| Policy files can reference variables defined in other policy
| |
| files. Policy files can also override variables defined elsewhere by
| |
| redefining them. In this case, the new definition affects all policy
| |
| files, also those processed before the overriding policy. Awall
| |
| variables are in fact simple macros, since each variable remains
| |
| constant thoughout a single processing round. If multiple files define
| |
| the same variable, the definition in the file processed last takes
| |
| effect.
| |
| | |
| If defined as an empty string, all non-embedded references to a
| |
| variable evaluate as if the attribute in question was not present in
| |
| the configuration. This is also the case when a string containing
| |
| embedded variable references finally evaluates to an empty string.
| |
| | |
| == Configuration Objects ==
| |
| | |
| Configuration objects can be divided into two main types.
| |
| ''Auxiliary objects'' model high-level concepts such as services and
| |
| zones. ''Rule objects'' translate into one or more iptables rules, and
| |
| are often defined with the help of some auxiliary objects.
| |
| | |
| === Services ===
| |
| | |
| A ''service'' represents a set of network protocols. A top-level
| |
| attribute '''service''' is a dictionary that maps service names to
| |
| service definition objects, or lists thereof in more complex cases.
| |
| | |
| A service definition object contains an attribute named '''proto''',
| |
| which corresponds to the <tt>--protocol</tt> option of iptables. The
| |
| protocol can be defined as a numerical value or string as defined in
| |
| <tt>/etc/protocols</tt>. If the protocol is '''tcp''' or '''udp''',
| |
| the scope of the service definition may be constrained by defining an
| |
| attribute named '''port''', which is a list of TCP or UDP port
| |
| numbers. If the protocol is '''icmp''' or '''icmpv6''', an analogous
| |
| '''icmp-type''' attribute may be used. In addition, the scope of the
| |
| rule is also automatically limited to IPv4 or IPv6, respectively.
| |
| | |
| === Zones ===
| |
| | |
| A ''zone'' represents a set of network hosts. A top-level attribute
| |
| '''zone''' is a dictionary that maps zone names to zone objects. A
| |
| zone object has an attribute named '''iface''', '''addr''', or
| |
| both. '''iface''' is a list of network interfaces and '''addr''' is a
| |
| list of IPv4/IPv6 host and network addresses (CIDR
| |
| notation). '''addr''' may also contain domain names, which are
| |
| expanded to IP addresses using DNS resolution. If not defined,
| |
| '''addr''' defaults to the entire address space and '''iface''' to all
| |
| interfaces.
| |
| | |
| Rule objects contain two attributes, '''in''' and '''out''', which are
| |
| lists of zone names. These attributes control whether a packet matches
| |
| the rule or not. If a particular zone is referenced by the '''in'''
| |
| attribute, the rule applies to packets whose ingress interface and
| |
| source address are covered by the zone definition. Correspondingly, if
| |
| a zone is referenced by the '''out''' attribute, the rule applies to
| |
| packets whose egress interface and destination address are included in
| |
| the zone. If both '''in''' and '''out''' are defined, the packet must
| |
| fulfill both criteria in order to match the rule.
| |
| | |
| === Rules ===
| |
| | |
| There are three types of rule objects: ''policies'', ''filters'', and
| |
| ''NAT rules''.
| |
| | |
| All rule objects can have the '''in''' and '''out''' attributes
| |
| referring to zones as described in the previous section. In addition,
| |
| the scope of the rule can be further constrained with the following
| |
| attributes:
| |
| | |
| {|
| |
| !Attribute!!Value format!!Effect
| |
| |-
| |
| |'''src'''
| |
| |Similar to '''addr''' attribute of zone objects
| |
| |Packet's source address matches the value
| |
| |-
| |
| |'''dest'''
| |
| |Similar to '''addr''' attribute of zone objects
| |
| |Packet's destination address matches the value
| |
| |-
| |
| |'''ipset'''
| |
| |Object containing two attributes: '''name''' referring to an IP set and '''args''', which is a list of strings '''in''' and '''out'''
| |
| |Packet matches the IP set referred here when the match arguments are taken from the source ('''in''') and destination ('''out''') address or port in the order specified by '''args'''
| |
| |-
| |
| |'''ipsec'''
| |
| |'''in''' or '''out'''
| |
| |IPsec decapsulation perfomed on ingress ('''in''') or encapsulation performed on egress ('''out''')
| |
| |}
| |
| | |
| Rule objects must have an attribute named '''action''', the value of
| |
| which can be one of the following:
| |
| | |
| {|
| |
| !Value!!Action
| |
| |-
| |
| |'''accept'''
| |
| |Accept the packet
| |
| |-
| |
| |'''reject'''
| |
| |Reject the packet with an ICMP error message
| |
| |-
| |
| |'''drop'''
| |
| |Silently drop the packet
| |
| |-
| |
| |'''logreject'''
| |
| |Similar to '''reject''' but with kernel logging
| |
| |-
| |
| |'''logdrop'''
| |
| |Similar to '''drop''' but with kernel logging
| |
| |}
| |
| | |
| Rule objects are declared in type-specific top-level dictionaries in
| |
| awall policy files. If a packet matches multiple rules, the one
| |
| appearing earlier in the list takes precedence. If the matching rules
| |
| are defined in different policy files, the one that was processed
| |
| earlier takes precedence in the current implementation, but this may
| |
| change in future versions.
| |
| | |
| ==== Filters ====
| |
| | |
| Filter objects specify an action for packets fulfilling certain
| |
| criteria. The top-level attribute '''filter''' is a list of filter
| |
| objects. The precedence rules are similar to those of policy objects.
| |
| | |
| In addition to the common rule attributes, filter objects can have a
| |
| '''service''' attribute constraining the scope to specific services
| |
| only. This attribute is a list of service names, referring to the
| |
| keys of the top-level '''service''' dictionary.
| |
| | |
| Filter objects may also contain limits for packet flow or new
| |
| connections. These are specified with the '''flow-limit''' and
| |
| '''conn-limit''' attributes, respectively. The values of these
| |
| attributes are limit objects that have two attributes: '''count''' and
| |
| '''interval'''. '''count''' specifies how many new connections or
| |
| packets are allowed within the time frame specified by '''interval'''
| |
| (in seconds). The '''logdrop''' action is applied to the packets
| |
| exceeding the limit.
| |
| | |
| Filter objects may have an attribute named '''dnat''', the value of
| |
| which is an IPv4 address. If defined, this enables destination NAT for
| |
| all IPv4 packets matching the rule, such that the specified address
| |
| replaces the original destination address. This option has no effect
| |
| on IPv6 packets.
| |
| | |
| ==== Policies ====
| |
| | |
| Policy objects describe the default action for packets that did not
| |
| match any filter. The top-level attribute '''policy''' is a list of
| |
| policy objects. Policy objects do not have other attributes than those
| |
| common to all rule objects.
| |
| | |
| ==== NAT Rules ====
| |
| | |
| NAT rules come in two flavors: ''source NAT rules'' and
| |
| ''destination NAT rules''. These are contained in two top-level lists
| |
| named '''snat''' and '''dnat''', respectively.
| |
| | |
| Each NAT rule must have an attribute named '''ip-range''' that
| |
| specifies the IPv4 address range to which the original source or
| |
| destinatinon address is mapped. The value can be a single IPv4 address
| |
| or a range specified by two addresses, separated with the '''-'''
| |
| character.
| |
| | |
| Optionally, a NAT rule can specify the TCP and UDP port range to which
| |
| the original source or destination port is mapped. The attribute is
| |
| named '''port-range''', and the value can be a single port number or a
| |
| range specified by two numbers, separated with the '''-'''
| |
| character. If '''port-range''' is not specified, the original port
| |
| number is kept intact.
| |
| | |
| Like filters, NAT rules can have a '''service''' attribute
| |
| constraining their scope to specific services.
| |
| | |
| === IP Sets ===
| |
| | |
| Any IP set referenced by rule objects should be created by
| |
| awall. Auxiliary ''IP set'' objects are used to defined them in awall
| |
| policy files. The top-level attribute '''ipset''' is a dictionary, the
| |
| keys of which are IP set names. The values are IP set objects, which
| |
| have two mandatory attributes. The attribute named '''type'''
| |
| corresponds to the type argument of the <tt>ipset create</tt>
| |
| command. '''family''' specifies whether the set is for IPv4 or IPv6
| |
| addresses, and the possible values are '''inet''' and '''inet6''',
| |
| correspondingly.
| |
| | |
| == Command Line Syntax ==
| |
| | |
| === Translating Policy Files to Firewall Configuration Files ===
| |
| | |
| '''awall translate''' ['''-o'''|'''--output''' DIRECTORY] ['''-V'''|'''--verify''']
| |
| | |
| The <tt>--verify</tt> option makes awall verify the configuration
| |
| using the test mode of iptables-restore before overwriting the old
| |
| files.
| |
| | |
| Specifying the output directory allows testing awall policies without
| |
| overwriting the current iptables and ipset configuration files. By
| |
| default, awall generates the configuration to <tt>/etc/iptables</tt>
| |
| and <tt>/etc/ipset.d</tt>, which are read by the init scripts.
| |
| | |
| === Run-Time Activation of New Firewall Configuration ===
| |
| | |
| '''awall activate'''
| |
| | |
| This command genereates firewall configuration from the policy files
| |
| and enables it. If the user confirms the new configuration by hitting
| |
| the Return key within 10 seconds, the configuration is saved to the
| |
| files. Otherwise, the old configuration is restored.
| |
| | |
| === Optional Policies ===
| |
| | |
| Optional policies can be enabled or disabled using this command:
| |
| | |
| '''awall''' {'''enable'''|'''disable'''} POLICY...
| |
| | |
| Optional policies can be listed using this command:
| |
| | |
| '''awall list'''
| |
| | |
| The '''enabled''' status means that the policy has been enabled by the
| |
| user. The '''disabled''' status means that the policy is not in
| |
| use. The '''required''' status means that the policy has not been
| |
| enabled by the user but is in use because it is required by another
| |
| policy which is in use.
| |
| | |
| [[Category:Networking]]
| |
