NAME

IPTables::IPv6 - Perl module for manipulating iptables rules for the IPv6 protocol

SYNOPSIS

  use IPTables::IPv6;
  
  $table = IPTables::IPv6::init('tablename');

  %IPTables::IPv6 = (
      filter => {
                  INPUT => {
                             rules => [
                                        {
                                          source => '2001::/16',
                                          jump => 'ACCEPT'
                                        }
                                      ],
                             pcnt => 50000,
                             bcnt => 1000000,
                             policy => 'DROP'
                           }
                }
  );

DESCRIPTION

This package provides a nice interface to the IP Tables control API that fairly closely parallels the C API exported in libiptc for manipulating firewalling and forwarding rules for IPv6 packets. Also, a tied multilayer data structure has been built, allowing the tables, chains, rules and fields to be manipulated in a more natural fashion.

The module will be built with a default library path built into it. That can be overridden using the IPT_MODPATH environment variable. If your script is being called suid root, you may want to do delete $ENV{IPT_MODPATH}; to ensure that someone isn't subverting your script. Make sure you do this before you use IPTables::IPv6; to ensure that it never loads from an unapproved path.

METHODS

Most methods will return 1 for success, or 0 for failure (and on failure, set $! to a string describing the reason for the failure). Unless otherwise noted, you can assume that all methods will use this convention.

Initialization

$table = IPTables::IPv6::init('tablename')

This sets up the connection to the kernel-level netfilter subsystem. tablename corresponds to the name of a table (filter, nat, mangle, or dropped) to manipulate. The call returns an object of type IPTables::IPv6::Table, which all the other methods are to be called against, if the named table exists. If it does not exist, undef will be returned.

Chain Operations

$is_builtin = $table->builtin('chainname')

This checks if the chain chainname is built into the current table. The method will return 1 if chainname is a built-in chain, or 0 if it is not.

$success = $table->create_chain('chainname')

This attempts to create the chain chainname.

$success = $table->delete_chain('chainname')

This attempts to delete the chain chainname.

($policy, $pcnt, $bcnt) = $table->get_policy('chainname')

This returns an array containing the default policy, and the number of packets and bytes which have reached the default policy, in the chain chainname. If chainname does not exist, or if it is not a built-in chain, an empty array will be returned, and $! will be set to a string containing the reason.

$refcnt = $table->get_references('chainname')

This returns the reference count for the chain chainname if it exists and is a user-defined chain. If chainname does not exist, or is a built-in chain, -1 will be returned, and $! will be set to a string containing the reason.

$is_chain = $table->is_chain('chainname')

This checks to verify that the chain chainname exists in the current table. The method will return 1 if chainname is a chain, 0 if not.

@chains = $table->list_chains()

In array context, this method returns an array containing names of all existing chains in the table that $table points to. In scalar context, returns the number of chains in the table.

$success = $table->rename_chain('oldname', 'newname')

This attempts to rename the chain oldname to newname.

$success = $table->set_policy('chainname', 'target')

$success = $table->set_policy('chainname', 'target', {pcnt => count, bcnt => count})

This attempts to set the default target for the chain chainname to target. It also allows the packet and byte counters on a chain to be set using the (optional) third argument. Those values must be passed as a hash ref, as shown.

Rule Operations

$success = $table->append_entry('chainname', $hashref)

This attempts to append the rule described in the hash referenced by $hashref to the chain chainname.

$success = $table->delete_entry('chainname', $hashref)

This attempts to delete a rule matching that described in the hash referenced by $hashref from the chain chainname.

$success = $table->delete_num_entry('chainname', $rulenum)

This attempts to delete the rule $rulenum from the chain chainname.

$success = $table->flush_entries('chainname')

This deletes all rules from the chain chainname.

$success = $table->insert_entry('chainname', $hashref, $rulenum)

This attempts to insert the rule described in the hash referenced by $hashref at index $rulenum in the chain chainname.

@rules = $table->list_rules('chainname')

When called in array context, this method returns an array of hash references, which contain descriptions of each rule in the chain chainname. In scalar context, returns the number of rules in the chain.

Note that if the chain chainname does not exist, an empty list will be returned, as will listing an empty chain. Be sure to verify that the chain exists before you try to list the rules.

$success = $table->replace_entry('chainname', $hashref, $rulenum)

This attempts to replace the rule at index $rulenum in the chain chainname with the rule described in the hash referenced by $hashref.

$success = $table->zero_entries('chainname')

This zeroes all packet counters in the chain chainname.

Cleanup

$success = $table->commit()

This attempts to commit all changes made to the IP chains in the table that $table points to, and closes the connection to the kernel-level netfilter subsystem. If you wish to apply your changes back to the kernel, you must call this.

RULE STRUCTURE

The rules in the libiptc interface are expressed as struct ipt_entrys. However, I have decided to express the rules as hashes. The rules are passed around as hash references, and may contain the following fields:

source

The source address of a packet. This will appear in one of the following forms:

        ip:v6:add::re:ss
        ip:v6:add::rs:ss/maskwidth
        ip:v6:add::re:ss/ip:v6:ne::tma:sk

It may be prefixed with a '!', to indicate the inverse sense of the address (i.e., match anything EXCEPT the address or address range specified).

destination

The destination address of a packet. It will appear in one of the same forms as source (see above).

in-interface

The network device which received the packet. Some chains cannot accept a rule with in-interface set (such as the PREROUTING chain). This may show up as a full interface name (such as eth0), or as a wildcarded interface name (such as eth+, where + is the wildcard character, which can only be used at the end of a wildcarded interface string). It may be prefixed with a '!', to indicate the inverse sense of the interface (i.e., match anything EXCEPT the interface specified).

out-interface

The network device that a packet will be sent out via. Some chains cannot accept a rule with out-interface set (such as the INPUT chain). The format is the same as that for in-interface (see above).

protocol

The name of the protocol of an incoming packet. It may be prefixed with a '!', to indicate the inverse sense of the protocol (i.e., match anything EXCEPT this protocol).

jump

The target or chain to jump to if the rule matches.

pcnt/bcnt

The number of packets and bytes that have matched this rule since the rule was put in place, or since its counters were last zeroed.

matches

An array reference, containing a list of all the match modules which are to be used as part of the rule. Any match qualifier other than a protocol match module - i.e., tos, mport, state, etc., must be specified with this option, or any fields that belong to them will not be honored.

[target]-target-raw

This contains, as a string, the raw target data for a rule, if the needed module can't be found. [target] should be the name of the target. There will, of course, only be one of these per rule (as each rule can only have one target).

[match]-match-raw

This contains, as a string, the raw match data for a rule, if the needed module can't be found. [match] should be the name of the match. There can be more than one of these in one rule. If a match is specified in matches, and no match module is available, raw data must be provided.

MODULE-SPECIFIC RULE OPTIONS

Each module, for protocols, non-protocol matches, and non-standard targets, has specific keys associated with specific options.

This material will be added later on, once I'm sure everything is working as it should be.

AUTHOR

Derrik Pates, dpates@dsdk12.net

SEE ALSO

iptables(8).