| Dir : /proc/self/root/opt/saltstack/salt/extras-3.10/pyroute2-0.7.12.dist-info/ |
| Server: Linux ngx353.inmotionhosting.com 4.18.0-553.22.1.lve.1.el8.x86_64 #1 SMP Tue Oct 8 15:52:54 UTC 2024 x86_64 IP: 209.182.202.254 |
| Dir : //proc/self/root/opt/saltstack/salt/extras-3.10/pyroute2-0.7.12.dist-info/METADATA |
Metadata-Version: 2.1
Name: pyroute2
Version: 0.7.12
Summary: Python Netlink library
Home-page: https://github.com/svinota/pyroute2
Author: Peter Saveliev
Author-email: peter@svinota.eu
License: GPL-2.0-or-later OR Apache-2.0
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Operating System :: POSIX :: Linux
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Development Status :: 4 - Beta
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: LICENSE.Apache-2.0
License-File: LICENSE.GPL-2.0-or-later
Requires-Dist: win-inet-pton ; platform_system == "Windows"
Requires-Dist: importlib-metadata ; python_version < "3.8"
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.6
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/