pysnmplib 6.0.0rc16

SNMP library for Python

This is a pure-Python, open source and free implementation of v1/v2c/v3 SNMP engine distributed under 2-clause BSD license.

The PySNMP project was initially sponsored by a PSF grant. Thank you!

This version is a fork of Ilya Etingof deceased's project etingof/pysnmp. Ilya sadly passed away on 10-Aug-2022. Announcement here. His work is still of great use to the Python community and he will be missed.

Features

• Complete SNMPv1/v2c and SNMPv3 support
• SMI framework for resolving MIB information and implementing SMI Managed Objects
• Complete SNMP entity implementation
• USM Extended Security Options support (3DES, 192/256-bit AES encryption)
• Extensible network transports framework (UDP/IPv4, UDP/IPv6)
• Asyncio integration
• pysmi integration for dynamic MIB compilation
• Built-in instrumentation exposing protocol engine operations
• 100% Python, supports Python 3.10 and later
• MT-safe (if SnmpEngine is thread-local)

Features, specific to SNMPv3 model include:

• USM authentication (MD5/SHA-1/SHA-2) and privacy (DES/AES) protocols (RFC3414, RFC7860)
• View-based access control to use with any SNMP model (RFC3415)
• Built-in SNMP proxy PDU converter for building multi-lingual SNMP entities (RFC2576)
• Remote SNMP engine configuration
• Optional SNMP engine discovery
• Shipped with standard SNMP applications (RC3413)

Download & Install

The PySNMP software is freely available for download from PyPI and GitHub.

Just run:

$ pip install pysnmplib

That pulls in what an SNMP engine needs to run:

• PyASN1
• PyCryptodomex (required for SNMPv3 encryption; imported lazily, so SNMPv1, SNMPv2c and the SNMPv3 noAuthNoPriv/authNoPriv security levels work without it)

pysmi is not pulled in. It compiles ASN.1 MIB sources at run time, which some deployments do and most do not, so it is an extra:

$ pip install 'pysnmplib[compile]'

Without it everything except run-time MIB compilation works — including SNMPv3, name resolution and the standard MIBs an engine needs, which PySNMP ships. Asking for a MIB compiler when the extra is not installed raises SmiError naming the missing import.

MIB content is a separate thing again, and not a pip install: module definitions come from the MIB distribution, used live over HTTPS or installed locally from a release archive or an OCI image. PySNMP starts without it, on the standard modules it ships.

Examples

PySNMP is designed in a layered fashion. Top-level and easiest to use API is known as hlapi. Here's a quick example on how to SNMP GET:

from pysnmp.hlapi import *

iterator = getCmd(
    SnmpEngine(),
    CommunityData("public"),
    UdpTransportTarget(("localhost", 161)),
    ContextData(),
    ObjectType(ObjectIdentity("SNMPv2-MIB", "sysDescr", 0)),
)

errorIndication, errorStatus, errorIndex, varBinds = next(iterator)

if errorIndication:  # SNMP engine errors
    print(errorIndication)
else:
    if errorStatus:  # SNMP agent errors
        print(
            "%s at %s"
            % (
                errorStatus.prettyPrint(),
                varBinds[int(errorIndex) - 1] if errorIndex else "?",
            )
        )
    else:
        for varBind in varBinds:  # SNMP response contents
            print(" = ".join([x.prettyPrint() for x in varBind]))

This is how to send SNMP TRAP:

from pysnmp.hlapi import *

errorIndication, errorStatus, errorIndex, varBinds = next(
    sendNotification(
        SnmpEngine(OctetString(hexValue="8000000001020304")),
        UsmUserData(
            "usr-sha-aes128",
            "authkey1",
            "privkey1",
            authProtocol=usmHMACSHAAuthProtocol,
            privProtocol=usmAesCfb128Protocol,
        ),
        UdpTransportTarget(("localhost", 162)),
        ContextData(),
        "trap",
        NotificationType(ObjectIdentity("SNMPv2-MIB", "authenticationFailure")),
    )
)

if errorIndication:
    print(errorIndication)

$ python3 examples/hlapi/asyncio/manager/cmdgen/v1-get.py
SNMPv2-MIB::sysDescr.0 = Linux localhost 5.15.0
$
$ python3 examples/hlapi/asyncio/agent/ntforg/default-v1-trap.py
SNMPv2-MIB::sysUpTime.0 = 0
SNMPv2-MIB::snmpTrapOID.0 = SNMPv2-MIB::warmStart
SNMPv2-MIB::sysName.0 = system name

Other than that, PySNMP is capable to automatically fetch and use required MIBs from HTTP, FTP sites or local directories. You could configure any MIB source available to you (including the MIB distribution) for that purpose.

For more example scripts please refer to the examples/ directory in this repository.

Documentation

The rendered documentation is at https://pysnmp.github.io/pysnmp/, built from the docs/ directory in this repository. The organization site describes how pysnmp, the MIB distribution, pysmi and pyasn1 fit together.

If something does not work as expected, please open an issue at GitHub or post your question on Stack Overflow.

Bug reports and PRs are appreciated! ;-)

Copyright (c) 2005-2019, Ilya Etingof deceased. All rights reserved.