IP-Array 1.2.2 Reference Manual

Mart Frauenlob aka AllKind

AllKind

GPL v.2+

2016


Table of Contents

1. Introduction
About this document
About IP-Array
What is IP-Array?
Requirements
Goals
Features
Where to find IP-Array?
2. General Information
Naming conventions
Program logic
Starting behaviour
Error handling
Configuration validation
XML configuration file parsing
iptables jump tree
Routing
Directory structure
3. Installation
Installer
Upgrade
4. Configuration
Configuration files
Bash configuration files
Templates
Syntax
Template XML tags
Template usage guidelines
Ruleblocks
Syntax
Ruleblocks usage guidelines
inline functions
Rule files
Syntax
Rule file XML tags
Public functions
ipset usage
sysctl rule files
Syntax
sysctl rule file XML tags
5. Traffic shaping
6. Usage
Startup parameters and options
Parameters
Options
init script
Exit codes
Usage examples
7. Appendix
Troubleshooting
Support
Bug report
Co-Development

List of Tables

2.1. Example of Template and Ruleblock relationship
4.1. Configure networking interfaces
4.2. Local (LAN) name servers
4.3. ISP name servers
4.4. ISP SMTP servers
4.5. Local name servers (resolv.conf)
4.6. Local NTP servers
4.7. VPN_MAP structure

Chapter 1. Introduction

About this document

This document is the reference manual for IP-Array version 1.2.2.

It should provide all the information necessary to configure and use IP-Array.

About IP-Array

This section gives an overview about what IP-Array is, the requirements, features, goals and online availability.

What is IP-Array?

IP-Array is a command-line program (you may also say `script') written for bash (the bash shell www.gnu.org/software/bash).

It's purpose is to configure IPv4 firewalling and traffic shaping of a linux host.

To achieve this, IP-Array configures the linux kernels netfilter / traffic control subsystems via the userspace tools iptables / ipset / tc.

It also allows to load and / or unload netfilter related kernel modules and configure the kernel via the sysctl program.

Intended Audience: Advanced End Users, System Administrators.

Field of application: From a single host system to a multi-homed router or gateway.

Requirements

This list describes, what is necessary to use IP-Array:

  • Bash version 3.1 or higher.

  • Linux kernel 2.4 or higher.

  • Netfilter support enabled in the kernel.

  • Traffic control support enabled in the kernel (optional). In order to enable traffic shaping.

  • Some coreutils: cat, date, grep, mkdir, rm, sort, uname.

  • The iptables program.

  • The ipset program (optional) . Version 4.x to 6.27 are supported.

  • The iproute2 program (ip).

  • The lsmod and modprobe programs are required if IP-Array is configured to load and/or unload modules.

  • The tc program (optional). To enable traffic shaping.

  • The sysctl program. For system settings.

  • The logger utility (optional). To write messages to syslog.

  • The at utility.

  • The bc (bash calculator) utility.

  • The dialog or whiptail program. To create the dialogs in the interactive mode.

  • Decent understanding of the netfilter concept. Tables, chains (and their order of traversal). State match (conntrack) functionality.

  • Decent understanding of the traffic control concept (optional). Qdiscs (htb, sfq), classes, filters and how they work together.

  • Decent understanding of the `sysctl' networking (netfilter) options (optional)

Goals

  1. Provide a configuration interface to iptables, ipset, tc and sysctl.

  2. Allowing flexible configuration from simple to complex setups.

  3. Keep effective rule writing effort low, by just entering the desired values, or allow grouping of options.

  4. Stay as close as possible with the concept and naming of iptables / tc.

  5. Although (by now) it's not the main goal of IP-Array, provide some preset options for automatic configuration.

Features

  1. Avaliable iptables targets:

    • Supported in this version:

      AUDIT, CHECKSUM, CLASSIFY, CLUSTERIP, CONNMARK, CONNSECMARK, CT, DNAT, DSCP, ECN, HMARK, IDLETIMER, LED, LOG, MARK, MASQUERADE, NETMAP, NFLOG, NFQUEUE, QUEUE, RATEEST, RAWDNAT, RAWSNAT, REDIRECT, REJECT, SECMARK, SET, SNAT, TCPMSS, TCPOPTSTRIP, TEE, TOS, TPROXY, TTL, ULOG

    • The list of available targets can be retrieved by executing ip-array show -sc targets.

    • IP-Array supports any target that has no options.

    • No Target. It is possible to create rules without a target set, by specifying the target with the special string: `empty'.

  2. Available iptables match extensions:

    • Supported in this version:

      addrtype, ah, bpf, cluster, comment, connbytes, connlimit, connmark, conntrack, cpu, dccp, devgroup, dscp, ecn, esp, hashlimit, helper, iprange, ipvs, length, limit, mac, mark, multiport, nfacct, osf, owner, physdev, pkttype, policy, quota, rateest, realm, recent, rpfilter, sctp, set, socket, state, statistic, string, tcpmss, time, tos, ttl, u32

    • The list of available options can be retrieved by executing ip-array show -sc matches.

  3. Supported tables: filter, mangle, nat, raw, rawpost (xtables-addons), security.

  4. Template based rule structure definition (quite a huge list of predefined templates is provided out of the box) to build ruleblocks (stacks of rules, which just contain values).

  5. Definition of sysctl settings, templates, ruleblocks, iptables rules and ipset sets is done in a simple XML dialect.

  6. Options in rules can be grouped to save writing effort.

  7. An interactive mode, which is wizard based and allows to create (and edit in case of ruleblocks) configuration files.

  8. ipset integration. Older ipset versions (4.x, 5.x) are supported. Compatible with ipset v. 6 to 6.27+.

  9. Chain creation (by adding them in the CHAIN_MAP variable).

  10. Different modes of automatic `jump tree' creation in all tables.

  11. Allow an admin connection.

  12. Create stateful return traffic rules (ESTABLISHED, RELATED).

  13. Create final (terminating) rules. A chain termination option for builtin and IP-Array created chains, which allows to choose between different 'final rule' modes.

  14. Automatic configuration (rule generation) options for:

    • Policy

      Set the iptables builtin chains policy.

    • DNS

      1. Allow local host DNS lookups to specific name servers.

      2. Allow forwarded DNS lookups from specific LAN name servers to ISP name servers.

    • SMTP

      Allow SMTP traffic from specific LAN(s) to ISP mail servers.

    • NTP

      Allow time server queries from local host to specific NTP servers.

    • FTP

      Allow forwarded (optional active/passive) FTP traffic from specific LAN(s).

    • OUTPUT allow rules generation (bound to interfaces or primary IP addresses) if the policy is DROP.

    • IPSEC (VPN)

      Put all ipsec related traffic into the ipsec chain. Allow only packets from / to the configured VPN branches.

      An option is available to allow all traffic between the VPN branches.

    • Anti spoofing.

  15. Automated iptables logging options:

    • Globally log invalid TCP packets

    • Globally log packets in INVALID state

    • Log options (prefix, level, etc.) for the above listed.

  16. Automated iptables dropping options:

    • Globally drop invalid TCP packets

    • Globally drop packets in INVALID state

    • Reject AUTH (tcp port 113) on certain interfaces

    • Drop NETBIOS broadcasts on certain interfaces

    • Drop DHCP broadcasts on certain interfaces

    • Drop UPNP broadcasts on certain interfaces

  17. Traffic shaping capabilities:

    • Marking of packets in mangle table

    • Creation of htb and sfq qdiscs

    • Creation of tc classes and filters

    • Bulk OUTPUT and FORWARD qdiscs

    • Prioritizing of TCP SYN packets

  18. Prolog and epilog scripts

    Prolog and epilog scripts can be configured selectively for any startup mode.

  19. Loading and unloading of kernel modules (with optional parameters).

  20. Saving restore rulesets / commands / system state.

    There are various ways available to save the generated rulesets and or commands selectively (iptables, ipset, tc, modprobe, sysctl) or all at once. The saved files may be used to restore the configured system state.

  21. Different levels of IP-Array's output verbosity to the screen and or syslog can be set.

  22. Screen output can be colourized. Colours for different message categories can be defined by the user.

  23. Public functions

    IP-Array allows the usage of `public functions' in rule files. They may be used to log messages (giving the opportunity to totally customize IP-Array's log output), or call automatic rule creation functions.

  24. Different startup behaviour according to command line parameter. Including multiple options to save and / or restore generated rulesets or commands.

  25. A `test' mode to test new configurations.

  26. Automatic restoring of the previous ruleset on error when applying the new configuration.

  27. Bash completion compspec is included.

Where to find IP-Array?

Home page and download information

IP-Array is currently hosted at sourceforge.

The home page is reachable via: http://www.sf.net/projects/ip-array or http://ip-array.sf.net/.

IP-Array files are available for download at: sf.net.

There is a mirror on github: https://github.com/AllKind/ip-array.

Chapter 2. General Information

This Chapter provides information about the structure, functionality and program logic of IP-Array.

Naming conventions

  • rule

    A rule is either:

    1. An entity in an iptables or tc ruleblock. Defined by the user or program logic. Which will be read by IP-Array, in order to create one or more iptables or tc commands.

    2. An entity added by the `add_rule' function. Where the `add_rule' function may be used as `public function' or `inline function'. In order to create an iptables command.

    3. An entity in a XML iptables rule or combined rule.

    4. An entity in a XML ipset rule.

    5. An entity in a XML sysctl rule.

  • ruleblock

    A ruleblock is a group (stack) of iptables rules, containing only the values of each option, to be read in order of occurence.

    The structure of the ruleblock is defined in a template.

  • template

    A template describes the structure of a ruleblock.

    Each rule entry in a ruleblock is interpreted column-wise. How the values in each column are interpreted, is defined in the template called with the ruleblock.

    The following example will show how a rule in a ruleblock, structured according to the definitions in a template, may look:

    Table 2.1. Example of Template and Ruleblock relationship

    Template definition:jump_targetipt_chaininput_devicesource_address
    According ruleblock rule:DROPINPUTeth010.0.0.10

Program logic

Starting behaviour

If IP-Array is run with the `start' parameter, a lockdown mode is enforced until the configuration is read and all iptables, ipset, tc and sysctl rules have been generated. During this lockdown mode only localhost and the administrator connection are allowed. After all rules are collected, they are applied at once. If the config variable RESTORE_ON_START is set to `1' and the previously saved ruleset is available, those will be sourced and thus activated immediatly.

In any other mode, that actually runs commands to configure the system, IP-Array will not touch the currently active iptables, tc rules or sysctl configuration until all rules and / or commands have been generated.

After all rules / commands are collected, they are applied at once. This should keep the time, the system is in an unconfigured or partly configured state, to a minimum. Allowing to catch configuration errors, before changing the systems state.

The behaviour for kernel modules is different. Module probing (if configured at all) is done every time IP-Array loads. To avoid reloading modules on an already running system, modules will only be loaded if they are not loaded already. If running in a mode that does not apply commands like i.e. `dry-run', then module probing is not actually perfomed, but done with `modprobe -n'. Alternativly the module probing can be disabled by using the `-nm' startup option.

Error handling

In the main configuration file a variable named EXIT_ON_ERROR exists to control IP-Arrays behaviour on errors. If it set to `1', the program will exit on any configuration and command apply error it can detect. In case the system state has already been changed by, either loading / unloading modules, or changing sysctl settings, IP-Array will try to revert those changes. If iptables commands have already been applied, a lockdown mode will be enforced first, before attempting a restore. All policies will be set to DROP and all chains get emptied. Depending on the configuration, only the current administrative connection (if present taken from the bash environment variable SSH_CONNECTION, or if not, if configured from the configuration variable ADMIN_CONNECTION) and localhost traffic (configuration variable ALLOW_LOOPBACK) may be allowed. If EXIT_ON_ERROR is set to `0', IP-Array only sends error messages and keeps on going.

Autosave / restore

If IP-Array is started with one of the following parameters: open, restart, or tc-start it will automatically save the current iptables ruleset using iptables-save to a temporary file. In case an error occurs while processing the configuration, this ruleset will be restored. This behaviour can be turned off, by using the startup option -na | --no-autosave. If the configuration variable IPTSAVE_FAILS is set to `1' automatic saving / restoring will also not take place.

Important

The restore procedure may even occur after an error condition lockdown (as described above) was inforced. This is done as something could go wrong with the restore process. Better have a lockded down system than one with an unkown and most likely messed up state.

Configuration validation

Every configuration variable, as well as every rule set by the user, will be validated for sane entries. For example IP addresses, port and protocol specifications, etc. are checked for valid values. If a bad value is detected, according messages will be displayed and the rule entry will be ignored. IP-Array may also quit further processing, if it is configured to exit on errors.

XML configuration file parsing

As IP-Array starts, it looks if it can find previously already compiled bash scripts for templates, rules and ruleblocks. If those are found, they will be read and no XML file parsing will be done. Otherwise the XML configuration files will be parsed, interpreted and the according bash scripts will be compiled. There are startup parameters available to force XML parsing globaly, or selectively for templates, rules and ruleblocks.

iptables jump tree

A jump tree is a set of chains and jump instructions starting from the builtin iptables chains, in order to quickly sort out traffic and to find a terminating rule as soon as possible. The desired jump tree behaviour can be configured using the JUMP_TREE variable in the main configuration file.

Per interface classified jump tree

IP-Array may create chains between every network interface configured in NET_INTERFACES. Means if you define two interfaces i.e: eth0 and eth1, IP-Array will create two chains named: 'eth0_to_eth1' and 'eth1_to_eth0'. And so on for every additional interface. This can be done for all tables according to the configuration. In example for the filter table the FORWARD chain then is filled with jump entries, seeding out the cross-interface traffic to the appropriate chain. Means every packet entering the FORWARD chain will end up in one of those chains created by IP-Array. This should minimize the amount of rules to pass before reaching the matching rule. IP-Array always uses those cross-interface chains when it applies rules in the FORWARD chain. In case of a rule without an interface definition, or an interface wildcard i.e: 'eth+', or an inverted interface value i.e: '!eth0' is used, the target chain will be FORWARD, instead of the cross-interface chains. Rules with chain values not matching builtin chains will not be touched.

Just like with the cross-interface chains, INPUT and OUTPUT packets are also classified by interface. For each network interface configured, INPUT and OUTPUT chains will be created. For example if one interface named 'eth0' is present, the chains 'INPUT_eth0', 'OUTPUT_eth0' and the according jump entries will be created automatically.

Per network jump tree

The jump tree creation is also available for networks defined in NET_INTERFACES. For every network IP-Array will create the according INPUT, OUTPUT, PREROUTING (just named PRE), POSTROUTING (just named POST) (depending on the active table) chains prefixed with `NETWORK-NAME_'. The FORWARD chains will be named NETWORK-NAME_FWD_IN and NETWORK-NAME_FWD_OUT. IP-Array will try to place rules into those chains by selecting on source address, destination address, input device and output device. Rules with chain values not matching builtin chains will not be touched.

Combined network and interface jump tree

There also is a combined method of the both above mentioned. First select upon interface and then jump into network chains attached to those interfaces.

Routing

IP-Array does not touch your routing tables at all!

Directory structure

This is the description of the dicretory structure IP-Array uses, some of them can be altered by editing variables in the defaults configuration file:

BASE_DIR

Base directory for IP-Array.

Default location of the saving directory and `stable' and `test' (RUNMODE) directory.

i.e. `/usr/local/etc/ip-array/'

BIN_DIR

Directory to put the main IP-Array executable into.

i.e. `/usr/local/bin/ip-array/'

LIB_DIR

Directory to put the IP-Array function files into.

i.e. `/usr/local/lib/ip-array/'

HELP_DIR

Directory containing help files.

HELP_DIR="${BASE_DIR}/help.d"

CONFIG_DIR

Directory containing configuration files and sub-directories.

CONFIG_DIR="${BASE_DIR}/${RUNMODE}/conf.d"

RULE_DIR

Directory to put the rule files into.

RULE_DIR="${CONFIG_DIR}/rules.d"

SYSCTL_DIR

Directory to put the sysctl rule files into.

SYSCTL_DIR="${CONFIG_DIR}/sysctl.d"

RULEBLOCK_DIR

Directory to put the ruleblock configuration files into.

RULEBLOCK_DIR="${CONFIG_DIR}/ruleblocks.d"

TEMPLATE_DIR

Directory to put the template configuration files into.

TEMPLATE_DIR="${CONFIG_DIR}/templates.d"

SAVE_DIR

Directory used to save commands, scripts or rulesets.

SAVE_DIR="${BASE_DIR}/save.d"

SCRIPT_DIR

Directory for the prolog / epilog scripts.

SCRIPT_DIR="${BASE_DIR}/${RUNMODE}/scripts.d"

TEMPLATE_REPOSITORY

Directory where all the templates that come with IP-Array are stored . By default it is /usr/share/ip-array/template_repo.d.

Chapter 3. Installation

Table of Contents

Installer
Upgrade

Installer

An installation program comes with IP-Array. It is called install.bash and allows to install all necessary files at once. Also the destination directories can be given as well as the file ownership can be set. It's also possible to create a backup of the old files. The installer utilises the install program, for more information about it consult its man page.

The installer creates a log file about the installation. This will be used by the uninstall.bash script, to uninstall IP-Array.

After installation you need to configure variables in the header of the init script. Telling the path to the defaults file and to the IP-Array executable. Maybe you need to adjust some path and programs settings in the defaults file. Then you can start to configure the main configuration file. There the NET_INTERFACES variable must be configured, before IP-Array is ready to run.

Upgrade

Note

There is no upgrade path from older ip-array versions (0.05.xx) available, but in the examples directory there is a set of rule and ruleblock files, which mimics the old configuration almost completely.

Important

Always create a backup before installing a new version! Configuration files will be overwritten with the default ones!

Chapter 4. Configuration

This chapter provides information about how to configure IP-Array.

Configuration files

IP-Array comes with two different kinds of configuration files. Some are written in shell, namely bash, syntax, while others are written in a simple XML dialect. The templates, ruleblocks and rule files are in XML language. All others are written in bash.

Note

All the configuration files are expected to be in the CONFIG_DIR directory, or one of it's sub directories, of the current runmode. If IP-Array is run with the 'test' startup parameter the location will be: $BASE_DIR/test/conf.d. In any other startup mode it will be: $BASE_DIR/stable/conf.d.

Bash configuration files

Description of the bash (shell) configuration files

init script

There is a configuration area in the IP-Array init script. The following variables can be configured there:

DEFAULTS_FILE

Mandatory: no - defaults to /etc/ip-array/ip-array_defaults.conf.

Allowed values: A valid path to the defaults file (i.e: /etc/default/ip-array).

Purpose: The defaults file holds startup and globally used variables.

BIN_DIR

Mandatory: no - defaults to /usr/bin.

Allowed values: A valid path to the directory holding the executable file (i.e: /usr/bin).

EXE_NAME

Mandatory: no - defaults to ip-array.

Allowed values: The name of the executable file (i.e: ip-array).

DEFAULT_OPTIONS

Mandatory: no

Allowed values: startup parameters of IP-Array.

Purpose: These parameters will be used in any starting mode of IP-Array.

DEFAULT_START_OPTIONS

Mandatory: no

Allowed values: startup parameters of IP-Array.

Purpose: These parameters will be used in the `start' starting mode of IP-Array.

DEFAULT_STOP_OPTIONS

Mandatory: no

Allowed values: startup parameters of IP-Array.

Purpose: These parameters will be used in the `stop' starting mode of IP-Array.

MY_SHELL

Mandatory: no - defaults to the value defined with the variable $BASH (default: /bin/bash).

Allowed values: A valid path to the shell to run IP-ARRAY with (i.e: /bin/bash).

Defaults (ip-array_defaults.conf)

The defaults file contains startup and globally used variables.

Important

The location of the defaults file is specified in the IP-Array init script.

The `DEFAULTS_FILE' variable must be pointing to the defaults file.

IP-Array message (logging) output settings
ENABLE_COLORS

Mandatory: no. Defaults to `0' if unset.

Allowed values: `0' or `1'.

Purpose: Enable or disable IP-Array coloured output.

ENABLE_SYSLOG

Mandatory: no. Defaults to `0' if unset.

Allowed values: `0' or `1'.

Purpose: Enable or disable logging of IP-Array's output to syslog using the logger utility.

LOG_FACILITY

Mandatory: no. Defaults to `local0' if unset.

Allowed values: auth, authpriv (for security information of a sensitive nature), cron, daemon, ftp, kern, lpr, mail, news, security (deprecated synonym for auth), syslog, user, uucp, local0 to local7 inclusive.

Purpose: Configure IP-Array's syslog logging facility.

VERBOSE

Mandatory: no. Defaults to `6' if unset.

Allowed values: `0' to `8'.

Purpose: Control level of IP-Array's output verbosity.

Tip

With a non zero environment variable `DEBUG_INFO', additional processing (debugging) information is printed.

  1. No messages are shown. Exit status indicates success or failure.

  2. Shows start and end message and errors.

  3. Main title and warning messages are also shown.

  4. Sub title messages are shown in addition.

  5. Info title, config and rule file loading messages, are shown additionally.

  6. Also show notice messages.

  7. Verbose output.

  8. Also show IP-Array internals.

  9. Debug mode (set -x).

    Tip

    With a non zero environment variable `DEBUG_INFO', a debugging `PS4' is set.

  10. More verbose debug mode (set -vx).

SYSLOG_VERBOSE

Mandatory: no. Defaults to `1' if unset.

Allowed values: `0' to `6'.

Purpose: Control verbosity level of IP-Array's syslog logging.

  1. Errror messages are shown.

  2. Main title and warning messages are shown.

  3. Subtitle messages are shown in addition.

  4. Info title, config and rule file loading messages, are shown additionally.

  5. Also show notice messages.

  6. Verbose output.

  7. Also show IP-Array internals.

COLOR_MSG_MAIN_TITLE

Mandatory: no. Defaults to `magenta' if unset.

Allowed values: black, blue, cyan, green, magenta, red, white, yellow.

Purpose: Set color for title messages.

COLOR_MSG_SUBTITLE

Mandatory: no. Defaults to `blue' if unset.

Allowed values: black, blue, cyan, green, magenta, red, white, yellow.

Purpose: Set color for sub title messages.

COLOR_MSG_INFO_TITLE

Mandatory: no. Defaults to `cyan' if unset.

Allowed values: black, blue, cyan, green, magenta, red, white, yellow.

Purpose: Set color for info title messages.

COLOR_MSG_ERROR

Mandatory: no. Defaults to `red' if unset.

Allowed values: black, blue, cyan, green, magenta, red, white, yellow.

Purpose: Set color for error messages.

COLOR_MSG_WARNING

Mandatory: no. Defaults to `yellow' if unset.

Allowed values: black, blue, cyan, green, magenta, red, white, yellow.

Purpose: Set color for warning messages.

COLOR_MSG_NOTICE

Mandatory: no. Defaults to `white' if unset.

Allowed values: black, blue, cyan, green, magenta, red, white, yellow.

Purpose: Set color for notice messages.

COLOR_MSG_CONFIG_LOAD

Mandatory: no. Defaults to `green' if unset.

Allowed values: black, blue, cyan, green, magenta, red, white, yellow.

Purpose: Set color for configuration file loading messages.

COLOR_MSG_RULE_LOAD

Mandatory: no. Defaults to `yellow' if unset.

Allowed values: black, blue, cyan, green, magenta, red, white, yellow.

Purpose: Set color for rule file loading messages.

Programs mandatory to run IP-Array
AUTO_GET_PROGS

Mandatory: no - defaults to `1'.

Allowed values: `0' or `1'.

Purpose: Configure if IP-Array should try to automatically find the mandatory programs (must be in $PATH) . If disabled (set to `0'), the program names varaibles (below) must be configured manually.

AT

Mandatory: yes

Allowed values: A valid path to the at executable file (i.e: /usr/bin/at), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

CAT

Mandatory: yes

Allowed values: A valid path to the cat executable file (i.e: /bin/cat), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

DATE

Mandatory: yes

Allowed values: A valid path to the date executable file (i.e: /bin/date), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

DIALOG

Mandatory: no (only in interactive mode a dialog program is required, which can be either dialog or whiptail)

Allowed values: A valid path to the dialog executable file (i.e: /usr/bin/dialog), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

DIFF

Mandatory: yes

Allowed values: A valid path to the diff executable file (i.e: /usr/bin/diff), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

FIND

Mandatory: yes

Allowed values: A valid path to the find executable file (i.e: /usr/bin/find), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

GREP

Mandatory: yes

Allowed values: A valid path to the grep executable file (i.e: /bin/grep), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

IP

Mandatory: yes

Allowed values: A valid path to the ip executable file (i.e: /sbin/ip), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

IPSET

Mandatory: no

Allowed values: A valid path to the ipset executable file (i.e: /sbin/ipset), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

IPT

Mandatory: yes

Allowed values: A valid path to the iptables executable file (i.e: /sbin/iptables), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

LOGGER

Mandatory: no

Allowed values: A valid path to the logger executable file (i.e: /usr/bin/logger), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

LSMOD

Mandatory: yes

Allowed values: A valid path to the lsmod executable file (i.e: /sbin/lsmod), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

MODPROBE

Mandatory: yes

Allowed values: A valid path to the modprobe executable file (i.e: /sbin/modprobe), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

NFACCT

Mandatory: no

Allowed values: A valid path to the nfacct executable file (i.e: /usr/sbin/nfacct), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

RM

Mandatory: yes

Allowed values: A valid path to the rm executable file (i.e: /bin/rm), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

IPT_SAVE

Mandatory: yes

Allowed values: A valid path to the iptables-save executable file (i.e: /sbin/iptables-save), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

This variable is only used by the IP-Array init script. It is not globally available.

IPT_RESTORE

Mandatory: yes

Allowed values: A valid path to the iptables-restore executable file (i.e: /sbin/iptables-restore), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

This variable is only used by the IP-Array init script. It is not globally available.

SORT

Mandatory: yes

Allowed values: A valid path to the sort executable file (i.e: /usr/bin/sort), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

SYSCTL

Mandatory: yes

Allowed values: A valid path to the sysctl executable file (i.e: /sbin/sysctl), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

TC

Mandatory: no

Allowed values: A valid path to the tc executable file (i.e: /sbin/tc), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

UNAME

Mandatory: yes

Allowed values: A valid path to the uname executable file (i.e: /bin/uname), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

WHIPTAIL

Mandatory: no (only in interactive mode a dialog program is required, which can be either dialog or whiptail)

Allowed values: A valid path to the whiptail executable file (i.e: /usr/bin/whiptail), or the just the name of the program, if it's found in $PATH and you do not want to use absolute paths.

Files and directories
BASE_DIR

Mandatory: no - defaults to /etc/ip-array.

Allowed values: A valid path (i.e.: /etc/ip-array).

IP-Array base directory.

CONFIG

Mandatory: no - defaults to ip-array.conf.

Allowed values: A valid filename (i.e.: ip-array.conf).

Name of the main configuration file.

CONF_DIR

Mandatory: no - defaults to conf.d.

Allowed values: A valid directory name (i.e.: conf.d).

Configuration directory must be below BASE_DIR.

LIB_DIR

Mandatory: no - defaults to /usr/lib/ip-array.

Allowed values: A valid path (i.e.: /usr/lib/ip-array).

Library directory used for the IP-Array function files.

LOCK_DIR

Mandatory: no - defaults to /var/run.

Allowed values: A valid path (i.e.: /var/run).

Directory to put the IP-Array PID file into.

SHARE_DIR

Mandatory: no - defaults to /usr/share/ip-array.

Allowed values: A valid path (i.e.: /usr/share/ip-array).

Data directory.

SAVE_FILE

Mandatory: no - defaults to iptables_ruleset.save.

Allowed values: A valid filename (i.e.: iptables_ruleset.save).

File to save the ruleset into. Applies to all the save* parameters.

IPSET_SAVE_FILE

Mandatory: no - defaults to ipset_ruleset.save.

Allowed values: A valid filename (i.e.: ipset_ruleset.save).

File to put the ipset save output into, when executing IP-Array with the 'save' startup parameter. Or to load, when restoring with the 'restore' parameter.

RULESETFILE

Mandatory: no - defaults to ip-array_commands.bash.

Allowed values: A valid filename (i.e.: ip-array_commands.bash).

File where the generated commands will be saved, if executing IP-Array with one of the 'save[ -iptables | -modprobe | -sysctl | -tc | -shaping ]-commands' parameters. The target directory will be $BASE_DIR/save.d.

DIFF_FILE

Mandatory: no - defaults to iptables_ruleset_saved_for_diff.

Allowed values: A valid filename (i.e.: iptables_ruleset_saved_for_diff).

File to save the iptables rule listing (iptables -S, or if not available on old systems -nL) into, after applying the rules. The target directory will be $BASE_DIR/save.d.

This file will be used to check for a difference to the currently active ruleset, when using the 'diff-last-activated' startup parameter.

SERVICES

Mandatory: no - defaults to /etc/services.

Allowed values: A valid path to the services file (most likely: /etc/services).

Purpose: Configure the location of the services file (containing service definitions).

PROTOCOLS

Mandatory: no - defaults to /etc/protocols.

Allowed values: A valid path to the services file (most likely: /etc/protocols).

Purpose: Configure the location of the protocols file (containing protocol definitions).

Quick start settings

Files to load, if RESTORE_ON_START is `1'.

KNOWN_GOOD_RULESET

Mandatory: no - defaults to KNOWN_GOOD_RULESET.save.

Allowed values: A valid filename (i.e.: KNOWN_GOOD_RULESET.save).

File to save the currently active 'known good' ruleset. This file will be used to restore the ruleset on 'start', if RESTORE_ON_START is enabled.

RESTORE_ON_START

Mandatory: no - defaults to `0'.

Allowed values: `0' to disable `1' to enable.

Loads the ruleset saved into $KNOWN_GOOG_RULESET, if IP-Array is loaded with the `start' parameter (faster startup also called quick start).

Basic configuration variables
RELOAD_TIME

Mandatory: no - defaults to 7.

Allowed values: Any value greater than 1.

Time period until the previously saved ruleset will be restored, when using the 'test' startup parameter, or the -t | --test option.

Warning

If iptables-save or iptables-restore fails for some reason, the 'test' parameter will not work, thus this setting will not produce the desired effect.

GEN_FORMAT

Mandatory: no - defaults to `cmd'.

Allowed values: `cmd': generated commands will be save as list of commands. ´ipt': generated commands will be used in iptables-save format (faster loading time).

IPTSAVE_FAILS

Mandatory: no - defaults to `0'.

Allowed values: `0' or `1'.

Enable this if saving or restoring with iptables-save or iptables-restore fails for some reason.

Important

Any startup mode, that utilizes iptables-save or iptables-restore will not work in that case.

USE_IPSET

Mandatory: no - defaults to `0'.

Allowed values: `0' or `1'.

Enable or disable the usage of ipset.

MAX_SETS

Mandatory: no - defaults to `256'.

Allowed values: The value compiled into your kernel.

The maximal amount of ipset sets to create.

SYNTAX_CHECK

Mandatory: no - defaults to `1'.

Allowed values: `0' or `1'.

Purpose: Perform a bash grammar check before sourcing or executing files. The bash grammar check is done using `bash -n file'. Thus the syntax check is very basic and may not catch all errors (as described in `man bash').

DIALOG_PROG

Mandatory: no - defaults to `$DIALOG'.

Allowed values: empty (make sure one of the variables DIALOG, or WHIPTAIL is defined, or automatic detection of programs - if enabled - can find them). `dialog' or `whiptail'. The full path to one of them.

Purpose: The interactive mode requires a dialog program. Either dialog (version 1.2+) or whiptail are supported.

Main configuration file (ip-array.conf)

This file is the main IP-Array configuration file.

CONFIG_FILES

Names of the configuration files which will be loaded in order of appearence. i.e. CONFIG_FILES="aliases.conf global.conf".

Tip

This is the only variable that needs to be inside the main configuration file. All others can be placed into different files of your choice and should be listed in the above variable, in order to be sourced from there.

BASE_TEMPLATES

Names of the basic XML template files.

ENABLE_FILTER

Enable or disable loading of the iptables filter table configuration. Valid values are `0' or `1'.

IPT_FILTER_TEMPLATES

Names of the iptables filter table XML templates files.

FILTER_RULEBLOCKS

Names of the iptables filter table ruleblocks files.

FILTER_RULES

Names of the iptables filter table rule files.

ENABLE_MANGLE

Enable or disable loading of the iptables mangle table configuration. Valid values are `0' or `1'.

IPT_MANGLE_TEMPLATES

Names of the iptables mangle table XML templates files.

MANGLE_RULEBLOCKS

Names of the iptables mangle table ruleblocks files.

MANGLE_RULES

Names of the iptables mangle table rule files.

ENABLE_NAT

Enable or disable loading of the iptables nat table configuration. Valid values are `0' or `1'.

IPT_NAT_TEMPLATES

Names of the iptables nat table XML templates files.

NAT_RULEBLOCKS

Names of the iptables nat table ruleblocks files.

NAT_RULES

Names of the iptables nat table rule files.

ENABLE_RAW

Enable or disable loading of the iptables raw table configuration. Valid values are `0' or `1'.

IPT_RAW_TEMPLATES

Names of the iptables raw table XML templates files.

RAW_RULEBLOCKS

Names of the iptables raw table ruleblocks files.

RAW_RULES

Names of the iptables raw table rule files.

ENABLE_RAWPOST

Enable or disable loading of the iptables rawpost table configuration. Only works if xtables-addons are installed. Valid values are `0' or `1'.

IPT_RAWPOST_TEMPLATES

Names of the iptables rawpost table XML templates files. Only works if xtables-addons are installed.

RAWPOST_RULEBLOCKS

Names of the iptables rawpost table ruleblocks files. Only works if xtables-addons are installed.

RAWPOST_RULES

Names of the iptables rawpost table rule files. Only works if xtables-addons are installed.

ENABLE_SECURITY

Enable or disable loading of the iptables security table configuration. Valid values are `0' or `1'.

IPT_SECURITY_TEMPLATES

Names of the iptables security table XML templates files.

SECURITY_RULEBLOCKS

Names of the iptables security table ruleblocks files.

SECURITY_RULES

Names of the iptables security table rule files.

IPSET_RULES

Names of the ipset rule files. These ipset rules are table independent.

MODULE_DIR

Patch to the kernels module directory. Defaults to /lib/modules/$(uname -r).

MODULES_TO_LOAD

Select the kernel modules to load. Entries are separated by newline.

Format:

module-name [parameters [...]]
MODS_TO_RM

Select the kernel modules to remove.

LOOPBACK_IF

Allowed values: A valid interface name. Defaults to `lo' if unset.

Purpose: Name of the loopback interface.

NET_INTERFACES

This variable must be configured with at least one interface. Any network interface but `lo' (localhost) may be put here.

If you use a VPN software that creates an interface (named i.e. ipsec) you need to put it in as a separate entry. Otherwise use the available types:

ext | local | ipsec

ext = an external interface, local = a local interface, ipsec = an ipsec interface

Example:

Table 4.1. Configure networking interfaces

Inteface nameInterface aliasType[:ipsec]Network name
eth0eth0ext:ipsecINET_CON_X
eth1eth1extINET_CON_Y
eth2eth2localPRODUCTION
eth2eth2:0localDEVELOPMENT
eth3eth3localDMZ
ipsec0ipsec0ipsecVPN_REMOTE_OFFICE


SCRIPT_MAP

The purpose of this variable is to configure which scripts will run at what startup mode.

The format is (newline separates entries):

startup-parameter-name[,...] { prolog | epilog } script-name { prolog | epilog } script-name

Example:

start,restart prolog my_start_prolog-script epilog my_start_epilog-script

POLICY_MAP

The purpose of this variable is to configure the policy for buitin iptables chains.

The format is (newline separates entries):

table chain policy

Example:

filter INPUT DROP

filter OUTPUT ACCEPT

ALLOW_LOOPBACK

Allow communication to and from the loopback interface. Valid values: `0' or `1'.

ADMIN_CONNECTION

Define an administrative connection, which will be allowed under certain conditions. The conditions are:

  • If the enviroment variable $SSH_CONNECTION is not available, otherwise those values will always be used.

  • When IP-Array enters lockdown mode in start mode.

  • In restore mode, if ipset is used.

  • In lockdown mode.

  • On a fail condition (an error occured while applying a ruleset).

The format is:

admin_source-IP local_destination-IP local_destination-port
CHAIN_MAP

The purpose of this variable is to create custom iptables chains.

The format is (newline separates entries):

table chain-name [...]

Example:

filter chain1 chain2

mangle mchain1 mchain2

JUMP_TREE

The purpose of this variable is to create an automated jump tree of iptables chains.

The format is:

{ none | interface | netname | netname+interface } { table-name [...] | all }

`none' disables jump tree creation (undefined variable does the same).

`interface' means to create a jump tree categorised by interfaces.

`netname' means to create a jump tree categorised by networks.

`netname+interface' means to create a jump tree categorised by interfaces and their networks.

`table' defines in which table the jump tree will be created. A value of `all' will cause creation in all tables.

Examples:

JUMP_TREE="interface filter mangle"

JUMP_TREE="netname all"

JUMP_TREE_CHAINS_CREATE_ALL

Valid values: `0' or `1'.

Enable or disable automatic creation of all jump tree chains.

REMOVE_EMPTY_CHAINS

Valid values: `0' or `1'.

Remove empty chains after applying the ruleset.

REMOVE_UNREF_CHAINS

Valid values: `0' or `1'.

Remove unreferenced chains after applying the ruleset.

KNOWN_TRAFFIC_MAP

This allows to define which and where the rules are created, which deal with the return traffic identified by the connection tracker. The format is (newline separates entries):

chain [ state ] [ top | bottom ]

state can be either E, R or ER (ESTABLESHED, RELATED or ESTABLISHED and RELATED). top or bottom define wheter the rule should be placed on top or bottom of the rule stack.

REVERSE_INPUT_RULES_REQUIRED

Valid values: `0' or `1'.

In a ruleblock which uses a template definition that uses the reverse (return) mode to generate bidirectional rules, define if those are needed (i.e. KNOWN_TRAFFIC_MAP is not used). This applies to traffic entering the INPUT chain.

REVERSE_FORWARD_RULES_REQUIRED

Valid values: `0' or `1'.

In a ruleblock which uses a template definition that uses the reverse (return) mode to generate bidirectional rules, define if those are needed (i.e. KNOWN_TRAFFIC_MAP is not used). This applies to traffic entering the FORWARD chain.

FINAL_RULE_MAP

Define a terminating rule for custom or builtin chains. Format:

chain action [ limit ] [ burst ] [ log-level ] [ log-options ]

chain = the name of the chain. action = Can be one of: log, drop, reject, logdrop, logreject. See the help of the iptables arguments for the other entries (ip-array show -sc ipt_args:limit,log-level,log-options). The default value for limit is defined with GLOBAL_LOGLIMIT and the burst value uses the default of GLOBAL_BURSTLIMIT.

LOG_INVALID

Valid values: `0' or `1'.

Log packets in invalid state. The logging options are defined with the global log options.

BLOCK_INVALID

Valid values: `0' or `1'.

Drop packets in invalid state.

LOG_ILLEGAL

Valid values: `0' or `1'.

Log illegal TCP packets. The logging options are defined with the global log options.

BLOCK_ILLEGAL

Valid values: `0' or `1'.

Drop illegal TCP packets.

LAN_FTP

Select LAN interface from where FTP traffic is permitted. Format (whitespace separates entries):

lan-interface|netname[:external-interface|netname][:active|passive|all|none] [...]

i.e. eth1:eth0:active or eth2 or LAN::passive

LAN_NS

Allow DNS (udp and tcp) traffic from nameservers inside one or more local networks to ISP nameservers. Needs the LAN_NS and ISP_NS variables to be defined. Purpose: Define name servers (DNS) that are part of a local area network.

Table 4.2. Local (LAN) name servers

Network nameName server IP address[Name server MAC address]
DMZ10.11.11.11AA:BB:CC:DD:EE:FF
DMZ10.11.11.12 


ISP_NS

Allow DNS (udp and tcp) traffic from nameservers inside one or more local networks to ISP nameservers. Needs the LAN_NS and ISP_NS variables to be defined. Purpose: Define the Internet service provider name servers (DNS), for each local area network.

Table 4.3. ISP name servers

Network nameISP name server IP address[,...][External network interface]
PRODUCTION123.12.12.22,123.12.12.23eth1
DEVELOPMENT124.13.13.23,124.13.13.24 


ISP_SMTP

Allow SMTP traffic from inside one or more local networks to SMTP mailservers. Needs the lan_isp_smtp public function to be called in the rule file.

Table 4.4. ISP SMTP servers

Network nameISP mail server IP address[,...][External network name]
PRODUCTION123.12.12.90,123.12.12.91INET_CON_ISP_X
DEVELOPMENT125.25.25.5,125.25.25.6INET_CON_ISP_Y
DMZ126.26.26.6,128.28.28.8 


RESTRICT_OUTPUT

Valid values: `0', `1, ´IFBOUND' or `IPBOUND'.

If the policy for the OUTPUT chain is set to DROP, additional allow rules may be applied. A value of `1' will allow other configurations like allow rules for local name or time servers. A value of ´IFBOUND' will create OUTPUT allow rules per interface i.e. -A OUTPUT -o eth0 -j ACCEPT. While setting it to `IPBOUND' will cause creation of one allow rule per IP address configure on each interface.

REST_OUT_DNS_ALLOW

Valid values: `0' or `1'.

If RESTRICT_OUTPUT is set to `1' and the policy of the OUTPUT chain is DROP, then rules will be created to allow localhost to nameservers traffic .

LOCAL_NS

Purpose: Define name servers (DNS) of the local system (most likely those configured in /etc/resolv.conf.

If set to `auto', then IP-Array will try to read the nameservers from /etc/resolv.conf. Otherwise the following formatting is used:

Table 4.5. Local name servers (resolv.conf)

Name server IP address[External network name]
123.12.12.22,123.12.12.23INET_CON_ISP_X
124.13.13.23,124.13.13.24 


REST_OUT_NTP_ALLOW

Valid values: `0' or `1'.

If RESTRICT_OUTPUT is set to `1' and the policy of the OUTPUT chain is DROP, then rules will be created to allow localhost to time servers traffic .

TIME_SERVERS

Purpose: Define time service request (NTP) of the local system.

If set to `auto', then IP-Array will try to read the ntp servers from /etc/ntp.conf. Note that host names are not supported! Otherwise the following formatting is used:

Table 4.6. Local NTP servers

NTP server IP address[,...][External network name]
11.12.13.14,12.13.14.15INET_CON_ISP_X
99.99.99.9,99.99.99.10 


REST_OUT_LAN_ALLOW

Valid values "lan-interface [...]"

If RESTRICT_OUTPUT is set to `1' and the policy of the OUTPUT chain is DROP, then rules will be created to allow traffic to the subnets configured .

REST_ALLOW_RELATED

Valid values: `0' or `1'.

If RESTRICT_OUTPUT is set to `IFBOUND' or ´IPBOUND' and the policy of the OUTPUT chain is DROP, setting this variable to `0' will allow only traffic in ESTABLISHED state, while setting it to `1' will allow traffic in ESTABLISHED and RELATED state.

DROP_DHCP

Drop DHCP broadcasts to certain interfaces. Allowed values are interface-names.

DROP_UPNP

Drop UPNP broadcasts to certain interfaces. Allowed values are interface-names.

LOG_PREFIX

A prefix for iptables log entries.

Tip

Use a short value, log entries have a limited lenght.

GLOBAL_LOGLIMIT

An iptables logging limit parameter that will be used globally, wherever it's not specified / requested differently. Defaults to 1/s (1 per second).

GLOBAL_BURSTLIMIT

An iptables logging limit-burst parameter that will be used globally, wherever it's not specified / requested differently. Defaults to `3'.

GLOBAL_LOGLEVL

Valid values are: alert, crit, debug, emerg, err, info, notice and warning. Defaults to `info'.

An iptables logging loglevel parameter that will be used globally, wherever it's not specified / requested differently.

ENABLE_IPSEC

Valid values: `0' or `1'.

Enable or disable the IPSEC rules.

ALLOW_ALL_BRANCH

Valid values: `0' or `1'.

Allow all traffic between all VPN branches.

LOCAL_BRANCH

Allowed values: Characters of class [:word:] (alphanumeric and the `_' (underline) character).

Purpose: Set name of the local VPN branch.

IPSEC_RULES

The IPSEC rule files.

VPN_MAP

This variable holds the vpn branch data.

The VPN_MAP variable is structured as follows (example data provided):

Table 4.7. VPN_MAP structure

Branch nameExternal IP addressLAN address/maskLAN interface IP address
local_branch188.88.88.8192.168.1.0/24192.168.1.1
remote_branch_01177.77.77.710.1.1.0/2410.1.1.1
remote_branch_02166.66.66.6172.16.1.0/24172.16.1.1


ENABLE_TC_SHAPING

Valid values: `0' or `1'.

Enable or disable traffic shaping rules.

TC_MARK_RULES

Files holding the iptables MARK and CLASSIFY rules for the traffic shaping.

OUTPUT_BULK

Formatting:

output-interface:mark [...]

Put the matching packets into the output bulk queue disc.

FORWARD_BULK

Formatting:

input-interface,output-interface:mark [...]

Put the matching packets into the forward bulk queue disc.

PRIORITIZE_SYN

Valid values: `0' or `1'.

Prioritize TCP SYN packets in traffic shaping.

EXIT_ON_ERROR

Valid values: `0' or `1'.

If enabled, IP-Array will exit on all error conditions (configuration, comand apply errors, etc.). Otherwise it will continue and will only exit on hard errors.

RULE_PLACEHOLDER

Valid values: `_' (underscore), `-' (dash), `.' (dot), `,' (comma). Defaults to `_' (underscore).

If a rule entry in a ruleblock will not be set, use this character as placeholder.

USE_M_CONNTRACK

Valid values: `0' or `1'.

Always use the iptables match extension conntrack in favour of the state match.

NFACCT_OBJ_MAP

Netfilter accounting objects (nfacct)

Format:

nfacct-name [...]
SYSCTL_RULES

Names of the files holding the sysctl rules.

SYSCTL_CONNTRACK_MAX

Maximum number of connection to track (conntrack). This can also be set in your sysctl rules, but this variable is here to allow automatic calculation.

Formatting:

value (integer) | (x|X)factor (factor = integer)

Using (x|X)factor, the conntrack max value will be automatically calculated and then multiplied with factor (i.e. x2 - double the auto value).

Global settings - configuration file (global.conf)

This file is supposed to hold global variable definitions (i.e. ports, network classes), which do not apply to the current working system only, but are of generic use, to be utilized on any or more than one host.

Custom variables/namings (alias.conf)

This file is supposed to hold custom (user defined) variables. It is optional, but its use is recommended.

Most likely the user will put definitions for interface names, hosts, etc. Those can be used in rules, ruleblocks and templates.

Internal variables (ip-array_global_defs)

This file holds variables only used internaly. But they still may be altered to change some of the IP-Array behaviour. This is only for advanced usage. Please stick to the comments for information about the settings available.

Templates

How to configure XML templates

XML templates provide the structure for the ruleblocks they will be associated with in the rule files (template rule).

Many templates are provided out of the box inside the template_repo.d. For better performance it is recommended to put only those templates which will actually be used into the directory holding the templates.

Syntax

A template definition file must contain the following:

  1. First a root tag including the describing name attribule and the syntax version:

    <ip_array_root name="iptables_templates" syntax_version="1.0">

    The name attribute tells us it is an iptables template.

    The syntax_version attribute defines the syntax version (only 1.0 is available by now).

  2. The actual template tag including the name attribute defining the name of the template:

    <template name="T_EXAMPLE">

    The template name must begin with one of the following prefixes: T_, BT_, GT_, TEMPLATE_, BASE_TEMPLATE_, GLOBAL_TEMPLATE_.

Template XML tags

The following list describes the tags which are valid inside the templates.

table

The name of the iptables table (defaults to `filter' if unset).

target

A comma separated list of iptables targets. Usually the target will be 'jumped' (--jump) to. To use a goto (--goto) instead, prefix the target name with `goto:'.

chain

A comma separated list of iptables chains. A maximum of 2 chain names can be specified, if the reverse_mode is `reverse' or `mirror'. Otherwise only one is valid.

reverse_mode

Reverse mode can either be set to `reverse' or `mirror'. This means that a second option list will be processed (most likely the return traffic). See option_list_1 below. If `mirror' is specified the first option list will be copied to the second one. Otherwise option_list_1 will be used.

reverse_condition

If this condition evaluates to true, than reverse mode will be used (if specified - othewise this setting does not make sense).

The condition must be defined like this:

foo:bar

where foo is the condition and bar is the value it has to match.

template_msg

A message that will be displayed as the template is called, if VERBOSE is greater or equal 3.

mandatory_vars

A comma separated list of variable names that must be defined in the ruleblock called with the template.

load_template

Other templates to load into the current one.

Important

Those loaded templates will always be read before any option_list or always_use list. Means they are on the more left side from the ruleblock perspective.

option_list_0

These are the actual iptables arguments which will be filled with values from the ruleblock called with the template.

The list of valid iptables arguments and their usage can be called with: ip-array show -sc ipt_args[,...].

You can define default values to be used by using this syntax:

name=default_value

I.e. idev=eth0

These default values will be used if the according ruleblock entry is not defined (filled with the rule placeholder value, or undefined).

option_list_1

This second list of iptables options is used for the reverse_mode if set to `reverse'. I.e. what has been idev (input interface) will be odev (output interface) in the reverse rule.

always_use_0

You can define default values for option_list_0 by using this syntax:

name=default_value

I.e. idev=eth0

always_use_1

You can define default values for option_list_1 by using this syntax:

name=default_value

I.e. odev=eth0

state_match_arg

A maximum of two comma separated lists with state-names of the state/conntrack match. I.e. NEW,ESTABLISHED ESTABLISHED.

The second one is only used if the reverse_mode is set to `reverse'.

Template usage guidelines

It is recommended to build small chunk templates (called base templates) and to use them modulary to build your final templates (using the load_template tag).

Ruleblocks

How to configure XML ruleblocks

Ruleblocks are used inside the template_rule tags in rule files. They always need to be called with the template defining their structure.

Syntax

A ruleblock definition file must contain the following:

  1. First a root tag including the describing name attribule and the syntax version:

    <ip_array_root name="ruleblocks" syntax_version="1.0">

    The name attribute tells us it is a ruleblocks definition.

    The syntax_version attribute defines the syntax version (only 1.0 is available by now).

  2. The actual ruleblock tag including the name attribute defining the name of the ruleblock:

    <ruleblock name="RULEBLOCK_EXAMPLE">

    The ruleblock name must begin with one of the following prefixes: RB_, RULEBLOCK_.

Ruleblocks usage guidelines

It's a good idea to write down the structure of the template you want to call the ruleblock with as a comment below the ruleblock opening tag. This way you will easily remember what each column has to contain.

Newline separates rules inside a ruleblock. So if your template defines i.e. a ruleblock structure like this:

table chain target proto src

then an entry in the ruleblock may look like this:

filter INPUT ACCEPT tcp 1.1.1.1

You can use your shell variables inside ruleblock rules.

XML style comments (<!-- comment -->) are valid inside ruleblocks.

If you want to leave a value in a column undefined use the character defined with $RULE_PLACEHOLDER (default = `_') as a placeholder.

To use spaces inside a column value, use either escaped double quotes (\"value with space\") or single quotes ('value with space').

If the structure of a ruleblock does not fit your needs, it is possible to use the inline functions inside it to add a rule with a different structure.

inline functions

Inline functions are used inside ruleblocks. Sometimes the structure of a ruleblock does not fit the current need. Using inline functions is a way around this, or allow to modify the behaviour of the rule processing.

The following functions are available inline:

add_rule

See description of public_functions.

insert_ipt_rule

Like `add_rule' but it will insert the rule on top of the stack.

create_chain

See description of public_functions.

Rule files

How to configure XML rule files

The rule files define what is run at what point. It may contain public functions, normal rules, combined rules, template rules and iptables arguments that may be used globally to be applied to all following rules (grouping). 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.

Rule file XML 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>

Public functions

IP-Array allows the use of public functions inside rule files. They are defined using the pub_func XML tag.

The list of available public functions can be retrieved by running: ip-array show -sc public_functions.

Help about one or more of them can be retrieved by running i.e.: ip-array show -sc public_functions:function_name_1,function_name_2.

Here is a list of the available functions including a brief description. For more details please refer to the individual help.

add_rule

Add (append) an iptables rule to the command queue (array). Can also be used as 'inline' command.

log

IP-Array messaging (logging) to stdout/stderr and/or syslog.

create_chain

Create an iptables chain (add command to the command queue).

delete_chain

Delete an iptables chain (add command to the command queue).

ipset_create

Create an ipset set.

ipset_add

Add an entry to an ipset set.

jump_tree_on

Enable classification into jump tree chains.

jump_tree_off

Disable classification into jump tree chains.

log_invalid_state

Log packets in invalid state.

drop_invalid_state

Drop packets in invalid state.

logdrop_illegal_tcp

Log and/or drop non legal tcp packets.

drop_dhcp

Drop dhcp broadcasts on certain interfaces.

drop_netbios

Drop netbios broadcasts on certain interfaces

drop_upnp

Drop UPNP broadcasts on certain interfaces

reject_auth

Reject auth (tcp port 113) traffic.

anti_spoof

Create anti spoofing rules.

intns_to_extns

Allow internal DNS servers to communicate with ISP name servers.

lan_isp_smtp

Allow local networks to communicate with ISP SMTP servers.

lan_ftp

Allow passive and/or active ftp forwarding traffic from certain LANs.

enable_ipsec

Enable ipsec rules.

restrict_output

Settings to restrict traffic in OUTPUT chain.

mark_prio_syn

Prioritize SYN packets.

mark_out_bulk

Mark OUTPUT bulk traffic.

mark_fwd_bulk

Mark FORWARD bulk traffic.

nfacct_add

Add a nfacct accounting object.

set_var

Set a variables value.

ipset usage

ipset sets are either controlled with the public functions ipset_create and ipset_add. Or through the ipset related tags in an iptables rule file.

sysctl rule files

How to configure XML sysctl rule files

The sysctl rule files define what system settings are to be modified.

Syntax

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

<ip_array_root name="sysctl_rules" syntax_version="1.0">

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

The syntax_version attribute defines the syntax version. 1.0 is available by now.

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.

sysctl rule file XML tags

The XML tags used in sysctl rule files are an exact representation of the names used with the sysctl program. Each of the names used by the sysctl program, which are separated by a dots, will be the name of the XML tag, or the attribute if it is the actual setting. Example:

net.ipv4.ip_forward=1 from sysctl will be described in XML like this:

<net>
    <ipv4>
        <ip_forward> 1 </ip_forward>
    </ipv4>
</net>

or as attribute:

<net>
    <ipv4 ip_forward="1">
    </ipv4>
</net>

or even shorter as attribute if only this single setting is used:

<net>
    <ipv4 ip_forward="1"/>
</net>

You can mix both ways as you wish. To see all the available types of your local system, run either sysctl -a or ip-array compat-check.

Shell variables are valid as tag names inside sysctl rules. The main purpose of this feature is to allow generic configuration of values that may change system depending. i.e. the interface names in net.ipv4.conf.$INTERFACE_NAME. The variable must not be quoted! You can either write them with or without the curly braces: <$VARIABLE> or <${VARIABLE}>.

Now if you define you interface name variables inside the i.e. alias.conf configuration file, you can use them inside your sysctl rule files. And every time an interface changes, all you need to do, is to modify the variable and re-parse the sysctl rule files.

Example: inside alias.conf you define: EXT_IF=eth0 and inside your sysctl rule file you write:

<net>
    <ipv4>
        <conf>
            <$EXT_IF>
                <accept_redirects> 0 </accept_redirects>
            </$EXT_IF>
        </conf>
    </ipv4>
</net>

or as attribute (in the short form):

<net>
    <ipv4>
        <conf>
            <$EXT_IF accept_redirects="0"/>
        </conf>
    </ipv4>
</net>

XML style comments are valid inside sysctl rule files. Public functions etc. are not.

In interactive mode, only the net.* (also suppressing ipv6.*) settings will be listed.

Chapter 5. Traffic shaping

IP-Array has basic traffic shaping support built in. The creation of htb, and sfq qdiscs as well as tc classes and filters is, with a limited set of options, supported.

When traffic shaping is enabled by setting the ENABLE_TC_SHAPING variable to `1', a number of predifined ruleblocks (TC_MANGLE_RULEBLOCKS - the iptables mangle table marking and TC_RULEBLOCKS - the queue discs, classes and filters) and rules (TC_MARK_RULES also containing the tc public functions) get loaded.

Unlike with the iptables counterpart, there are no templates to edit and the names and order of parameters of the ruleblocks are hard coded.

Chapter 6. Usage

Running IP-Array

Startup parameters and options

Parameters

If the first parameter is omitted, usage instructions are printed. Only one parameter is allowed - but required - for ip-array to take any action.

These parameters control the 'mode' IP-Array runs on.

  • start

    All network connections are forbidden (see lockdown mode below) until all configuration has been read. Module probing (if configured) is done first. After all commands are compiled, they are applied at once. An iptables rule listing is saved for later difference checks.

  • stop

    All tables and chains and ipset sets get flushed and destroyed, no firewalling is active any more. All tc qdisc are removed, no traffic shaping is active any more. Modules configured to be loaded are removed.

  • restart

    Module probing (if configured) is done first. After all commands are compiled, they are applied at once. An iptables rule listing is saved for later difference checks.

  • test

    Acts like the 'restart', but will use the testing configuration below the 'test' folder. Also it will schedule a restore job (using the `at' command scheduler) for the time specified with RELOAD_TIME in the defaults file.

  • open

    Module probing (if configured) is done first.

    This mode leaves only the NAT rules active (reads configuration and re-applies them), all other tables are emptied. Policies are set to ACCEPT. An iptables rule listing is saved for later difference checks. The ipset ruleset will not be touched.

  • tc-start

    Start traffic shaping only. Mangle table rules will be (re)-applied. An iptables rule listing is saved for later difference checks. ipset ruleset will not be touched.

  • tc-stop

    Stop traffic shaping only. Mangle table rules will be (re)-applied. Qdisks of interfaces listed in NET_INTERFACES will be deleted. An iptables rule listing is saved for later difference checks. ipset ruleset will not be touched.

  • lockdown

    All filter table policies will be set to DROP, all others will be set to ACCEPT. All chains get flushed and custom chains are deleted. No more network connections are allowed except:

    A: If the bash environment variable SSH_CONNECTION is set, IP-Array allow connections from that source address to the ssh server port.
    B: If the environment variable is not set, but the ADMIN_CONNECTION variable is set in the main config file, IP-Array will allow the configured connection.
    C: If the ALLOW_LOOPBACK variable is set in the main config file, loopback communication will be allowed.
  • interactive

    In this mode several wizards are available to interactively create or edit the IP-Array configuration. It is possible to create main configuration files, templates, iptables/ipset and sysctl rule files, or create and edit ruleblocks. The whiptail program is required for this. The global_defs configuration file holds 3 variables (IACTIVE_WINDOW_HEIGHT, IACTIVE_WINDOW_WITH, IACTIVE_LIST_HEIGHT) for configuring the sizes of the wizards dialog boxes. By default they are set to `0'. If this is kept and the tput program is available in PATH, it will used to query and set the required values for window height, window with and list height. Otherwise it is possible to adjust the window settings there, with the downside of having static values.

  • diff-last-activated

    Every time IP-Array is not in 'test' mode and activates an iptables ruleset, it saves a listing of the rules to a file. Using this parameter a (simple diff based) difference check between the currently active ruleset and the listing of the file is performed. Thus allowing to detect (unwanted) modifications.

  • dry-run

    Configuration is processed and validated, but no commands will be applied.

  • save

    The currently active iptables and ipset ruleset will be saved using `iptables-save' and `ipset save'.

  • save-known-good

    Save the currently active ruleset to file (the name of the file can be set using the variable KNOWN_GOOD_RULESET in the defaults file. It will be used if RESTORE_ON_START is set to `1' (quick start activated).

  • restore

    The previously saved ruleset (using the 'save' parameter) will be restored using `iptables-restore' `ipset restore'.

  • save-commands

    Save all commands (modprobe, sysctl, tc, iptables, ipset) to a file.

  • save-iptables-commands

    Save the generated iptables and ipset commands to a file.

  • save-modprobe-commands

    Save the generated modprobe commands to a file.

  • save-sysctl-commands

    Save the generated sysctl commands to a file.

  • save-tc-commands

    Save the generated tc commands to file.

  • save-shaping-commands

    Save the generated tc and iptables mangle table (mark) commands to file.

  • prepare-restore-on-start

    Create the 'quick start' scripts. After the configuration is completed this parameter allows to save it into scripts holding the compiled commands, in order to quickly (re)apply it to the system. If iptables-save is used (IPTSAVE_FAILS is set to `0') the currently active ruleset will be saved. The name for these 'known-good' script can be set in the defaults file.

  • parse-xml

    Compile bash scripts from the XML files. By default templates, ruleblocks and rules are converted. The -pb, -pr and -pt parameters allow to select which of those will be compiled.

  • compat-check

    A compatibility check will be performed. IP-Array will probe the kernel version, supported iptables tables, targets and matches, available sysctl settings, modules and programs. The result will be printed to stdout.

  • show

    Show configuration or colour settings. The option `-sc' selects the type of information to display. By default the settings of the main configuration file are shown.

  • version

    Show version information.

  • help, -h, --help, -?

    Show usage information.

Options

All options are optional. Some require an argument, others do not. All options and their arguments must be separated by blank(s). If an option can be used more than once, it is mentioned explicitly.

  • -ct, --ipt-counters

    Save or restore iptables counters when using the `save' or `restore' startup parameter.

  • -dg, --debug

    Enable debugging output.

  • -dr, --dry-run

    Commands will not be applied.

  • -ex, --err-exit

    Set bash to exit on simple command failure (set -e) and to inherit the ER trap to functions, etc.

  • -na, --no-autosave

    Do not use the automatic saving and restoring logic (see autosave / restore).

  • -nc, --no-compat-check

    Do not perform the compatibility check.

  • -nd, --no-diff

    Do not save the diff file for the difference check of the ruleset (diff-last-activated startup parameter).

  • -ni, --no-iface-check

    Do not check for the existence of interfaces.

  • -nm, --no-modprobe

    Do not perform load or unload kernel modules.

  • -ny, --no-sysctl

    Do not set the sysctl configuration.

  • -p, --parse-xml

    Read all XML files and overwrite already compiled bash scripts.

  • -pb, --parse-ruleblocks [type[,...]]

    Read XML ruleblock files and overwrite already compiled bash scripts.

    The type argument allows to parse files selectively by type. Available types are: filter, mangle, nat, raw, security, rawpost, tc, tc_mangle.

  • -pr, --parse-rulefiles [type[,...]]

    Read XML rule files and overwrite already compiled bash scripts.

    The type argument allows to parse files selectively by type. Available types are: filter, mangle, nat, raw, security, rawpost, ipset, sysctl, tc_mark, vpn.

  • -pt, --parse-templates [type[,...]]

    Read XML template files and overwrite already compiled bash scripts.

    The type argument allows to parse files selectively by type. Available types are: base, filter, mangle, nat, raw, security, rawpost.

  • -t, --test

    Schedule the restore of the active ruleset..

  • -b, --base-dir directory

    Set base directory to use (i.e. /etc/ip-array).

  • -c, --config-file file

    Specify the name of the main configuration file to use.

  • -C, --config-dir directory

    Set directory for the main configuration file.

  • -d, --defaults-file full_path_to_file

    Specify the full path of the defaults file to use.

  • -e, --exe-dir directory

    Set the directory to place the main executable of IP-Array into (i.e. /usr/bin/ip-array).

  • -l, --lib-dir directory

    Set the directory to place the function file(s) of IP-Array into (i.e. /usr/lib/ip-array).

  • -r, --run-dir directory

    Set the directory to place the PID file into (i.e. /var/run).

  • -s, --save-file file

    Specify the name of the file used to save or restore a ruleset.

  • -si, --save-ips-file file

    Specify the name of the file used to save or restore an ipset ruleset.

  • -co, --color 0 | 1

    Enable or disable coloured output.

  • -ui, --use-ipset 0 | 1

    Enable or disable usage of ipset. This setting is globally. It disables builtin usage as well as the users ipset rules.

  • -o, --set-option assignment [...]

    Override variables of the main configuration file. i.e. -o ENABLE_NAT=0.

  • -gf, --gen-format type

    Generate command in iptables-save format, or as command list. Available types: `cmd' (= default) or `ipt'.

  • -rs, --restore-on-start 0 | 1

    Enable or disabe quickstart (only valid using the `start' parameter).

  • -rt, --reload-time 1-15

    Time in minutes until the saved ruleset will be restored.

  • -sc, --show-config [type] [...]

    Select type of information to show. If type is omitted, the settings of the main configuration file will be displayed. This option can be used multible times.

    all - everything will be displayed.
    ansi_codes - display ANSI codes for coloured shell output.
    colors - available colours.
    defaults[:NAME[,...]] - display all or just the selected variable names from the defaults file.
    main[:NAME[,...]] - display all or just the selected variable names from the main configuration file file.
    targets - show all available iptables targets.
    matches - show all available iptables matches.
    rules - show the compiled iptables rules.
    ipt_args[:-[core|matches|targets][,...]] - display iptables arguments by category.
    ipt_args[:NAME[,...]] - display all or just the selected iptables arguments help.
    ruleblocks[:NAME[,...]] - display all or just the selected ruleblock names.
    templates[:NAME[,...]] - display all or just the selected templates names.
    sysctl - display the sysctl configuration.
    public_functions[:NAME[,...]] - display all or just the selected public functions help.
    find_templates:template-entry-glob[,...] - find templates containing all entries of the comma separated search list.

    Available types are:

  • -sh, --shell /path/shell

    Specify an alternative shell to run IP-Array.

  • -sv, --syslog-verbose 0-6

    Specify the level of output verbosity to syslog. Allowed values are from `0' to `6'. Overrides the value of SYSLOG_VERBOSE in the defaults file.

  • -v, --verbose 0-9

    Specify the level of output verbosity. Allowed values are from `0' to `9'. Overrides the value of VERBOSE in the defaults file.

init script

Usually IP-Array is called from the init script. But it can also be started directly by running the executable. In that case you must specify a path to the defaults file on the command line.

The header of the init script contains some variables to configure. You need to set the path to the defaults file and the IP-Array executable.

There is also a second init script provided, called ip-array.init_pre_net_boot, this should be executed before the network configuration takes place. It will apply `lockdown' mode, in order to make sure there's no unsecure gap while setting up the networking.

Exit codes

  • 0 - Success.

  • 1 - Unknown error.

  • 2 - Usage information (help).

  • 111 - Not exist error. Used if i.e. a file was not found.

  • 112 - Not defined error. Used if i.e. a configuration variable is not set.

  • 113 - Loading error. Used if i.e. sourcing a file failed.

  • 114 - Failure error. General fail condition.

  • 115 - Configuration error. Used if a configuration error was not found.

Usage examples

/etc/init.d/ip-array dry-run -v 6 -sv 0 -pb

Run IP-Array in no-acting mode (don't apply commands). With a verbosity to screen of `6' (quite detailed) and a syslog verbosity of `0'. Also parse the XML ruleblock files and compile bash scripts out of them.

/etc/init.d/ip-array parse-xml -sv 0

Just parse all XML files. Use the default screen verbosity and set syslog verbosity to `0'.

/etc/init.d/ip-array restart -p -na

Parse the XML files before reloading the configuration. Do not use the autosave / restore logic.

/etc/init.d/ip-array save -s home_net_config.ipt_save

Save the currently active iptables ruleset using iptables-save to the file specified as 'home_net_config.ipt_save.

/etc/init.d/ip-array test -d "/etc/default/ip-array/defaults_02.conf" -c "xyz_test_02.conf" -sv 4 -v 0 -pb -pr

Run IP-Array in 'test' mode. Use the defaults config file specified with '/etc/default/ip-array/defaults_02.conf'. Use the main configuration file specified with: 'xyz_test_02.conf'. Set syslog verbosity to `4'. Set screen output verbosity to `0'. Parse ruleblock and rule files.

/etc/init.d/ip-array prepare-restore-on-start -v 1 -sv 0

Prepare the 'quick-start' scripts with a screen verbosity of `1' and syslog verbosity of `0'.

/etc/init.d/ip-array show -sc find_templates:option_list_0*=odev,option_list_0*=src,option_list_0\\\[6\\\]=nat_opt -v 0 -sv 0

Find templates conaining the iptables arguments in the first option list (option_list_0) odev and src at any position and the the iptables arguent nat_opt at position `6'. Screen verbosity set to `0' and syslog verbosity of `0'.

Chapter 7. Appendix

Troubleshooting

  • Compatibility test lists a target or module as not existing, although it is.

    Answer: Open the file 'ip-array_global_defs' and find the definition of the arrays IPARRAY_TARGETS or IPARRAY_MODULES. Edit the line containing the test for the desired module or module to fit your needs.

Support

The preferred way to get support on IP-Array, is to open a forum post on the project page. Alternatively you could send a mail to .

Bug report

Please report bugs either via a forum post on the project homepage, or send email to .

Co-Development

If you like IP-Array and want to help developing, send email to .