Pyroute2
========
Pyroute2 is a pure Python **netlink** library. The core requires only Python
stdlib, no 3rd party libraries. The library was started as an RTNL protocol
implementation, so the name is **pyroute2**, but now it supports many netlink
protocols. Some supported netlink families and protocols:
* **rtnl**, network settings --- addresses, routes, traffic controls
* **nfnetlink** --- netfilter API
* **ipq** --- simplest userspace packet filtering, iptables QUEUE target
* **devlink** --- manage and monitor devlink-enabled hardware
* **generic** --- generic netlink families
* **uevent** --- same uevent messages as in udev
Netfilter API:
* **ipset** --- IP sets
* **nftables** --- packet filtering
* **nfct** --- connection tracking
Generic netlink:
* **ethtool** --- low-level network interface setup
* **wireguard** --- VPN setup
* **nl80211** --- wireless functions API (basic support)
* **taskstats** --- extended process statistics
* **acpi_events** --- ACPI events monitoring
* **thermal_events** --- thermal events monitoring
* **VFS_DQUOT** --- disk quota events monitoring
On the low level the library provides socket objects with an
extended API. The additional functionality aims to:
* Help to open/bind netlink sockets
* Discover generic netlink protocols and multicast groups
* Construct, encode and decode netlink and PF_ROUTE messages
Supported systems
-----------------
Pyroute2 runs natively on Linux and emulates some limited subset
of RTNL netlink API on BSD systems on top of PF_ROUTE notifications
and standard system tools.
Other platforms are not supported.
NDB -- high level RTNL API
--------------------------
Key features:
* Data integrity
* Transactions with commit/rollback changes
* State synchronization
* Multiple sources, including netns and remote systems
A "Hello world" example:
.. code-block:: python
from pyroute2 import NDB
with NDB() as ndb:
with ndb.interfaces['eth0'] as eth0:
# set one parameter
eth0.set(state='down')
eth0.commit() # make sure that the interface is down
# or multiple parameters at once
eth0.set(ifname='hello_world!', state='up')
eth0.commit() # rename, bring up and wait for success
# --> <-- here you can be sure that the interface is up & renamed
More examples:
.. code-block:: python
from pyroute2 import NDB
ndb = NDB(log='debug')
for record in ndb.interfaces.summary():
print(record.ifname, record.address, record.state)
if_dump = ndb.interfaces.dump()
if_dump.select_records(state='up')
if_dump.select_fields('index', 'ifname', 'kind')
for line in if_dump.format('json'):
print(line)
addr_summary = ndb.addresses.summary()
addr_summary.select_records(ifname='eth0')
for line in addr_summary.format('csv'):
print(line)
with ndb.interfaces.create(ifname='br0', kind='bridge') as br0:
br0.add_port('eth0')
br0.add_port('eth1')
br0.add_ip('10.0.0.1/24')
br0.add_ip('192.168.0.1/24')
br0.set(
br_stp_state=1, # set STP on
br_group_fwd_mask=0x4000, # set LLDP forwarding
state='up', # bring the interface up
)
# --> <-- commit() will be run by the context manager
# operate on netns:
ndb.sources.add(netns='testns') # connect to a namespace
with (
ndb.interfaces.create(
ifname='veth0', # create veth
kind='veth',
peer={
'ifname': 'eth0', # setup peer
'net_ns_fd': 'testns', # in a namespace
},
state='up',
)
) as veth0:
veth0.add_ip(address='172.16.230.1', prefixlen=24)
with ndb.interfaces.wait(
target='testns', ifname='eth0'
) as peer: # wait for the peer
peer.set(state='up') # bring it up
peer.add_ip('172.16.230.2/24') # add address
IPRoute -- Low level RTNL API
-----------------------------
Low-level **IPRoute** utility --- Linux network configuration.
The **IPRoute** class is a 1-to-1 RTNL mapping. There are no implicit
interface lookups and so on.
Get notifications about network settings changes with IPRoute:
.. code-block:: python
from pyroute2 import IPRoute
with IPRoute() as ipr:
# With IPRoute objects you have to call bind() manually
ipr.bind()
for message in ipr.get():
print(message)
More examples:
.. code-block:: python
from socket import AF_INET
from pyroute2 import IPRoute
# get access to the netlink socket
ipr = IPRoute()
# no monitoring here -- thus no bind()
# print interfaces
for link in ipr.get_links():
print(link)
# create VETH pair and move v0p1 to netns 'test'
ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')
# wait for the devices:
peer, veth = ipr.poll(
ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')
)
ipr.link('set', index=peer['index'], net_ns_fd='test')
# bring v0p0 up and add an address
ipr.link('set', index=veth['index'], state='up')
ipr.addr('add', index=veth['index'], address='10.0.0.1', prefixlen=24)
# release Netlink socket
ip.close()
Network namespace examples
--------------------------
Network namespace manipulation:
.. code-block:: python
from pyroute2 import netns
# create netns
netns.create('test')
# list
print(netns.listnetns())
# remove netns
netns.remove('test')
Create **veth** interfaces pair and move to **netns**:
.. code-block:: python
from pyroute2 import IPRoute
with IPRoute() as ipr:
# create interface pair
ipr.link('add', ifname='v0p0', kind='veth', peer='v0p1')
# wait for the peer
(peer,) = ipr.poll(ipr.link, 'dump', timeout=5, ifname='v0p1')
# move the peer to the 'test' netns:
ipr.link('set', index=peer['index'], net_ns_fd='test')
List interfaces in some **netns**:
.. code-block:: python
from pyroute2 import NetNS
from pprint import pprint
ns = NetNS('test')
pprint(ns.get_links())
ns.close()
More details and samples see in the documentation.
Installation
------------
Using pypi:
.. code-block:: bash
pip install pyroute2
Using git:
.. code-block:: bash
pip install git+https://github.com/svinota/pyroute2.git
Using source, requires make and nox
.. code-block:: bash
git clone https://github.com/svinota/pyroute2.git
cd pyroute2
make install
Requirements
------------
Python >= 3.8
Links
-----
* home: https://pyroute2.org/
* source: https://github.com/svinota/pyroute2
* bugs: https://github.com/svinota/pyroute2/issues
* pypi: https://pypi.python.org/pypi/pyroute2
* docs: http://docs.pyroute2.org/
Raw data
{
"_id": null,
"home_page": "https://github.com/svinota/pyroute2",
"name": "pyroute2",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Peter Saveliev",
"author_email": "peter@svinota.eu",
"download_url": "https://files.pythonhosted.org/packages/4d/04/c9060b6cb024d05467e17ea93d3ca4bd2f3b05deb2372b7f79321640e8ad/pyroute2-0.8.1.tar.gz",
"platform": null,
"description": "Pyroute2\n========\n\nPyroute2 is a pure Python **netlink** library. The core requires only Python\nstdlib, no 3rd party libraries. The library was started as an RTNL protocol\nimplementation, so the name is **pyroute2**, but now it supports many netlink\nprotocols. Some supported netlink families and protocols:\n\n* **rtnl**, network settings --- addresses, routes, traffic controls\n* **nfnetlink** --- netfilter API\n* **ipq** --- simplest userspace packet filtering, iptables QUEUE target\n* **devlink** --- manage and monitor devlink-enabled hardware\n* **generic** --- generic netlink families\n* **uevent** --- same uevent messages as in udev\n\nNetfilter API:\n\n* **ipset** --- IP sets\n* **nftables** --- packet filtering\n* **nfct** --- connection tracking\n\nGeneric netlink:\n\n* **ethtool** --- low-level network interface setup\n* **wireguard** --- VPN setup\n* **nl80211** --- wireless functions API (basic support)\n* **taskstats** --- extended process statistics\n* **acpi_events** --- ACPI events monitoring\n* **thermal_events** --- thermal events monitoring\n* **VFS_DQUOT** --- disk quota events monitoring\n\nOn the low level the library provides socket objects with an\nextended API. The additional functionality aims to:\n\n* Help to open/bind netlink sockets\n* Discover generic netlink protocols and multicast groups\n* Construct, encode and decode netlink and PF_ROUTE messages\n\nSupported systems\n-----------------\n\nPyroute2 runs natively on Linux and emulates some limited subset\nof RTNL netlink API on BSD systems on top of PF_ROUTE notifications\nand standard system tools.\n\nOther platforms are not supported.\n\nNDB -- high level RTNL API\n--------------------------\n\nKey features:\n\n* Data integrity\n* Transactions with commit/rollback changes\n* State synchronization\n* Multiple sources, including netns and remote systems\n\nA \"Hello world\" example:\n\n.. code-block:: python\n\n from pyroute2 import NDB\n\n with NDB() as ndb:\n with ndb.interfaces['eth0'] as eth0:\n # set one parameter\n eth0.set(state='down')\n eth0.commit() # make sure that the interface is down\n # or multiple parameters at once\n eth0.set(ifname='hello_world!', state='up')\n eth0.commit() # rename, bring up and wait for success\n # --> <-- here you can be sure that the interface is up & renamed\n\nMore examples:\n\n.. code-block:: python\n\n from pyroute2 import NDB\n\n ndb = NDB(log='debug')\n\n for record in ndb.interfaces.summary():\n print(record.ifname, record.address, record.state)\n\n if_dump = ndb.interfaces.dump()\n if_dump.select_records(state='up')\n if_dump.select_fields('index', 'ifname', 'kind')\n for line in if_dump.format('json'):\n print(line)\n\n addr_summary = ndb.addresses.summary()\n addr_summary.select_records(ifname='eth0')\n for line in addr_summary.format('csv'):\n print(line)\n\n with ndb.interfaces.create(ifname='br0', kind='bridge') as br0:\n br0.add_port('eth0')\n br0.add_port('eth1')\n br0.add_ip('10.0.0.1/24')\n br0.add_ip('192.168.0.1/24')\n br0.set(\n br_stp_state=1, # set STP on\n br_group_fwd_mask=0x4000, # set LLDP forwarding\n state='up', # bring the interface up\n )\n # --> <-- commit() will be run by the context manager\n\n # operate on netns:\n ndb.sources.add(netns='testns') # connect to a namespace\n\n with (\n ndb.interfaces.create(\n ifname='veth0', # create veth\n kind='veth',\n peer={\n 'ifname': 'eth0', # setup peer\n 'net_ns_fd': 'testns', # in a namespace\n },\n state='up',\n )\n ) as veth0:\n veth0.add_ip(address='172.16.230.1', prefixlen=24)\n\n with ndb.interfaces.wait(\n target='testns', ifname='eth0'\n ) as peer: # wait for the peer\n peer.set(state='up') # bring it up\n peer.add_ip('172.16.230.2/24') # add address\n\nIPRoute -- Low level RTNL API\n-----------------------------\n\nLow-level **IPRoute** utility --- Linux network configuration.\nThe **IPRoute** class is a 1-to-1 RTNL mapping. There are no implicit\ninterface lookups and so on.\n\nGet notifications about network settings changes with IPRoute:\n\n.. code-block:: python\n\n from pyroute2 import IPRoute\n with IPRoute() as ipr:\n # With IPRoute objects you have to call bind() manually\n ipr.bind()\n for message in ipr.get():\n print(message)\n\nMore examples:\n\n.. code-block:: python\n\n from socket import AF_INET\n from pyroute2 import IPRoute\n\n # get access to the netlink socket\n ipr = IPRoute()\n # no monitoring here -- thus no bind()\n\n # print interfaces\n for link in ipr.get_links():\n print(link)\n\n # create VETH pair and move v0p1 to netns 'test'\n ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')\n # wait for the devices:\n peer, veth = ipr.poll(\n ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')\n )\n ipr.link('set', index=peer['index'], net_ns_fd='test')\n\n # bring v0p0 up and add an address\n ipr.link('set', index=veth['index'], state='up')\n ipr.addr('add', index=veth['index'], address='10.0.0.1', prefixlen=24)\n\n # release Netlink socket\n ip.close()\n\nNetwork namespace examples\n--------------------------\n\nNetwork namespace manipulation:\n\n.. code-block:: python\n\n from pyroute2 import netns\n # create netns\n netns.create('test')\n # list\n print(netns.listnetns())\n # remove netns\n netns.remove('test')\n\nCreate **veth** interfaces pair and move to **netns**:\n\n.. code-block:: python\n\n from pyroute2 import IPRoute\n\n with IPRoute() as ipr:\n\n # create interface pair\n ipr.link('add', ifname='v0p0', kind='veth', peer='v0p1')\n\n # wait for the peer\n (peer,) = ipr.poll(ipr.link, 'dump', timeout=5, ifname='v0p1')\n\n # move the peer to the 'test' netns:\n ipr.link('set', index=peer['index'], net_ns_fd='test')\n\nList interfaces in some **netns**:\n\n.. code-block:: python\n\n from pyroute2 import NetNS\n from pprint import pprint\n\n ns = NetNS('test')\n pprint(ns.get_links())\n ns.close()\n\nMore details and samples see in the documentation.\n\nInstallation\n------------\n\nUsing pypi:\n\n.. code-block:: bash\n\n pip install pyroute2\n\nUsing git:\n\n.. code-block:: bash\n\n pip install git+https://github.com/svinota/pyroute2.git\n\nUsing source, requires make and nox\n\n.. code-block:: bash\n\n git clone https://github.com/svinota/pyroute2.git\n cd pyroute2\n make install\n\nRequirements\n------------\n\nPython >= 3.8\n\nLinks\n-----\n\n* home: https://pyroute2.org/\n* source: https://github.com/svinota/pyroute2\n* bugs: https://github.com/svinota/pyroute2/issues\n* pypi: https://pypi.python.org/pypi/pyroute2\n* docs: http://docs.pyroute2.org/\n",
"bugtrack_url": null,
"license": "GPL-2.0-or-later OR Apache-2.0",
"summary": "Python Netlink library",
"version": "0.8.1",
"project_urls": {
"Homepage": "https://github.com/svinota/pyroute2"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "76cb0b7a8009a577eba01ea54556c921f3cbf67a52931da17b4dd97472d0e694",
"md5": "ddd5da5663edfb1a3a800d409af495a7",
"sha256": "f339be8acffc46cd87bca19217b559ea5838810b4b08836301a52cb2cb4c054b"
},
"downloads": -1,
"filename": "pyroute2-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ddd5da5663edfb1a3a800d409af495a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 474302,
"upload_time": "2024-12-20T14:41:15",
"upload_time_iso_8601": "2024-12-20T14:41:15.448292Z",
"url": "https://files.pythonhosted.org/packages/76/cb/0b7a8009a577eba01ea54556c921f3cbf67a52931da17b4dd97472d0e694/pyroute2-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4d04c9060b6cb024d05467e17ea93d3ca4bd2f3b05deb2372b7f79321640e8ad",
"md5": "6699294168d3051b2897a556ceeaf6c2",
"sha256": "b91f4a1f7abb9824637b1fe67e6e4a0a071d98d4a1a1b47ef792304ff3adad11"
},
"downloads": -1,
"filename": "pyroute2-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "6699294168d3051b2897a556ceeaf6c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 435829,
"upload_time": "2024-12-20T14:41:19",
"upload_time_iso_8601": "2024-12-20T14:41:19.138284Z",
"url": "https://files.pythonhosted.org/packages/4d/04/c9060b6cb024d05467e17ea93d3ca4bd2f3b05deb2372b7f79321640e8ad/pyroute2-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-20 14:41:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "svinota",
"github_project": "pyroute2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyroute2"
}
JSON
