Mini Shell

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/