Metadata-Version: 2.1
Name: pyroute2
Version: 0.7.5
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
Description: 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 = nsb.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/
        
Platform: UNKNOWN
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.6
Classifier: Programming Language :: Python :: 3.7
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: Development Status :: 4 - Beta
Description-Content-Type: text/x-rst
