Provided by: xtables-addons-common_1.32-2_i386 bug

NAME

       ipset -- administration tool for IP sets

SYNOPSIS

       ipset -N set type-specification [options...]

       ipset {-F|-H|-L|-S|-X} [set] [options...]

       ipset {-E|-W} from-set to-set

       ipset {-A|-D|-T} set entry

       ipset -R

       ipset {-V|-v}

DESCRIPTION

       ipset  is used to set up, maintain and inspect so called IP sets in the
       Linux kernel. Depending on the type, an IP set may store IP  addresses,
       (TCP/UDP) port numbers or additional informations besides IP addresses:
       the word IP means a general term here. See  the  set  type  definitions
       below.

       Iptables  matches  and  targets  referring  to sets creates references,
       which protects the given sets in the kernel. A set  cannot  be  removed
       (destroyed) while there is a single reference pointing to it.

OPTIONS

       The  options  that  are recognized by ipset can be divided into several
       different groups.

   COMMANDS
       These options specify the specific action to perform.  Only one of them
       can  be specified on the command line unless otherwise specified below.
       For all the long versions of the command and option names, you need  to
       use  only enough letters to ensure that ipset can differentiate it from
       all other options.

       -N, --create setname type type-specific-options
              Create a set identified with setname and specified type.   Type-
              specific options must be supplied.

       -X, --destroy [setname]
              Destroy the specified set or all the sets if none is given.

              If the set has got references, nothing is done.

       -F, --flush [setname]
              Delete  all  entries from the specified set or flush all sets if
              none is given.

       -E, --rename from-setname to-setname
              Rename a set. Set identified by to-setname must not exist.

       -W, --swap from-setname to-setname
              Swap the content of two sets, or in another words, exchange  the
              name  of  two  sets.  The referred sets must exist and identical
              type of sets can be swapped only.

       -L, --list [setname]
              List the entries for the specified set, or for all sets if  none
              is  given.  The  -r/--resolve  option  can be used to force name
              lookups (which may be slow).  When  the  -s/--sorted  option  is
              given,  the  entries  are  listed  sorted (if the given set type
              supports the operation).

       -S, --save [setname]
              Save the given set, or all sets if none is given to stdout in  a
              format that --restore can read.

       -R, --restore
              Restore  a  saved session generated by --save. The saved session
              can be fed from stdin.

              When generating a session file please note  that  the  supported
              commands  (create  set  and add element) must appear in a strict
              order: first create the set, then add all elements. Then  create
              the  next  set,  add  all  its elements and so on. Also, it is a
              restore operation, so the sets being restored must not exist.

       -A, --add setname entry
              Add an entry to a set.

       -D, --del setname entry
              Delete an entry from a set.

       -T, --test setname entry
              Test wether an entry is in a set or not. Exit status  number  is
              zero  if  the  tested  entry  is in the set and nonzero if it is
              missing from the set.

       -H, --help [settype]
              Print help and settype specific help if settype specified.

       -V, -v, --version
              Print program version and protocol version.

   OTHER OPTIONS
       The following additional options can be specified:

       -r, --resolve
              When listing sets, enforce name lookup. The program will try  to
              display  the  IP  entries  resolved  to  host  names or services
              (whenever applicable), which can trigger slow DNS lookups.

       -s, --sorted
              Sorted output. When listing sets, entries are listed sorted.

       -n, --numeric
              Numeric output. When listing sets, IP addresses and port numbers
              will be printed in numeric format. This is the default.

       -q, --quiet
              Suppress  any  output  to  stdout  and  stderr. ipset will still
              return possible errors.

SET TYPES

       ipset supports the following set types:

   ipmap
       The ipmap set type uses a memory range, where each bit  represents  one
       IP  address.  An  ipmap  set can store up to 65536 (B-class network) IP
       addresses. The ipmap set type is very fast and memory cheap, great  for
       use  when  one  want  to  match certain IPs in a range. If the optional
       --netmask parameter is specified with a CIDR netmask value between 1-31
       then  network  addresses are stored in the given set: i.e an IP address
       will be in the set if the network address, which is resulted by masking
       the address with the specified netmask, can be found in the set.

       Options to use when creating an ipmap set:

       --from from-addr

       --to to-addr
              Create an ipmap set from the specified address range.

       --network addr/mask
              Create an ipmap set from the specified network.

       --netmask prefixlen
              When   the   optional  --netmask  parameter  specified,  network
              addresses will be stored in the set instead of IP addresses, and
              the from-addr parameter must be a network address. The prefixlen
              value must be between 1-31.

       Example:

              ipset -N test ipmap --network 192.168.0.0/16

   macipmap
       The macipmap  set  type  uses  a  memory  range,  where  each  8  bytes
       represents one IP and a MAC addresses. A macipmap set type can store up
       to 65536 (B-class network) IP addresses with MAC.  When adding an entry
       to  a  macipmap set, you must specify the entry as "address,mac".  When
       deleting or testing macipmap entries, the ",mac" part is not mandatory.

       Options to use when creating an macipmap set:

       --from from-addr

       --to to-addr
              Create a macipmap set from the specified address range.

       --network addr/mask
              Create a macipmap set from the specified network.

       --matchunset
              When the optional --matchunset parameter specified, IP addresses
              which  could  be  stored in the set but not set yet, will always
              match.

       Please note, the "set" and "SET" netfilter kernel  modules  always  use
       the  source MAC address from the packet to match, add or delete entries
       from a macipmap type of set.

   portmap
       The portmap set type uses a memory range, where each bit represents one
       port.  A portmap set type can store up to 65536 ports.  The portmap set
       type is very fast and memory cheap.

       Options to use when creating an portmap set:

       --from from-port

       --to to-port
              Create a portmap set from the specified port range.

   iphash
       The iphash set type uses a hash to store IP  addresses.   In  order  to
       avoid clashes in the hash double-hashing, and as a last resort, dynamic
       growing of the hash performed. The iphash set type is  great  to  store
       random addresses. If the optional --netmask parameter is specified with
       a CIDR prefix length value between  1-31  then  network  addresses  are
       stored  in  the  given set: i.e an IP address will be in the set if the
       network address, which is resulted by  masking  the  address  with  the
       specified netmask, can be found in the set.

       Options to use when creating an iphash set:

       --hashsize hashsize
              The initial hash size (default 1024)

       --probes probes
              How  many  times  try to resolve clashing at adding an IP to the
              hash by double-hashing (default 8).

       --resize percent
              Increase the hash size by this many percent  (default  50)  when
              adding  an  IP  to  the hash could not be performed after probes
              number of double-hashing.

       --netmask prefixlen
              When  the  optional  --netmask  parameter   specified,   network
              addresses will be stored in the set instead of IP addresses. The
              prefixlen value must be between 1-31.

       The iphash type of sets can store up to 65536  entries.  If  a  set  is
       full, no new entries can be added to it.

       Sets  created  by zero valued resize parameter won't be resized at all.
       The lookup time in an iphash type of set grows  approximately  linearly
       with  the value of the probes parameter. In general higher probes value
       results better utilized  hash  while  smaller  value  produces  larger,
       sparser hash.

       Example:

              ipset -N test iphash --probes 2

   nethash
       The  nethash  set  type  uses a hash to store different size of network
       addresses. The entry used in the ipset commands must  be  in  the  form
       "address/prefixlen"  where  prefixlen must be in the inclusive range of
       1-31.  In order to avoid clashes in the hash double-hashing, and  as  a
       last resort, dynamic growing of the hash performed.

       Options to use when creating an nethash set:

       --hashsize hashsize
              The initial hash size (default 1024)

       --probes probes
              How  many  times  try to resolve clashing at adding an IP to the
              hash by double-hashing (default 4).

       --resize percent
              Increase the hash size by this many percent  (default  50)  when
              adding an IP to the hash could not be performed after

       The  nethash  type  of  sets can store up to 65536 entries. If a set is
       full, no new entries can be added to it.

       An IP address will be in a nethash type of set if it belongs to any  of
       the  netblocks  added  to  the  set. The matching always start from the
       smallest size of netblock (most specific netmask) to the  largest  ones
       (least  specific  netmasks).  When  adding/deleting  IP  addresses to a
       nethash  set  by  the  "SET"  netfilter  kernel  module,  it  will   be
       added/deleted  by  the smallest netblock size which can be found in the
       set, or by /31 if the set is empty.

       The lookup time in a nethash type of set grows  approximately  linearly
       with the times of the probes parameter and the number of different mask
       parameters in the hash.  Otherwise the same speed and memory efficiency
       comments applies here as at the iphash type.

   ipporthash
       The ipporthash set type uses a hash to store IP address and port pairs.
       In order to avoid clashes in the hash double-hashing,  and  as  a  last
       resort,  dynamic  growing  of the hash performed. An ipporthash set can
       store up to 65536 (B-class network) IP addresses with all possible port
       values.  When adding, deleting and testing values in an ipporthash type
       of set, the entries must be specified as "address,port".

       The ipporthash types of sets evaluates two src/dst  parameters  of  the
       "set" match and "SET" target.

       Options to use when creating an ipporthash set:

       --from from-addr

       --to to-addr
              Create an ipporthash set from the specified address range.

       --network addr/mask
              Create an ipporthash set from the specified network.

       --hashsize hashsize
              The initial hash size (default 1024)

       --probes probes
              How  many  times  try to resolve clashing at adding an IP to the
              hash by double-hashing (default 8).

       --resize percent
              Increase the hash size by this many percent  (default  50)  when
              adding  an  IP  to  the hash could not be performed after probes
              number of double-hashing.

       The same resizing, speed and memory efficiency comments applies here as
       at the iphash type.

   ipportiphash
       The  ipportiphash  set type uses a hash to store IP address,port and IP
       address triples. The first IP address must  come  form  a  maximum  /16
       sized  network or range while the port number and the second IP address
       parameters are arbitrary. When adding, deleting and testing  values  in
       an  ipportiphash  type  of  set,  the  entries  must  be  specified  as
       "address,port,address".

       The ipportiphash types of sets evaluates three  src/dst  parameters  of
       the "set" match and "SET" target.

       Options to use when creating an ipportiphash set:

       --from from-addr

       --to to-addr
              Create an ipportiphash set from the specified address range.

       --network addr/mask
              Create an ipportiphash set from the specified network.

       --hashsize hashsize
              The initial hash size (default 1024)

       --probes probes
              How  many  times  try to resolve clashing at adding an IP to the
              hash by double-hashing (default 8).

       --resize percent
              Increase the hash size by this many percent  (default  50)  when
              adding  an  IP  to  the hash could not be performed after probes
              number of double-hashing.

       The same resizing, speed and memory efficiency comments applies here as
       at the iphash type.

   ipportnethash
       The  ipportnethash  set type uses a hash to store IP address, port, and
       network address triples. The IP address must come form  a  maximum  /16
       sized  network  or  range while the port number and the network address
       parameters are arbitrary, but the size of the network address  must  be
       between  /1-/31.  When  adding,  deleting  and  testing  values  in  an
       ipportnethash  type  of  set,  the  entries  must   be   specified   as
       "address,port,address/prefixlen".

       The  ipportnethash  types of sets evaluates three src/dst parameters of
       the "set" match and "SET" target.

       Options to use when creating an ipportnethash set:

       --from from-address

       --to to-address
              Create an ipporthash set from the specified range.

       --network address/mask
              Create an ipporthash set from the specified network.

       --hashsize hashsize
              The initial hash size (default 1024)

       --probes probes
              How many times try to resolve clashing at adding an  IP  to  the
              hash by double-hashing (default 8).

       --resize percent
              Increase  the  hash  size by this many percent (default 50) when
              adding an IP to the hash could not  be  performed  after  probes
              number of double-hashing.

       The same resizing, speed and memory efficiency comments applies here as
       at the iphash type.

   iptree
       The iptree set type uses a tree to store IP addresses, optionally  with
       timeout values.

       Options to use when creating an iptree set:

       --timeout value
              The timeout value for the entries in seconds (default 0)

       If a set was created with a nonzero valued --timeout parameter then one
       may add IP addresses to the set with a specific timeout value using the
       syntax  "address,timeout-value".   Similarly  to  the  hash  types, the
       iptree type of sets can store up to 65536 entries.

   iptreemap
       The iptreemap set type uses a tree to store IP addresses  or  networks,
       where the last octet of an IP address are stored in a bitmap.  As input
       entry, you can add IP addresses, CIDR blocks or network ranges  to  the
       set. Network ranges can be specified in the format "address1-address2".

       Options to use when creating an iptreemap set:

       --gc value
              How  often  the  garbage collection should be called, in seconds
              (default 300)

   setlist
       The setlist type uses a simple list in which you can store sets. By the
       ipset  command  you  can add, delete and test sets in a setlist type of
       set.  You can specify the sets  as  "setname[,{after|before},setname]".
       By  default  new  sets  are  added  after  (appended  to)  the existing
       elements. Setlist type of sets cannot be added to  a  setlist  type  of
       set.

       Options to use when creating a setlist type of set:

       --size size
              Create a setlist type of set with the given size (default 8).

       By  the "set" match or "SET" target of iptables(8) you can test, add or
       delete entries in the sets. The match will try to find  a  matching  IP
       address/port  in  the  sets  and  the  target  will  try  to add the IP
       address/port to the first set to which it can be added. The  number  of
       src,dst  options of the match and target are important: sets which eats
       more src,dst parameters than specified are  skipped,  while  sets  with
       equal  or less parameters are checked, elements added. For example if a
       and b are setlist type of sets then in the command

              iptables -m set --match-set a src,dst -j SET --add-set b src,dst

       the match and target will skip any set in a and  b  which  stores  data
       triples,  but will check all sets with single or double data storage in
       a set and add src to the first single or src,dst to  the  first  double
       data  storage  set  in  b.  You can imagine a setlist type of set as an
       ordered union of the set elements.

       Please note: by the ipset command you can  add,  delete  and  test  the
       setnames  in  a  setlist  type  of set, and not the presence of a set's
       member (such as an IP address).

GENERAL RESTRICTIONS

       Setnames starting with colon (:) cannot be  defined.  Zero  valued  set
       entries cannot be used with hash type of sets.

COMMENTS

       If  you  want  to store same size subnets from a given network (say /24
       blocks from a /8 network), use the ipmap set  type.   If  you  want  to
       store random same size networks (say random /24 blocks), use the iphash
       set type. If you have got random size of netblocks, use nethash.

       Old separator tokens (':' and '%") are still accepted.

       Binding support is removed.

DIAGNOSTICS

       Various error messages are printed to standard error.  The exit code is
       0 for correct functioning.  Errors which appear to be caused by invalid
       or abused command line parameters cause an exit code of  2,  and  other
       errors cause an exit code of 1.

BUGS

       Bugs? No, just funny features. :-) OK, just kidding...

SEE ALSO

       iptables(8),

AUTHORS

       Jozsef  Kadlecsik  wrote  ipset,  which  is  based  on ippool by Joakim
       Axelsson, Patrick Schaaf and Martin Josefsson.

       Sven Wegener wrote the iptreemap type.

LAST REMARK

       I stand on the shoulders of giants.

                                 Feb 05, 2004                         IPSET(8)