Table of Contents
List of Tables
Table of Contents
This document is the reference manual for IP-Array version 1.1.1.
It should provide all the information necessary to configure and use IP-Array.
This section gives an overview about what IP-Array is, the requirements, features, goals and online availability.
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 `/proc' filesystem.
Intended Audience: Advanced End Users, System Administrators.
Field of application: From a single host system to a multi-homed router or gateway.
This list describes, what is necessary to use IP-Array:
Bash version 3.0 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 logger utility (optional). To write messages to syslog.
The at utility.
The bc (bash calculator) utility.
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 `/proc' filesystems networking (netfilter) options (optional)
Provide a configuration interface to iptables, ipset and tc.
Allowing flexible configuration from simple to complex setups.
Keep effective rule writing effort low, by just entering the desired values, or allow grouping of options.
Stay as close as possible with the concept and naming of iptables / tc.
Although (by now) it's not the main goal of IP-Array, provide some preset options for automatic configuration.
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'.
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.
Supported tables: filter, mangle, nat, raw, rawpost (xtables-addons), security.
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).
Definition of templates, ruleblocks, rules and ipset sets is done in a simple XML dialect.
Options in rules can be grouped to save writing effort.
An interactive mode, which is wizard based and allows to create (and edit in case of ruleblocks) configuration files.
ipset integration. Older ipset versions (4.x, 5.x) are supported. Compatible with ipset v. 6 to 6.27+.
Chain creation (by adding them in the CHAIN_MAP
variable).
Different modes of automatic `jump tree' creation in all tables.
Allow an admin connection.
Create stateful return traffic rules (ESTABLISHED, RELATED).
Create final (terminating) rules. A chain termination option for builtin and IP-Array created chains, which allows to choose between different 'final rule' modes.
Automatic configuration (rule generation) options for:
Policy
Set the iptables builtin chains policy.
DNS
Allow local host DNS lookups to specific name servers.
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.
Automated iptables logging options:
Globally log invalid TCP packets
Globally log packets in INVALID state
Log options (prefix, level, etc.) for the above listed.
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
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
Prolog and Epilog scripts
Prolog and epilog scripts can be configured selectively for any startup mode.
Loading and unloading of kernel modules (with optional parameters).
/proc filesystem configuration
There are many networking related options available in IP-Array, to configure the system using the /proc filesystem.
Saving restore rulesets / commands / system state.
There are various ways available to save the generated rulesets and or commands selectivly (iptables, ipset, tc, modprobe, /proc) or all at once. The saved files may be used to restore the configured system state.
Different levels of IP-Array's output verbosity to the screen and or syslog can be set.
Screen output can be colourized. Colours for different message categories can be defined by the user.
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.
Different startup behaviour according to command line parameter. Including multiple options to save and / or restore generated rulesets or commands.
A `test' mode to test new configurations.
Automatic restoring of the previous ruleset on error when applying the new configuration.
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.
Table of Contents
This Chapter provides information about the structure, functionality and program logic of IP-Array.
A rule is either:
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.
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.
An entity in a XML rule or combined rule.
A ruleblock is a group (stack) of 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.
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_target | ipt_chain | input_device | source_address |
According ruleblock rule: | DROP | INPUT | eth0 | 10.0.0.10 |
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 /proc 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 previously saved rulesets are
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 /proc 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.
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 setting values in the /proc filesystem, 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.
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.
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.
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.
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.
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.
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.
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.
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 directory for IP-Array.
Default location of the defaults directory, saving directory, help directory.
`stable' and `test' (OP_DIR) directory (describing runmode).
i.e. `/usr/local/etc/ip-array/'
Directory to put the main IP-Array executable into.
i.e. `/usr/local/bin/ip-array/'
Directory to put the IP-Array function files into.
i.e. `/usr/local/lib/ip-array/'
Directory containing help files.
HELP_DIR="${BASE_DIR}/help.d"
Operation directory according to runmode. Can be either `stable' or `test' (if startup parameter `test' is used).
OP_DIR="${BASE_DIR}/${rmode}"
Directory containing configuration files and sub-directories.
CONFIG_DIR="${OP_DIR}/conf.d"
Directory to put the rule files into.
RULE_DIR="${OP_DIR}/rules.d"
Directory for the prolog / epilog scripts.
SCRIPT_DIR="${OP_DIR}/scripts.d"
Directory to put the ruleblock configuration files into.
RULEBLOCK_DIR="${CONFIG_DIR}/ruleblocks.d"
Directory to put the template configuration files into.
TEMPLATE_DIR="${CONFIG_DIR}/templates.d"
Directory used to save commands, scripts or rulesets.
SAVE_DIR="${BASE_DIR}/save.d"
Directory where all the templates that come with IP-Array are stored . By default
it is /usr/share/ip-array/template_repo.d
.
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.
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.
Always create a backup before installing a new version! Configuration files will be overwritten with the default ones!
Table of Contents
This chapter provides information about how to configure IP-Array.
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.
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
.
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/default/ip-array
.
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
).
The defaults file contains startup and globally used variables.
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.
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.
With a non zero environment variable `DEBUG_INFO
',
additional processing (debugging) information is printed.
No messages are shown. Exit status indicates success or failure.
Shows start and end message and errors.
Main title and warning messages are also shown.
Sub title messages are shown in addition.
Info title, config and rule file loading messages, are shown additionally.
Also show notice messages.
Verbose output.
Also show IP-Array internals.
Debug mode (set -x).
With a non zero environment variable `DEBUG_INFO
',
a debugging `PS4
' is set.
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.
Errror messages are shown.
Main title and warning messages are shown.
Subtitle messages are shown in addition.
Info title, config and rule file loading messages, are shown additionally.
Also show notice messages.
Verbose output.
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.
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.
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.
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 put the iptables-save output into, when executing IP-Array with the 'save' startup parameter.
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.
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 | -proc | -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).
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).
RELOAD_TIME
Mandatory: no - defaults to 7.
Allowed values: Any value from 1 to 15.
Time period until the previously saved ruleset will be restored, when using the 'test' startup parameter.
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.
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.
This file is the main IP-Array configuration file. The various settings for the /proc filesystem are not listed here. Please stick to the comments in the configuration file and the kernel documentation for further explanations. The list of the settings names and their path inside the /proc filesystem can be retrieved by running: ip-array show -sc proc.
CONFIG_FILES
Names of the configuration files which will be loaded in order of appearence. i.e. CONFIG_FILES="aliases.conf global.conf".
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 name | Interface alias | Type[:ipsec] | Network name |
---|---|---|---|
eth0 | eth0 | ext:ipsec | INET_CON_X |
eth1 | eth1 | ext | INET_CON_Y |
eth2 | eth2 | local | PRODUCTION |
eth2 | eth2:0 | local | DEVELOPMENT |
eth3 | eth3 | local | DMZ |
ipsec0 | ipsec0 | ipsec | VPN_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 name | Name server IP address | [Name server MAC address] |
---|---|---|
DMZ | 10.11.11.11 | AA:BB:CC:DD:EE:FF |
DMZ | 10.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 name | ISP name server IP address[,...] | [External network interface] |
---|---|---|
PRODUCTION | 123.12.12.22,123.12.12.23 | eth1 |
DEVELOPMENT | 124.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 name | ISP mail server IP address[,...] | [External network name] |
---|---|---|
PRODUCTION | 123.12.12.90,123.12.12.91 | INET_CON_ISP_X |
DEVELOPMENT | 125.25.25.5,125.25.25.6 | INET_CON_ISP_Y |
DMZ | 126.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.23 | INET_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.15 | INET_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.
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 name | External IP address | LAN address/mask | LAN interface IP address |
---|---|---|---|
local_branch | 188.88.88.8 | 192.168.1.0/24 | 192.168.1.1 |
remote_branch_01 | 177.77.77.7 | 10.1.1.0/24 | 10.1.1.1 |
remote_branch_02 | 166.66.66.6 | 172.16.1.0/24 | 172.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 [...]
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.
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.
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.
A template definition file must contain the following:
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).
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_.
The following list describes the tags which are valid inside the templates.
The name of the iptables table (defaults to `filter' if unset).
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:'.
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 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.
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.
A message that will be displayed as the template is called, if
VERBOSE
is greater or equal 3.
A comma separated list of variable names that must be defined in the ruleblock called with the template.
Other templates to load into the current one.
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.
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).
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.
You can define default values for option_list_0
by using this
syntax:
name=default_value
I.e. idev=eth0
You can define default values for option_list_1
by using this
syntax:
name=default_value
I.e. odev=eth0
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'.
Ruleblocks are used inside the template_rule tags in rule files. They always need to be called with the template defining their structure.
A ruleblock definition file must contain the following:
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).
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_.
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.
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 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:
See description of public_functions.
Like `add_rule' but it will insert the rule on top of the stack.
See description of public_functions.
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.
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> 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.
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.
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>
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 (append) an iptables rule to the command queue (array). Can also be used as 'inline' command.
IP-Array messaging (logging) to stdout/stderr and/or syslog.
Create an iptables chain (add command to the command queue).
Delete an iptables chain (add command to the command queue).
Set a configuration value in the `/proc' filesystem (add command to the command queue).
Create an ipset set.
Add an entry to an ipset set.
Enable classification into jump tree chains.
Disable classification into jump tree chains.
Log packets in invalid state.
Drop packets in invalid state.
Log and/or drop non legal tcp packets.
Drop dhcp broadcasts on certain interfaces.
Drop netbios broadcasts on certain interfaces
Drop UPNP broadcasts on certain interfaces
Reject auth (tcp port 113) traffic.
Create anti spoofing rules.
Allow internal DNS servers to communicate with ISP name servers.
Allow local networks to communicate with ISP SMTP servers.
Allow passive and/or active ftp forwarding traffic from certain LANs.
Enable ipsec rules.
Settings to restrict traffic in OUTPUT chain.
Prioritize SYN packets.
Mark OUTPUT bulk traffic.
Mark FORWARD bulk traffic.
Add a nfacct accounting object.
Set a variables value.
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.
IP-Array has basic traffic shaping support built in.
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.
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,
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, proc, 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-proc-commands
Save the generated /proc 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 proc 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.
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 onsimple 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.
-np, --no-proc
Do not set the /proc filesystem 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, 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: 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.
Available types are:
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. |
proc display the /proc filesystem configuration options, paths and their configured values. |
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. |
-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.
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.
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.
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.
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.
Just parse all XML files. Use the default screen verbosity and set syslog verbosity to `0'.
Parse the XML files before reloading the configuration. Do not use the autosave / restore logic.
Save the currently active iptables ruleset using iptables-save to the file specified as 'home_net_config.ipt_save.
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.
Prepare the 'quick-start' scripts with a screen verbosity of `1' and syslog verbosity of `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'.
Table of Contents
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.
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 <AllKind@fastest.cc>
.
Please report bugs either via a forum post on the project homepage, or send email to
<AllKind@fastest.cc>
.
If you like IP-Array and want to help developing, send email to
<AllKind@fastest.cc>
.