WiSet module

High level ipset support.

When IPSet module is providing a direct netlink socket with low level functions, a WiSet object is built to map ipset objects from kernel. It helps to add/remove entries, list content, etc.

For example, adding an entry with pyroute2.ipset.IPSet object implies to set a various number of parameters:

>>> ipset = IPSet()
>>> ipset.add("foo", "1.2.3.4/24", etype="net")
>>> ipset.close()

When they are discovered by a WiSet:

>>> wiset = load_ipset("foo")
>>> wiset.add("1.2.3.4/24")

Listing entries is also easier using WiSet, since it parses for you netlink messages:

>>> wiset.content
{'1.2.3.0/24': IPStats(packets=None, bytes=None, comment=None,
                       timeout=None, skbmark=None, physdev=False)}
pyroute2.wiset.need_ipset_socket(fun)

Decorator to create netlink socket if needed.

In many of our helpers, we need to open a netlink socket. This can be expensive for someone using many times the functions: instead to have only one socket and use several requests, we will open it again and again.

This helper allow our functions to be flexible: the caller can pass an optional socket, or do nothing. In this last case, this decorator will open a socket for the caller (and close it after call)

It also help to mix helpers. One helper can call another one: the socket will be opened only once. We just have to pass the ipset variable.

Note that all functions using this helper must use ipset as variable name for the socket.

class pyroute2.wiset.IPStats(packets, bytes, comment, timeout, skbmark, physdev=False, wildcard=False)
class pyroute2.wiset.WiSet(name=None, attr_type='hash:ip', family=AddressFamily.AF_INET, sock=None, timeout=None, counters=False, comment=False, hashsize=None, revision=None, skbinfo=False)

Main high level ipset manipulation class.

Every high level ipset operation should be possible with this class, you probably don't need other helpers of this module, except tools to load data from kernel (load_all_ipsets() and load_ipset())

For example, you can create and an entry in a ipset just with:

>>> with WiSet(name="mysuperipset") as myset:
>>>    myset.create()             # add the ipset in the kernel
>>>    myset.add("198.51.100.1")  # add one IP to the set

Netlink sockets are opened by __enter__ and __exit__ function, so you don't have to manage it manually if you use the "with" keyword.

If you want to manage it manually (for example for long operation in a daemon), you can do the following:

>>> myset = WiSet(name="mysuperipset")
>>> myset.open_netlink()
>>> # do stuff
>>> myset.close_netlink()

You can also don't initiate at all any netlink socket, this code will work:

>>> myset = WiSet(name="mysuperipset")
>>> myset.create()
>>> myset.destroy()

But do it very carefully. In that case, a netlink socket will be opened in background for any operation. No socket will be leaked, but that can consume resources.

You can also instantiate WiSet objects with load_all_ipsets() and load_ipset():

>>> all_sets_dict = load_all_ipsets()
>>> one_set = load_ipset(name="myset")

Have a look on content variable if you need list of entries in the Set.

Open manually a netlink socket.

You can use "with WiSet()" statement instead.

Clone any opened netlink socket

Create a ipset objects based on a parsed netlink message

Parameters:

  • ndmsg -- the netlink message to parse

  • content (bool) -- should we fill (and parse) entries info (can be slow on very large set)

update_dict_content(ndmsg)

Update a dictionary statistics with values sent in netlink message

Parameters:

ndmsg (netlink message) -- the netlink message

create(**kwargs)

Insert this Set in the kernel

Many options are set with python object attributes (like comments, counters, etc). For non-supported type, kwargs are provided. See IPSet module documentation for more information.

destroy()

Destroy this ipset in the kernel list.

It does not delete this python object (any content or other stored values are keep in memory). This function will fail if the ipset is still referenced (by example in iptables rules), you have been warned.

add(entry, **kwargs)

Add an entry in this ipset.

If counters are enabled on the set, reset by default the value when we add the element. Without this reset, kernel sometimes store old values and can add very strange behavior on counters.

delete(entry, **kwargs)

Delete/remove an entry in this ipset

test(entry, **kwargs)

Test if an entry is in this ipset

test_list(entries, **kwargs)

Test if a list of a set of entries is in this ipset

Return a set of entries found in the IPSet

update_content()

Update the content dictionary with values from kernel

flush()

Flush entries of the ipset

property content

Dictionary of entries in the set.

Keys are IP addresses (as string), values are IPStats tuples.

insert_list(entries)

Just a small helper to reduce the number of loops in main code.

replace_entries(new_list)

Replace the content of an ipset with a new list of entries.

This operation is like a flush() and adding all entries one by one. But this call is atomic: it creates a temporary ipset and swap the content.

Parameters:

new_list (list or set of basestring or of keyword arguments dict) -- list of entries to add

pyroute2.wiset.get_ipset_socket(**kwargs)

Get a socket that one can pass to several WiSet objects