ipchains(3)

NAME

IPChains - Create and Manipulate ipchains via Perl

SYNOPSIS

use IPChains;
$fw = IPChains->new(-option => value, ... );
$fw->append('chain');

DESCRIPTION

This module acts as an interface to the ipchains(8)
userspace utility by Paul "Rusty" Russell
(http://www.rustcorp.com/linux/ipchains/). It attempts to
include all the functionality of the original code with a
simplified user interface via Perl. In addition, plans for
log parsing facilities, an integrated interface to
ipmasqadm, and possibly traffic shaping are slated for up
and coming versions.

The new() and attribute() methods support the following options:

Source

Specifies origination address of packet. Appending
hostmask to this address using a / is OK, as well as
specifying it separately (see SourceMask).

SourceMask

Hostmask for origination address. Can either be in 24
or 255.255.255.0 style.

SourcePort

Specific port or port range (use xxx:xxx to denote
range), requires specific protocol specification.

Dest

Specifies destination address of packet. Appending
hostmask to this address using a / is OK, as well as
specifying it separately (see DestMask)

DestMask

Destination address, (see SourceMask).

DestPort

Destination Port, (see SourcePort).

Prot

Protocol. Can be tcp, udp, icmp, or all. Required for
specifying specific port(s).

ICMP

ICMP Name/Code (in place of port when ICMP is
specified as protocol).

Here is a small table of some of the most common ICMP
packets:

Number Name Required by

0 echo-reply ping
3 destination-unreachable Any TCP/UDP

traffic.
5 redirect routing if not

running

routing daemon

8 echo-request ping
11 time-exceeded traceroute

Rule

Target. Can be ACCEPT, DENY, REJECT, MASQ, REDIRECT,
RETURN, or a user-defined chain. Note: This is case
sensitive.

Interface

Specify a specify interface as part of the criteria
(ie, eth0, ppp0, etc.).

Fragment

Rule only refers to second and further fragments of
fragmented packets (1 or 0).

Bidir

Makes criteria effective in both directions (1 or 0).

Verbose

Set verbose option for setting rules or list() (1 or
0).

Numeric

Show output from list() in numeric format. No DNS
lookups, etc.. (1 or 0).

Log Enable kernel logging (via syslog, kern.info) of

matched packets (1 or 0).

Output

Copy matching packets to the userspace device
(advanced).

Mark

Mark matching packets with specified number
(advanced).

TOS Used for modifying the TOS field in the IP header.

Takes 2 args, AND and XOR masks, (ie, (TOS => ["0x01",
"0x10"])). This feature is highly untested.

The first mask is ANDed with the packet's current TOS,
and the second mask is XORed with it. Use the
following table for reference:

TOS Name Value Typical

Uses

Minimum Delay 0x01 0x10 ftp,

telnet
Maximum Throughput 0x01 0x08 ftp-da

ta
Maximum Reliability 0x01 0x04 snmp
Minimum Cost 0x01 0x02 nntp

Exact

Display exact numbers in byte counters instead of
numbers rounded in K's, M's, or G's (1 or 0).

SYN Only match TCP packets with the SYN bit set and the

ACK and FIN bits cleared (1 or 0).

METHODS

The following methods are available to you:

new()

$fw = IPChains->new(option => value, ...) create new
fw object with options

attribute()

$fw->attribute(option, value) to set option to value, OR $value = $obj->attribute(option) to get current value of option.

clopts()

$fw->clopts() clears all option settings (do this
before calling methods like list(), flush(), delete(), etc. that take only a few specific options).

append()

$fw->append(chain) appends current rule to end of
chain

insert()

$fw->insert(chain, rulenum) inserts rule at position
rulenum in chain. If rulenum is omitted 1 is assumed.

replace()

$fw->replace(chain, rulenum) replace rule at rulenum in chain with current rule.

delete()

$fw->delete(chain, rulenum) deletes rule rulenum from
chain.

check()

$fw->check(chain) check given packet against chain for
testing.

flush()

$fw->flush(chain) deletes all rules from chain.

list()

$fw->list(chain) lists all rules defined for chain.

zero()

$fw->zero(chain) zero's all packet counters for chain.
Cannot zero counters for chain policy.

masq()

$fw->masq() lists current masqueraded connections.

new_chain()

$fw->new_chain(chain) creates new user defined chain.

del_chain()

$fw->del_chain(chain) delete user defined chain.

set_policy()

$fw->set_policy(chain) set default policy for chain. Takes Rule option only.

EXAMPLES

To set the default policy for the "forward" chain to DENY:

use IPChains;

$fw = IPChains->new(Rule => "DENY");
$fw->set_policy("forward");

To list current rules in "input" chain to stdout (without
parsing through /proc/net/ip_fw*):

use IPChains;

$fw = IPChains->new(Verbose => 1);
$fw->list("input");

To create a rule that would allow all traffic on an
internal lan, and deny all tcp traffic from external hosts
on relevant ports, and log it,you could use something
like:

use IPChains;

$internal = IPChains->new(Source =>

"192.168.100.0/24",

Rule => "ACCEPT",
Interface => "eth0");

$external = IPChains->new(Interface => "ppp0",

Prot => "tcp",
DestPort => "0:1024",
Log => 1);

$internal->append("input");
$external->append("input");

You could also create one object, set up the attributes,
append() it, then use clopts() to clear it's options, then use attribute() to individually specify it's next set of options, then append() it again with the new rule. See the examples/ subdirectory in the IPChains.pm source for
more examples.

BUGS

Much of this is highly untested. Masquerading timeout
setting and negative attributes (!) aren't yet
implemented. Much of what's planned to be done hasn't
been yet. This is to be considered nothing more than an
early beta to work out bugs in the basic code, and get
feedback on usefulness and improvements that could be
made.

AUTHOR

Jessica Quaintance (j@x25.org). Please feel free to email
me with feedback, questions, or comments (or indeed
patches/additions).

COPYRIGHT

This package is free software; you can redistribute it
and/or modify it under the same terms as Perl itself, with
the exception of the libipfwc.c, ipchains.c, and the files
in include/ which have separate terms derived from those
of the original ipchains sources. See COPYING for details
of this license. Please see README.ipchains for the README
that was included with the original source code for
ipchains and contains copyrights and credits for such.

23/Feb/99 perl 5.004, patch 04 IPChains(3)