Name

ip-array rulefiles — Configure ip-array rule files

Synopsis

/etc/ip-array/{stable|test}/conf.d/rules.d/file

Description

Rule files are written in a simple and relaxed XML style. There are different rule tags available, as well as public functions. For each iptables table (if configured to be used) there must be at least one rule file defined.

Syntax

A rule definition file must contain the root tag including the describing name attribule and the syntax version:

<ip_array_root name="iptables_rules" syntax_version="1.1">

The name attribute tells us it is an iptables rule definition.

The syntax_version attribute defines the syntax version. 1.0 and 1.1 are available by now. The ipset tags were introduced with version 1.1.

The XML syntax can be used in a relaxed way (not XML compatible). Tags can be closed by a simple `/>'. Attributes can have their value enclosed inside single quotes, or not quoted at all.

Tags

  • <rule> or the short form <r>

    A single rule entry. All iptables arguments can be used inside a rule tag. The list of valid arguments can be retrieved by running: ip-array show -sc ipt_args[,...].

    They can be used as attributes of the tag, or as content inside the tag. In the first form they do not need be enclosed inside quotes (relaxed XML), unless the value contains a whitespace. Values with whitespace must be enclosed within double or single quotes. In both cases the left hand side (left of the `=') is the iptables argument and the right hand side is its value.

    Examples:

    <rule> table="filter" chain="INPUT" src="1.1.1.1" target="DROP" </rule>

    <rule table="filter" chain="INPUT" src="1.1.1.1" target="DROP" />

    <r> table=filter chain=INPUT target=LOG log_prefix="my log message" />

  • <combined_rule> or the short form <cr>

    ´Combined rules allow to create reverse traffic rules like with templates and ruleblocks with the reverse_mode=reverse option, but in a dynamic way.

    It has these attributes available:

    • reverse_mode - which can be like within templates set to either `reverse' or `mirror'.

    • reverse_condition - like within templates defines a condition that must evaluate to true for the reverse rules to be created. The variable name and its value must be separated by a colon `:'. i.e. foo:bar

    • msg - like with template_msg, it allows to define a message to be displayed, if VERBOSE is greater or equal 3.

    The iptables arguments must be used inside the <optlist> tag (see next item in the list). The arguments in the second option list do not need the equal siqn and the right hand side value. The values of the first option list will be used in order from left to right and will be applied to the options (iptables arguments) of the second option list. Only if a value needs to be left out the special keyword `empty' can be used. Either as option name (i.e. option list one has `odev=eth0' as iptables argument, you will use just `empty' in the second option list), or as value (i.e. idev=empty).

    All global iptables arguments, that are opended inside a combined rule will be applied to all following rules created with the <optlist> tag. They will not be applied to rules outside of the combined rule.

    Note

    Inside combined rules the iptables arguments target and chain may be set to a comma separated list (maximum 2 chains can be defined).

    Example:

    <table> filter
        <combined_rule reverse_mode="reverse" reverse_condition="x:y">
            <chain> INPUT,OUTPUT
                <target> LOG,ACCEPT
                    <optlist> proto=tcp sport=99 </optlist>
                    <optlist> proto dport </optlist>
                </target>
                <target> DROP
                    <opts idev="$lan_if" proto="udp" sport="66" />
                    <opts> odev proto empty />
                </target>
            </chain>
        </combined_rule>
    </table>

  • <optlist> or the allowed variations: <opt>, <opts>, <option>, <options>

    This tag is only valid within a combined_rule tag. All iptables arguments can be used inside this tag. The list of valid arguments can be retrieved by running: ip-array show -sc ipt_args[,...].

    They can be used as attributes of the tag, or as content inside the tag. In the first form they do not need be enclosed inside quotes. Values with whitespace must be enclosed within double or single quotes. In both cases the left hand side (left of the `=') is the iptables argument and the right hand side is its value.

  • <template_rule> or the short form <tr>

    This tag defines one or more ruleblocks to be called with their corresponding templates. This is named a template rule.

    The syntax is:

    <template_rule> template-name ruleblock-name [ template-invocation-command ... ] </template_rule>
    or:
    <template_rule template="template-name" ruleblock="ruleblock-name" />

    For the first form multible entries may be separated by newline. Also one or more command(s) can be run at invocation of the ruleblock.

    Template rules will not inherit the global arguments (see below).

  • <pub_func> or the short form <f>

    This tag defines one or more public functions to be called.

    The syntax is:

    <pub_func name="function-name" />
    or
    <pub_func> function-name [ option ... ] </pub_func>

    For the second form multible entries must be separated by newline. Also it allows to pass parameters to the call of the function.

    The value part of the name attribute must be enclosed within quotes.

    Examples:

    <pub_func>
        log -S "Adding DROP rules"
        drop_dhcp
        drop_netbios
    </pub_func>

    <f name="lan_ftp" />

  • <ipsets> or the short forms: <s>, <set>, <ipset>

    This tag allows to define ipset sets. It is not valid inside any other but the root tag. Only attributes are allowed, no content.

    The syntax is:

    <ipsets name="set-name" [ type="set-type" ] [ (hashsize|family|maxelem|netmask|range|timeout|size)="value" ] [ (opt|opts|options)="option-name" ] >
        [ <elements> content </elements> ]
    </ipsets>
    or
    <ipsets import_xml="file-name" />

    For the first form the attributes name and type are mandatory when creating a set. If only elements are to be added using the <elements> tag, only the name of the set is required. All header options that require a value must be expressed using the form: option-name=value. All other header options must be put into the options attribute.

    For the second for a file can be imported. This file must be in the format as used with ipset -output xml.

    Examples:

    <set name="foo" type="hash:ip" family="inet" timeout="10000" options="counters comment" />
    
    <ipsets import_xml="${BASE_DIR}/stable/${CONF_DIR}/rules.d/import_ipsets.xml" />

  • <elements> or the short forms: <e>, <elem>, <element>

    This tags allows to add elements to an ipset set. It is of course only valid inside an <ipsets> tag (see above).

    The syntax is:

    <elements [ import_plain="file-name" ] >
        [ content ]
        [ ... ]
    </elements>

    The optional import_plain attribute is available inside this tag. It allows to import elements from a file. The file must contain one element per line. Shell style comments (#) are allowed.

    The syntax for content and inside the file is as with ipset without writing ipset add set-name ... When using the comment option and the comment contains spaces, it must be enclosed inside double quotes.

    Examples:

    <set name="foo" type="hash:ip" family="inet" timeout="10000" options="counters comment" >
        <elements import_plain="${BASE_DIR}/stable/${CONF_DIR}/rules.d/foo-elements.txt" >
            10.0.0.1 packets 3 comment "My sophisticated comment"
            10.0.0.2
        </elements>
    </set>
    
    <set name="foo">
        <elements>
            10.0.0.1 packets 3 comment "My sophisticated comment"
            10.0.0.2
        </elements>
    </set>

  • All other iptables arguments. We'll call them global arguments.

    The list of valid arguments can be retrieved by running: ip-array show -sc ipt_args[,...].

    These can be used to apply their value to all other rules following (grouping). Or to build rules by their own. In the second case, the closing of a tag will cause the creation of a rule. Except they are terminated by a <rule> or a <combined_rule>, in which case their closing will not cause additional rules to be created, unless a new tag is opened (and then closed afterwards to create a rule), which will start a new counter like before.

    Important

    They will not be applied to template rules!

    In example:

    <table name="filter">
        <chain name="INPUT">
            <rule> rule1 </rule>
            <rule> rule2 </rule>
        </chain>
    </table>

    Or in the relaxed way:

    <table> filter <chain name=INPUT>
        <rule> rule1 />
        <rule> rule2 />
    /> />

    Another example using only global arguments:

    <table> filter
        <chain> INPUT
            <target> ACCEPT
                <state> NEW,ESTABLISHED
                     <src> 1.1.1.1 </src>
                     <dst> 2.2.2.2 </dst>
                </state> </target>
            <target> DROP </target>
        </chain>
    </table>

See also

ip-array(8), ip-array.conf(8), ip-array_defaults.conf(8), ip-array_ruleblocks(5), ip-array_templates(5)