Name

ip-array — Firewall and Traffic control Configuration utility

Scope = security, networking, system administration -- linux - netfilter/iptables - tc

Synopsis

ip-array parameter [ option [ option_argument ] ...]

Description

ip-array is a command generator for netfilter (currently only iptables), tc, sysctl and kernel module configuration.

It is written in bash. Bash version 3.1 or higher is required.

Basic configuration is done via shell style configuration files. Rules are defined using a simple XML syntax. The XML configuration files get converted to bash scripts, which are read at runtime. A bash completion compspec ships with the package.

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

    If `--public-functions' is used as second argument, a list of available public functions is printed. If a name of public function is given as third argument, a brief description of the function is shown.

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.

  • -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/sbin/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.

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

Environment

If the environment variable DEBUG_INFO is set, additional debugging information is displayed. If in addition the output verbosity is set to 8 or higher, a debugging PS4 is set.

Exit status

0

Success

1

Undetermined error.

3

Usage error.

111

Requested item (file, folder) does not exist error.

112

Item (configuration variable) not defined error.

113

Failed loading item (script, program) error.

114

General fail condition error.

115

Configuration error.

Files

/usr/sbin/ip-array

See also

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

iptables(8), iptables-save(8), iptables-restore(8), tc(8), tc-htb(8), tc-sfq(8)