IPSet module

ipset support.

This module is tested with hash:ip, hash:net, list:set and several other ipset structures (like hash:net,iface). There is no guarantee that this module is working with all available ipset modules.

It supports almost all kernel commands (create, destroy, flush, rename, swap, test...)

class pyroute2.ipset.PortRange(begin, end, protocol=None)

A simple container for port range with optional protocol

Note that optional protocol parameter is not supported by all kernel ipset modules using ports. On the other hand, it's sometimes mandatory to set it (like for hash:net,port ipsets)

Example:

udp_proto = socket.getprotobyname("udp")
port_range = PortRange(1000, 2000, protocol=udp_proto)
ipset.create("foo", stype="hash:net,port")
ipset.add("foo", ("192.0.2.0/24", port_range), etype="net,port")
ipset.test("foo", ("192.0.2.0/24", port_range), etype="net,port")
class pyroute2.ipset.PortEntry(port, protocol=None)

A simple container for port entry with optional protocol

class pyroute2.ipset.AsyncIPSet(version=None, attr_revision=None, nfgen_family=2)

NFNetlink socket (family=NETLINK_NETFILTER).

Implements API to the ipset functionality.

async headers(name, **kwargs)

Get headers of the named ipset. It can be used to test if one ipset exists, since it returns a no such file or directory.

async get_proto_version(version=6)

Get supported protocol version by kernel.

version parameter allow to set mandatory (but unused?) IPSET_ATTR_PROTOCOL netlink attribute in the request.

async list(*argv, **kwargs)

List installed ipsets. If name is provided, list the named ipset or return an empty list.

Be warned: netlink does not return an error if given name does not exit, you will receive an empty list.

async destroy(name=None)

Destroy one (when name is set) or all ipset (when name is None)

async create(name, stype='hash:ip', family=AddressFamily.AF_INET, exclusive=True, counters=False, comment=False, maxelem=None, forceadd=False, hashsize=None, timeout=None, bitmap_ports_range=None, size=None, skbinfo=False)

Create an ipset name of type stype, by default hash:ip.

Common ipset options are supported:

  • exclusive -- if set, raise an error if the ipset exists

  • counters -- enable data/packets counters

  • comment -- enable comments capability

  • maxelem -- max size of the ipset

  • forceadd -- you should refer to the ipset manpage

  • hashsize -- size of the hashtable (if any)

  • timeout -- enable and set a default value for entries (if not None)

  • bitmap_ports_range -- set the specified inclusive portrange for

    the bitmap ipset structure (0, 65536)

  • size -- Size of the list:set, the default is 8

  • skbinfo -- enable skbinfo capability

async add(name, entry, family=AddressFamily.AF_INET, exclusive=True, comment=None, timeout=None, etype='ip', skbmark=None, skbprio=None, skbqueue=None, wildcard=False, **kwargs)

Add a member to the ipset.

etype is the entry type that you add to the ipset. It's related to the ipset type. For example, use "ip" for one hash:ip or bitmap:ip ipset.

When your ipset store a tuple, like "hash:net,iface", you must use a comma a separator (etype="net,iface")

entry is a string for "ip" and "net" objects. For ipset with several dimensions, you must use a tuple (or a list) of objects.

"port" type is specific, since you can use integer of specialized containers like PortEntry and PortRange

Examples:

ipset = IPSet()
ipset.create("foo", stype="hash:ip")
ipset.add("foo", "198.51.100.1", etype="ip")

ipset = IPSet()
ipset.create("bar", stype="bitmap:port",
             bitmap_ports_range=(1000, 2000))
ipset.add("bar", 1001, etype="port")
ipset.add("bar", PortRange(1500, 2000), etype="port")

ipset = IPSet()
import socket
protocol = socket.getprotobyname("tcp")
ipset.create("foobar", stype="hash:net,port")
port_entry = PortEntry(80, protocol=protocol)
ipset.add("foobar", ("198.51.100.0/24", port_entry),
          etype="net,port")

wildcard option enable kernel wildcard matching on interface name for net,iface entries.

async delete(name, entry, family=AddressFamily.AF_INET, exclusive=True, etype='ip')

Delete a member from the ipset.

See add() method for more information on etype.

async test(name, entry, family=AddressFamily.AF_INET, etype='ip')

Test if entry is part of an ipset

See add() method for more information on etype.

async swap(set_a, set_b)

Swap two ipsets. They must have compatible content type.

async flush(name=None)

Flush all ipsets. When name is set, flush only this ipset.

async rename(name_src, name_dst)

Rename the ipset.

async get_set_byname(name)

Get a set by its name

async get_set_byindex(index)

Get a set by its index

async get_supported_revisions(stype, family=AddressFamily.AF_INET)

Return minimum and maximum of revisions supported by the kernel.

Each ipset module (like hash:net, hash:ip, etc) has several revisions. Newer revisions often have more features or more performances. Thanks to this call, you can ask the kernel the list of supported revisions.

You can manually set/force revisions used in IPSet constructor.

Example:

ipset = IPSet()
ipset.get_supported_revisions("hash:net")

ipset.get_supported_revisions("hash:net,port,net")
exception pyroute2.ipset.NoSuchObject(code, msg=None, cmd=None)

Specific exception on No such file or directory error

class pyroute2.ipset.IPSet(version=None, attr_revision=None, nfgen_family=2)