Pyroute2

https://github.com/svinota/pyroute2
Admin
Pyroute2 is a pure Python networking framework that provides synchronous and asynchronous APIs for...
Tokens:24,199
Snippets:185
Trust Score:9.1
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install pyroute2 from source

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Clones the repository and installs from source, requiring make and nox.

```bash
git clone https://github.com/svinota/pyroute2.git
cd pyroute2
make install
```

--------------------------------

### Start NDB with default settings

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_init.rst

Creates an NDB instance with default settings. This is the simplest way to start the database.

```python
ndb = NDB()
```

--------------------------------

### Equivalent nox Command for Test Session Configuration

Source: https://github.com/svinota/pyroute2/blob/master/README.contribute.rst

Equivalent to the previous make test example, but using the system's nox installation directly. Specifies the same core-python3.14 session and JSON configuration.

```bash
nox \
    -e core-python3.14 -- \
    '{ \
        "exitfirst": false, \
        "verbose": false, \
        "timeout": 10, \
        "pdb": true, \
        "sub": "test_plan9/test_basic.py" \
    }'

```

--------------------------------

### Test Session Configuration Example with make

Source: https://github.com/svinota/pyroute2/blob/master/README.contribute.rst

Example of running make test with a noxconfig JSON argument specifying exitfirst, verbose, timeout, pdb, and sub options. This demonstrates configuring test session behavior via the noxconfig argument.

```bash
make test \
    session=core-python3.14 \
    noxconfig='{ \
        "exitfirst": false, \
        "verbose": false, \
        "timeout": 10, \
        "pdb": true, \
        "sub": "test_plan9/test_basic.py" \
    }'

```

--------------------------------

### Install pyroute2 via git

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Installs the latest pyroute2 directly from the GitHub repository using pip.

```bash
pip install git+https://github.com/svinota/pyroute2.git
```

--------------------------------

### Install pyroute2 via pypi

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Installs the pyroute2 package from PyPI using pip.

```bash
pip install pyroute2
```

--------------------------------

### Setup Environment and Run Test Suite

Source: https://github.com/svinota/pyroute2/blob/master/README.contribute.rst

Clone the repository and run the test suite. Requires bash, git, python, GNU make, sed, and awk. Run 'sudo make test' to execute the tests.

```bash
# Make sure you have the following installed:
#   bash
#   git
#   python
#   GNU make, sed, awk

# Clone the repository
git clone ${pyroute2_git_url}
cd pyroute2

# Run the test suite
sudo make test

```

--------------------------------

### Async AsyncIPRoute link dump

Source: https://github.com/svinota/pyroute2/blob/master/docs/usage.rst

Async API example using AsyncIPRoute and asyncio.run. The output is identical to the sync version.

```python
import asyncio

from pyroute2 import AsyncIPRoute


async def main():
    ipr = AsyncIPRoute()
    async for link in await ipr.link("dump"):
        print(link.get("ifname"), link.get("state"), link.get("address"))
    ipr.close()

asyncio.run(main())

```

```text
lo up 00:00:00:00:00:00
eth0 up 52:54:00:72:58:b2

```

--------------------------------

### NDB Hello world example

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Shows how to use the NDB context manager to modify an interface: set parameters like state and ifname, commit changes, and ensure the interface is up and renamed.

```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
```

--------------------------------

### Start pyroute2-cli server and send requests with curl

Source: https://github.com/svinota/pyroute2/blob/master/docs/pyroute2-cli.rst

Starts the pyroute2-cli server in server mode and sends requests via curl. Shows text/plain and application/json content types, including a JSON script with multiple commands.

```bash
# start the server
pyroute2-cli -l debug -m S -a 127.0.0.1 -p 8080
```

```bash
# run a request
# text/plain: send a text script to the server
curl \
    -H "Content-Type: text/plain" \
    -d "neighbours summary | format json" \
    http://localhost:8080/v1/
```

```bash
# application/json: send a script as a JSON data
curl \
    -H "Content-Type: application/json" \
    -d '{"commands": ["neighbours summary | format json"]}'
    http://localhost:8080/v1/
```

```bash
curl \
    -H "Content-Type: application/json" \
    -d '{"commands": ["interfaces eth0", "set state down", "commit"]}'
    http://localhost:8080/v1/
```

--------------------------------

### Snapshot and rollback with nic.snapshot() and snapshot.apply(rollback=True)

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_debug.rst

Before commit, NDB marks records and stores snapshots. This example shows manual snapshot, apply, and rollback to restore state.

```python
>>> nic = ndb.interfaces['t0']
>>> nic['state']
'down'
>>> nic['state'] = 'up'
>>> snapshot = nic.snapshot()
>>> ndb.schema.snapshots
{
   'addresses_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'neighbours_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'routes_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'nh_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'p2p_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'ifinfo_bridge_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'ifinfo_bond_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'ifinfo_vlan_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'ifinfo_vxlan_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'ifinfo_gre_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'ifinfo_vrf_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'ifinfo_vti_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'ifinfo_vti6_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>,
   'interfaces_139736119707256': <weakref at 0x7f16d8391a98; to 'Interface' at 0x7f16d9c708e0>
}
>>> nic.apply()
...
>>> nic['state']
'up'
>>> snapshot.apply(rollback=True)
...
>>> nic['state']
'down'
```

```python
>>> nic = ndb.interfaces['t0']
>>> nic['state']
'down'
>>> nic['state'] = 'up'
>>> nic.commit()
>>> nic['state']
'up'
>>> nic.rollback()
>>> nic['state']
'down'
```

--------------------------------

### Run pyroute2-dhcp-client and inspect lease JSON

Source: https://github.com/svinota/pyroute2/blob/master/docs/pyroute2-dhcp-client.rst

Example of running pyroute2-dhcp-client with --disable-hooks, -R, and -x 5 on eth0, followed by the contents of the resulting eth0.lease.json file. The lease file shows the DHCP ACK details including IP, server, and lease timings.

```bash
# pyroute2-dhcp-client --disable-hooks -R -x 5 eth0
...
# cat eth0.lease.json
{
  "ack": {
    "op": 2,
    "htype": 1,
    "hlen": 6,
    "hops": 0,
    "xid": 391458644,
    "secs": 0,
    "flags": 32768,
    "ciaddr": "0.0.0.0",
    "yiaddr": "192.168.124.180",
    "siaddr": "192.168.124.1",
    "giaddr": "0.0.0.0",
    "chaddr": "aa:80:fa:2c:49:a2",
    "sname": "",
    "file": "",
    "cookie": "63:82:53:63",
    "options": {
      "message_type": 5,
      "server_id": "192.168.124.1",
      "lease_time": 3600,
      "renewal_time": 1800,
      "rebinding_time": 3150,
      "subnet_mask": "255.255.255.0",
      "broadcast_address": "192.168.124.255",
      "router": [
        "192.168.124.1"
      ],
      "name_server": [
        "192.168.124.1"
      ]
    }
  },
  "interface": "eth0",
  "server_mac": "52:54:00:e9:d3:1d",
  "obtained": 1740562827.7350075
}
```

--------------------------------

### Sync IPRoute link dump

Source: https://github.com/svinota/pyroute2/blob/master/docs/usage.rst

Sync API example that dumps all links and prints interface name, state, and MAC address. The output shows two lines for loopback and eth0.

```python
from pyroute2 import IPRoute

def main():
    ipr = IPRoute()
    for link in ipr.link("dump"):
        print(link.get("ifname"), link.get("state"), link.get("address"))
    ipr.close()

main()

```

```text
lo up 00:00:00:00:00:00
eth0 up 52:54:00:72:58:b2

```

--------------------------------

### IPRoute with custom event loop for uvloop

Source: https://github.com/svinota/pyroute2/blob/master/docs/asyncio.rst

Shows how to use pyroute2 with uvloop by providing a custom event loop via the use_event_loop parameter. The example creates a SelectorEventLoop with a SelectSelector and passes it to IPRoute.

```python
selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)

with IPRoute(use_event_loop=loop) as ipr:
    pass
```

--------------------------------

### Run Specific Test Sessions with make

Source: https://github.com/svinota/pyroute2/blob/master/README.contribute.rst

Run specific nox sessions via make test. The 'session' argument selects the session; examples show running tests/test_unit and tests/test_core with Python 3.14. Each session runs in its own virtual environment.

```bash
make test session=unit             # run only tests/test_unit
make test session=core-python3.14  # run tests/test_core with Python 3.14

```

--------------------------------

### AsyncIPRoute: Asynchronous RTNL API

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Shows the asynchronous equivalent of the IPRoute example using AsyncIPRoute. Note that .close() is synchronous in any case.

```python
import asyncio

from pyroute2 import AsyncIPRoute

async def main():
    # get access to the netlink socket
    ipr = AsyncIPRoute()

    # print interfaces
    async for link in await ipr.get_links():
        print(link)

    # create VETH pair and move v0p1 to netns 'test'
    await ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')

    # wait for the devices:
    peer, veth = await ipr.poll(
        ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')
    )
    await ipr.link('set', index=peer['index'], net_ns_fd='test')

    # bring v0p0 up and add an address
    await ipr.link('set', index=veth['index'], state='up')
    await ipr.addr('add', index=veth['index'], address='10.0.0.1', prefixlen=24)

    # release Netlink socket
    ipr.close()

asyncio.run(main())
```

--------------------------------

### Run a Specific Test Module within a Session

Source: https://github.com/svinota/pyroute2/blob/master/README.contribute.rst

Use the noxconfig argument to select a specific test module within a session. This example runs tests/test_linux/test_ndb/test_mpls.py in the linux-python3.14 session.

```bash
# Run tests/test_linux/test_ndb/test_mpls.py
make test session=linux-python3.14 \
    noxconfig='{"sub": "test_ndb/test_mpls.py"}'

```

--------------------------------

### Enable RTNL event logging with rtnl_debug=True

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_debug.rst

Start NDB with the debug option to store all loaded RTNL events in the DB. Warning: events log tables are unlimited and may exhaust memory; do not enable in production.

```python
ndb = NDB(rtnl_debug=True)
```

--------------------------------

### Low-level IPRoute get()

Source: https://github.com/svinota/pyroute2/blob/master/docs/usage.rst

Low-level socket usage: create an RTNL socket, bind to receive broadcast messages, and wait for parsed data with get(). Direct recv()/recvmsg() are not supported because sockets are monitored by the asyncio event loop.

```python
from pyroute2 import IPRoute

# create RTNL socket
ipr = IPRoute()

# subscribe to broadcast messages
ipr.bind()

# wait for parsed data
data = ipr.get()

```

--------------------------------

### Verify AsyncCoreSocket components with assertions

Source: https://github.com/svinota/pyroute2/blob/master/docs/asyncio.rst

Verifies the key components of AsyncCoreSocket: socket, transport, protocol, msg_queue, enqueue(), get(), and marshal. Uses assertions to confirm that enqueue() is synchronous and get() is an async generator.

```python
import asyncio
import inspect

from pyroute2 import IPRoute
from pyroute2.netlink.core import CoreMessageQueue
from pyroute2.netlink.marshal import Marshal

with IPRoute() as ipr:
    # AsyncCoreSocket.socket, compatibility, management
    assert callable(ipr.asyncore.socket.recv)
    assert callable(ipr.asyncore.socket.send)
    assert callable(ipr.asyncore.socket.recvmsg)
    assert callable(ipr.asyncore.socket.sendmsg)
    assert callable(ipr.asyncore.socket.bind)
    assert ipr.asyncore.transport._sock == ipr.asyncore.socket

    # AsyncCoreSocket.endpoint
    assert isinstance(ipr.asyncore.transport, asyncio.Transport)
    assert isinstance(ipr.asyncore.protocol, asyncio.Protocol)

    # msg_queue
    assert isinstance(ipr.asyncore.msg_queue, CoreMessageQueue)

    # enqueue()
    e_flags = ipr.asyncore.enqueue.__code__.co_flags
    assert callable(ipr.asyncore.enqueue)
    assert not e_flags & inspect.CO_ASYNC_GENERATOR

    # get()
    g_flags = ipr.asyncore.get.__code__.co_flags
    assert callable(ipr.asyncore.get)
    assert g_flags & inspect.CO_ASYNC_GENERATOR

    # marshal
    assert isinstance(ipr.asyncore.marshal, Marshal)
```

--------------------------------

### Example parsed RTNL message with NLA chain

Source: https://github.com/svinota/pyroute2/blob/master/docs/iproute_responses.rst

Example of a parsed RTNL message showing the NLA chain as a list-like structure and the injected 'event' field. Comments explain that NLAs are parsed on access, error handling, sequence numbers, and that type 16 equals RTM_NEWLINK.

```python
{'attrs': [('IFLA_IFNAME', 'lo'),    # [1]
               ('IFLA_TXQLEN', 1),
               ('IFLA_OPERSTATE', 'UNKNOWN'),
               ('IFLA_LINKMODE', 0),
               ('IFLA_MTU', 65536),
               ('IFLA_GROUP', 0),
               ('IFLA_PROMISCUITY', 0),
               ('IFLA_NUM_TX_QUEUES', 1),
               ('IFLA_NUM_RX_QUEUES', 1),
               ('IFLA_CARRIER', 1),
               ...],
 'change': 0,
 'event': 'RTM_NEWLINK',             # [2]
 'family': 0,
 'flags': 65609,
 'header': {'error': None,           # [3]
            'flags': 2,
            'length': 1180,
            'pid': 28233,
            'sequence_number': 257,  # [4]
            'type': 16},             # [5]
 'ifi_type': 772,
 'index': 1}

 # [1] every NLA is parsed upon access
 # [2] this field is injected by the RTNL parser
 # [3] if not None, an exception will be raised
 # [4] more details in the netlink description
 # [5] 16 == RTM_NEWLINK
```

--------------------------------

### IPRoute: Get RTNL broadcast notifications

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Binds to the netlink socket to listen for RTNL broadcasts and prints each received message. Use this to monitor network changes.

```python
from pyroute2 import IPRoute

with IPRoute() as ipr:
    ipr.bind()  # <--- start listening for RTNL broadcasts
    for message in ipr.get():  # receive the broadcasts
        print(message)
```

--------------------------------

### IPRoute: Manage links and addresses

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Demonstrates using IPRoute to create a veth pair, move a peer to a network namespace, bring an interface up, and add an address. The socket is closed synchronously.

```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
ipr.close()
```

--------------------------------

### create

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Creates a new network namespace.

```APIDOC
## create

### Description
Creates a new network namespace.

### Method
Function

### Signature
`create(name)`

### Parameters
- **name** (string) - Required - The name of the namespace to create.

```

--------------------------------

### Run pyroute2-cli CLI mode with -c, stdin, and script file

Source: https://github.com/svinota/pyroute2/blob/master/docs/pyroute2-cli.rst

Shows three ways to run pyroute2-cli in CLI mode: with a -c command, via stdin with a heredoc, and from a script file. The script commands bring eth0 up and add an IP address.

```bash
# bring eth0 up and add an IP address
pyroute2-cli -l debug -c "interfaces eth0 set { state up } => add_ip { 10.0.0.2/24 } => commit"
```

```bash
# same via stdin + pipe:
cat <<EOF | pyroute2-cli                                                                
> interfaces eth0
>     set { state up }
>     add_ip { 10.0.0.2/24 }
>     commit
> EOF
```

```bash
# run a script from a file script.pr2:
interfaces eth0
      set { state up }
      add_ip { 10.0.0.2/24 }
      commit

pyroute2-cli -l debug script.pr2
```

--------------------------------

### attach

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Attaches a process to a network namespace.

```APIDOC
## attach

### Description
Attaches a process to a network namespace.

### Method
Function

### Signature
`attach(pid, name)`

### Parameters
- **pid** (int) - Required - The process ID to attach.
- **name** (string) - Required - The name of the target namespace.

```

--------------------------------

### Run dhcp-server-detector with -1 option

Source: https://github.com/svinota/pyroute2/blob/master/docs/dhcp-server-detector.rst

Command to run dhcp-server-detector on interface wlp61s0 with the -1 flag to exit on first offer. The output is a JSON object containing the interface and full DHCP OFFER message details.

```bash
# dhcp-server-detector -1 wlp61s0
{
  "interface": "wlp61s0",
  "message": {
    "dhcp": {
      "op": 2,
      "htype": 1,
      "hlen": 6,
      "hops": 0,
      "xid": 2900208454,
      "secs": 0,
      "flags": 32768,
      "ciaddr": "0.0.0.0",
      "yiaddr": "192.168.94.166",
      "siaddr": "0.0.0.0",
      "giaddr": "0.0.0.0",
      "chaddr": "a0:a4:c5:93:ac:60",
      "sname": "",
      "file": "",
      "cookie": "63:82:53:63",
      "options": {
        "message_type": 2,
        "server_id": "192.168.94.254",
        "lease_time": 43200,
        "subnet_mask": "255.255.255.0",
        "router": [
            "192.168.94.254"
        ],
        "name_server": [
            "192.168.94.254"
        ],
        "broadcast_address": "192.168.94.255"
      }
    },
    "eth_src": "14:0c:76:62:51:64",
    "eth_dst": "ff:ff:ff:ff:ff:ff",
    "ip_src": "192.168.94.254",
    "ip_dst": "255.255.255.255",
    "sport": 67,
    "dport": 68
  }
}
```

--------------------------------

### Network namespace management with netns

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Shows how to create, list, and remove network namespaces using the netns module.

```python
from pyroute2 import netns
# create netns
netns.create('test')
# list
print(netns.listnetns())
# remove netns
netns.remove('test')
```

--------------------------------

### Use sqlite3 database provider with db_spec

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_init.rst

Creates an NDB instance using the sqlite3 database provider with a file named 'test.db'. The subsequent shell command queries the interfaces table to show the stored interface names.

```python
ndb_fs = NDB(db_provider='sqlite3', db_spec='test.db')
...
$ echo 'select f_ifla_ifname from interfaces' | sqlite3 test.db
lo
enp0s31f6
wlp58s0
virbr0
virbr0-nic
...
```

--------------------------------

### High-level addr dump with context manager

Source: https://github.com/svinota/pyroute2/blob/master/docs/usage.rst

High-level context manager usage to dump IP addresses and print address/prefix length pairs. The output shows loopback and a local network address.

```python
from pyroute2 import IPRoute

# RTNL interface
with IPRoute() as ipr:
    # get IP addresses
    for msg in ipr.addr("dump"):
        addr = msg.get("address")
        mask = msg.get("prefixlen")
        print(f"{addr}/{mask}")

```

```text
127.0.0.1/8
192.168.122.28/24

```

--------------------------------

### NetNS compatibility wrapper

Source: https://github.com/svinota/pyroute2/blob/master/docs/iproute_netns.rst

Uses the legacy NetNS class as a compatibility wrapper for the new API to open a socket in the 'test' network namespace and print the current netns.

```python
from pyroute2 import NetNS

with NetNS("test") as ns:
    print(f"current netns: {ns.status['netns']}")
```

```output
current netns: test
```

--------------------------------

### Create veth pair and move to netns

Source: https://github.com/svinota/pyroute2/blob/master/README.rst

Creates a veth pair, waits for the peer, and moves it to a network namespace using IPRoute.

```python
from pyroute2 import IPRoute

with IPRoute() as ipr:

    # create interface pair
    ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')

    # wait for the peer
    (peer,) = ipr.poll(ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1'))

    # move the peer to the 'test' netns:
    ipr.link('set', index=peer['index'], net_ns_fd='test')
```

--------------------------------

### AsyncIPRoute with netns argument

Source: https://github.com/svinota/pyroute2/blob/master/docs/iproute_netns.rst

Initializes an AsyncIPRoute socket within the 'test' network namespace and prints the current netns from the socket status. The output shows the expected result.

```python
import asyncio

from pyroute2 import AsyncIPRoute


async def main():
    async with AsyncIPRoute(netns="test") as ipr:
        print(f"current netns: {ipr.status['netns']}")

asyncio.run(main())
```

```output
current netns: test
```

--------------------------------

### Import CoreSocket and AsyncCoreSocket

Source: https://github.com/svinota/pyroute2/blob/master/docs/asyncio.rst

Imports the synchronous CoreSocket and its asynchronous counterpart AsyncCoreSocket. CoreSocket is a wrapper around AsyncCoreSocket and operates on the asyncio event loop.

```python
from pyroute2.netlink.core import AsyncCoreSocket, CoreSocket
```

--------------------------------

### listnetns

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Lists all available network namespaces.

```APIDOC
## listnetns

### Description
Lists all available network namespaces.

### Method
Function

### Signature
`listnetns()`

### Returns
- **list** - A list of namespace names.

```

--------------------------------

### CoreSocket composition with asyncore property

Source: https://github.com/svinota/pyroute2/blob/master/docs/asyncio.rst

Shows that CoreSocket uses composition rather than inheritance to expose the asynchronous API via the .asyncore property. The assertions verify that cs.asyncore is an AsyncCoreSocket instance, while CoreSocket itself is not.

```python
with CoreSocket() as cs:
    assert isinstance(cs.asyncore, AsyncCoreSocket)
    assert not isinstance(cs, AsyncCoreSocket)
    assert not issubclass(CoreSocket, AsyncCoreSocket)
```

--------------------------------

### Import NetNS from root module

Source: https://github.com/svinota/pyroute2/blob/master/docs/usage.rst

Shows two ways to import NetNS: directly from pyroute2.iproute.linux (signature may change) and from the root module pyroute2 (stable signature).

```python
# Import a pyroute2 class directly. In the next versions
# the import signature can be changed, e.g., NetNS from
# pyroute2.netns.nslink it can be moved somewhere else.
#
from pyroute2.iproute.linux import NetNS
ns = NetNS('test')

# Import the same class from root module. This signature
# will stay the same, any layout change is reflected in
# the root module.
#
from pyroute2 import NetNS
ns = NetNS('test')

```

--------------------------------

### NDB list lwtunnel routes

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

List lwtunnel routes using NDB's dump and filter by encap not being None.

```python
>>> ndb.routes.dump().filter(lambda x: x.encap is not None)
('localhost', 0, 2, 24, 0, 0, 254, 4, 0, 1, 16, '10.255.145.0', ...
('localhost', 0, 2, 24, 0, 0, 254, 4, 0, 1, 0, '192.168.142.0', ...

>>> ndb.routes.dump().filter(lambda x: x.encap is not None).select('dst', 'encap') 
('10.255.145.0', '[{"label": 20, "tc": 0, "bos": 0, "ttl": 0}, ...
('192.168.142.0', '[{"label": 20, "tc": 0, "bos": 0, "ttl": 0}, ...
```

--------------------------------

### Parallel DHCP server detection with jq output

Source: https://github.com/svinota/pyroute2/blob/master/docs/dhcp-server-detector.rst

Command that runs dhcp-server-detector on all interfaces in parallel for 3 seconds and pipes the JSON output to jq to extract interface names.

```bash
# does the same as the script above, but polls all interfaces in parallel
# for 3s max before exiting
dhcp-server-detector -d 3 $(ip --json l | jq -r '.[].ifname') |\
    jq -r .interface
```

--------------------------------

### Check object state transitions in state log

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_debug.rst

Create an interface and inspect its state events to see transitions from 'invalid' to 'system'. Timestamps correlate with NDB and RTNL event logs.

```python
>>> from pyroute2 import NDB
>>> ndb = NDB()
>>> c = ndb.interfaces.create(ifname='t0', kind='dummy').commit()
>>> c.state.events
[
   (1557752212.6703758, 'invalid'),
   (1557752212.6821117, 'system')
]
```

--------------------------------

### pushns

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Pushes the current network namespace onto a stack and switches to a new one.

```APIDOC
## pushns

### Description
Pushes the current network namespace onto a stack and switches to a new one.

### Method
Function

### Signature
`pushns(name)`

### Parameters
- **name** (string) - Required - The name of the namespace to switch to.

```

--------------------------------

### Enable and disable NDB logging

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_debug.rst

Set up stderr logging on DB init or at runtime, and turn it off. Also supports logging to a file or syslog server.

```python
# to start logging on the DB init
ndb = NDB(log='on')

# ... or to start it in run time
ndb.log('on')

# ... the same as above, another syntax
ndb.log.on

# ... turn logging off
ndb.log('off')

# ... or
ndb.log.off
```

```python
#
ndb.log('file_name.log')

#
ndb.log('syslog://server:port')
```

--------------------------------

### Configure NDB with multiple sources and log output

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_init.rst

Configures NDB to use multiple RTNL sources: two network namespaces (test01, test02) and a local source. The log='on' option enables stdio logging, and the output shows the debug messages during source initialization and connection.

```python
sources = [{'netns': 'test01'},
               {'netns': 'test02'},
               {'target': 'localhost', 'kind': 'local'}]
>>> ndb = NDB(log='on', sources=sources)
2020-03-24 18:01:48,241    DEBUG pyroute2.ndb.139900805197264.sources.test01: init
2020-03-24 18:01:48,242    DEBUG pyroute2.ndb.139900805197264.sources.test01: starting the source
2020-03-24 18:01:48,242    DEBUG pyroute2.ndb.139900805197264.sources.test02: init
2020-03-24 18:01:48,243    DEBUG pyroute2.ndb.139900805197264.sources.test01: connecting
2020-03-24 18:01:48,248    DEBUG pyroute2.ndb.139900805197264.sources.test02: starting the source
2020-03-24 18:01:48,249    DEBUG pyroute2.ndb.139900805197264.sources.localhost: init
2020-03-24 18:01:48,250    DEBUG pyroute2.ndb.139900805197264.sources.test02: connecting
2020-03-24 18:01:48,256    DEBUG pyroute2.ndb.139900805197264.sources.localhost: starting the source
2020-03-24 18:01:48,259    DEBUG pyroute2.ndb.139900805197264.sources.localhost: connecting
2020-03-24 18:01:48,262    DEBUG pyroute2.ndb.139900805197264.sources.localhost: loading
2020-03-24 18:01:48,265    DEBUG pyroute2.ndb.139900805197264.sources.test01: loading
2020-03-24 18:01:48,278    DEBUG pyroute2.ndb.139900805197264.sources.test02: loading
2020-03-24 18:01:48,478    DEBUG pyroute2.ndb.139900805197264.sources.localhost: running
2020-03-24 18:01:48,499    DEBUG pyroute2.ndb.139900805197264.sources.test01: running
2020-03-24 18:01:48,537    DEBUG pyroute2.ndb.139900805197264.sources.test02: running
```

--------------------------------

### Use NDB as context manager

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_init.rst

Uses NDB as a context manager. The instance is automatically synchronized and stopped when the with block exits.

```python
with NDB() as ndb:
    ...
    ...
#
# ---> <--- here the NDB instance will be synchronized and stopped
```

--------------------------------

### setns

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Sets the current process's network namespace.

```APIDOC
## setns

### Description
Sets the current process's network namespace.

### Method
Function

### Signature
`setns(name)`

### Parameters
- **name** (string) - Required - The name of the namespace to switch to.

```

--------------------------------

### IPRoute with flags=0 to fail on missing netns

Source: https://github.com/svinota/pyroute2/blob/master/docs/iproute_netns.rst

Attempts to open an IPRoute socket in the 'foo' netns with flags=0, which causes a FileNotFoundError if the namespace does not exist. The default flags are os.O_CREAT, which would create the namespace if missing.

```python
from pyroute2 import IPRoute

try:
    ipr = IPRoute(netns="foo", flags=0)
except FileNotFoundError:
    print("netns doesn't exist, refuse to start")
```

```output
netns doesn't exist, refuse to start
```

--------------------------------

### Shell script to detect DHCP servers on all interfaces

Source: https://github.com/svinota/pyroute2/blob/master/docs/dhcp-server-detector.rst

Bash script that iterates over all interfaces using ip and jq, runs dhcp-server-detector with -d 1 -1 for each, and prints a message if a DHCP server is found.

```bash
# prints a line for every interface on which a DHCP server is detected.
# waits 1 second for each interface.
for ifname in $(ip --json l | jq -r '.[].ifname'); do
    if dhcp-server-detector -d 1 -1 $ifname > /dev/null; then
        echo "DHCP server found on $ifname"
    fi
done
```

--------------------------------

### Access fields and nested NLAs with .get()

Source: https://github.com/svinota/pyroute2/blob/master/docs/iproute_responses.rst

Shows how to use the .get() method to access fields, NLAs, and nested NLAs by passing a tuple of NLA names. Returns None if the NLA is not present.

```python
from pyroute2 import IPRoute

with IPRoute() as ipr:
    lo = tuple(ipr.link("get", index=1))[0]
    # get a field
    assert lo.get("index") == 1
    # get an NLA
    assert lo.get("ifname") == "lo"
    # get a nested NLA
    assert lo.get(("stats64", "rx_bytes")) == 43309665
```

--------------------------------

### NDB create MPLS route

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

Create an MPLS route using NDB's routes.create with AF_MPLS family and a label stack.

```python
>>> from pyroute2.common import AF_MPLS
>>> ndb.routes.create(family=AF_MPLS,
                      dst=128,                       # label
                      oif=1,                         # output interface
                      newdst=[128, 132]).commit()    # label stack
```

--------------------------------

### NDB create lwtunnel route

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

Create an lwtunnel route using NDB's routes.create with an MPLS encap.

```python
>>> ndb.routes.create(dst='192.168.145.0/24',
                      gateway='192.168.140.5', 
                      encap={'type': 'mpls',
                             'labels': [128, 132]}).commit()
```

--------------------------------

### remove

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Removes an existing network namespace.

```APIDOC
## remove

### Description
Removes an existing network namespace.

### Method
Function

### Signature
`remove(name)`

### Parameters
- **name** (string) - Required - The name of the namespace to remove.

```

--------------------------------

### Export NDB database with schema.export()

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_debug.rst

Dump all DB data to stderr or to a file. Useful for post-mortem analysis.

```python
with NDB() as ndb:
   ndb.schema.export('stderr')  # dump the DB to stderr
   ...
   ndb.schema.export('pr2_debug')  # dump the DB to a file
```

--------------------------------

### Retrieve multiple NLAs with .get_attrs()

Source: https://github.com/svinota/pyroute2/blob/master/docs/iproute_responses.rst

Demonstrates chaining .get() and .get_attrs() to retrieve all NLAs with a given name in a hierarchy. Use get_attrs() when multiple NLAs of the same type may exist, such as IFLA_MACVLAN_MACADDR.

```python
# for macvlan interfaces there may be several
# IFLA_MACVLAN_MACADDR NLA provided, so use
# get_attrs() to get all the list, not only
# the first one

(msg
 .get('IFLA_LINKINFO')                # one NLA
 .get('IFLA_INFO_DATA')               # one NLA
 .get_attrs('IFLA_MACVLAN_MACADDR'))  # a list of
```

--------------------------------

### popns

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Pops the network namespace stack and switches back to the previous namespace.

```APIDOC
## popns

### Description
Pops the network namespace stack and switches back to the previous namespace.

### Method
Function

### Signature
`popns()`

```

--------------------------------

### NDB list MPLS routes

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

List MPLS routes using NDB's dump and filter by family. The output shows route tuples.

```python
>>> from pyroute2.common import AF_MPLS
>>> ndb.routes.dump().filter(family=AF_MPLS)
('localhost', 0, 28, 20, 0, 0, 254, 4, 0, 1, 0, ...
('localhost', 0, 28, 20, 0, 0, 254, 4, 0, 1, 0, ...

>>> ndb.routes.dump().filter(family=AF_MPLS).select('oif', 'dst', 'newdst')
(40627, '[{"label": 16, "tc": 0, "bos": 1, "ttl": 0}]', '[{"label": 500, ...
(40627, '[{"label": 40, "tc": 0, "bos": 1, "ttl": 0}]', '[{"label": 40, ...
```

--------------------------------

### pid_to_ns

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Returns the network namespace identifier for a given PID.

```APIDOC
## pid_to_ns

### Description
Returns the network namespace identifier for a given PID.

### Method
Function

### Signature
`pid_to_ns(pid)`

### Parameters
- **pid** (int) - Required - The process ID.

### Returns
- **string** - The namespace identifier.

```

--------------------------------

### ns_pids

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Returns the PIDs of processes in a given network namespace.

```APIDOC
## ns_pids

### Description
Returns the PIDs of processes in a given network namespace.

### Method
Function

### Signature
`ns_pids(name)`

### Parameters
- **name** (string) - Required - The name of the namespace.

### Returns
- **list** - A list of PIDs.

```

--------------------------------

### IPRoute MPLS label push

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

Create an MPLS route that pushes a label stack using IPRoute. The 'dst' field can only specify one label, even if a list is given.

```python
req = {"family": AF_MPLS,
       "oif": idx,
       "dst": 20,
       "newdst": [20, 30]}
ipr.route("add", **req)
```

--------------------------------

### IPRoute MPLS route with via field

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

Set up an MPLS route with a 'via' field to specify the next hop address.

```python
from socket import AF_INET

req = {"family": AF_MPLS,
       "oif": idx,
       "dst": 20,
       "newdst": [30],
       "via": {"family": AF_INET,
               "addr": "1.2.3.4"}}
ipr.route("add", **req)
```

--------------------------------

### IPRoute MPLS label swap

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

Create an MPLS route that swaps a label using IPRoute. Requires an interface index and uses AF_MPLS family.

```python
from pyroute2 import IPRoute
from pyroute2.common import AF_MPLS

ipr = IPRoute()
# get the `eth0` interface's index:
idx = ipr.link_lookup(ifname="eth0")[0]
# create the request
req = {"family": AF_MPLS,
       "oif": idx,
       "dst": 20,
       "newdst": [30]}
# set up the route
ipr.route("add", **req)
```

--------------------------------

### IPRoute MPLS lwtunnel

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

Inject IP packets into MPLS using an lwtunnel encap with a label stack.

```python
req = {"dst": "1.2.3.0/24",
       "oif": idx,
       "encap": {"type": "mpls",
                  "labels": [202, 303]}}
ipr.route("add", **req)
```

--------------------------------

### dropns

Source: https://github.com/svinota/pyroute2/blob/master/docs/netns.rst

Drops the current network namespace.

```APIDOC
## dropns

### Description
Drops the current network namespace.

### Method
Function

### Signature
`dropns()`

```

--------------------------------

### Inspect RTNL object cache keys and values

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_debug.rst

Show the keys and values of the ndb.interfaces.cache set, which holds references to created RTNL objects.

```python
>>> ndb.interfaces.cache.keys()
[(('target', u'localhost'), ('index', 2)),
 (('target', u'localhost'), ('index', 39615))]
```

```python
>>> [x['ifname'] for x in ndb.interfaces.cache.values()]
[u'eth0', u't2']
```

--------------------------------

### MPLS label formats

Source: https://github.com/svinota/pyroute2/blob/master/docs/mpls.rst

Possible label formats for the 'newdst' field: int, list of ints, string, dict, and list of dicts.

```python
# int
"newdst": 20

# list of ints
"newdst": [20]
"newdst": [20, 30]

# string
"newdst": "20/30"

# dict
"newdst": {"label": 20}

# list of dicts
"newdst": [{"label": 20, "tc": 0, "bos": 0, "ttl": 16},
           {"label": 30, "tc": 0, "bos": 1, "ttl": 16}]
```

--------------------------------

### Close NDB instance

Source: https://github.com/svinota/pyroute2/blob/master/docs/ndb_init.rst

Explicitly closes and stops the NDB instance to finish pending calls and synchronize. This is recommended before exiting.

```python
ndb = NDB()
...
ndb.close()
```

--------------------------------

### Mandatory message fields for NetlinkSocketBase

Source: https://github.com/svinota/pyroute2/blob/master/docs/parser.rst

Mandatory fields that a message parser must return for NetlinkSocketBase methods. The 'error' field must be None or a NetlinkError instance.

```python
{
    'header': {
        'type': int,
        'flags': int,
        'error': None or NetlinkError(),
        'sequence_number': int,
    }
}
```
Tokens:
Raw