IPChains - Create and Manipulate ipchains via Perl

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- BUGS
- AUTHOR
- COPYRIGHT

# 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-data
             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.

# BUGS

Much of this is highly untested. Masquerading timeout setting isn'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 Hutchison (j@splatlabs.com). 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.