ip-array — Firewall and Traffic control Configuration utility
Scope = security, networking, system administration -- linux - netfilter/iptables - tc
ip-array
parameter [
option
[
option_argument
]
...]
ip-array is a command generator for netfilter (currently only iptables), tc, /proc filesystem 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.
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, 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.
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.
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.
-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.
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.
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.