0
# PySNMP
1

2
A comprehensive Pure Python SNMP library supporting SNMP v1, v2c, and v3 protocols with complete authentication and privacy capabilities. PySNMP provides both high-level and low-level APIs for building SNMP agents, managers, and network monitoring applications, with full compliance to IETF RFC standards.
3

4
## Package Information
5

6
- **Package Name**: pysnmp
7
- **Language**: Python
8
- **Installation**: `pip install pysnmp`
9
- **Version**: 7.1.21
10
- **License**: BSD-2-Clause
11

12
## Core Imports
13

14
```python
15
import pysnmp
16
```
17

18
For high-level async operations (recommended):
19

20
```python
21
from pysnmp.hlapi.v3arch.asyncio import *
22
```
23

24
For legacy imports:
25

26
```python
27
from pysnmp.hlapi.asyncio import *
28
```
29

30
For specific components:
31

32
```python
33
from pysnmp.hlapi.v3arch.asyncio import (
34
    SnmpEngine, CommunityData, UsmUserData,
35
    UdpTransportTarget, ContextData,
36
    get_cmd, set_cmd, walk_cmd, is_end_of_mib
37
)
38
```
39

40
For data types and SMI objects:
41

42
```python
43
from pysnmp.proto.rfc1902 import (
44
    Integer32, OctetString, ObjectIdentifier, Counter32, 
45
    Gauge32, TimeTicks, Counter64, Bits, IpAddress
46
)
47
from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType, NotificationType
48
from pysnmp.proto.rfc1905 import EndOfMibView, NoSuchObject, NoSuchInstance
49
```
50

51
## Basic Usage
52

53
### Simple SNMP GET Operation
54

55
```python
56
import asyncio
57
from pysnmp.hlapi.v3arch.asyncio import *
58

59
async def snmp_get():
60
    errorIndication, errorStatus, errorIndex, varBinds = await get_cmd(
61
        SnmpEngine(),
62
        CommunityData('public'),
63
        await UdpTransportTarget.create(('demo.pysnmp.com', 161)),
64
        ContextData(),
65
        ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'))
66
    )
67
    
68
    if errorIndication:
69
        print(f"Error: {errorIndication}")
70
    elif errorStatus:
71
        print(f"Error: {errorStatus.prettyPrint()}")
72
    else:
73
        for varBind in varBinds:
74
            print(f"{varBind[0]} = {varBind[1]}")
75

76
# Run the async function
77
asyncio.run(snmp_get())
78
```
79

80
### SNMPv3 with Authentication
81

82
```python
83
import asyncio
84
from pysnmp.hlapi.v3arch.asyncio import *
85

86
async def snmpv3_get():
87
    errorIndication, errorStatus, errorIndex, varBinds = await get_cmd(
88
        SnmpEngine(),
89
        UsmUserData('testuser', 
90
                   authKey='authenticationkey',
91
                   authProtocol=USM_AUTH_HMAC96_SHA),
92
        await UdpTransportTarget.create(('demo.pysnmp.com', 161)),
93
        ContextData(),
94
        ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'))
95
    )
96
    
97
    if not errorIndication and not errorStatus:
98
        for varBind in varBinds:
99
            print(f"{varBind[0]} = {varBind[1]}")
100

101
asyncio.run(snmpv3_get())
102
```
103

104
### SNMP Walk Operation
105

106
```python
107
import asyncio
108
from pysnmp.hlapi.v3arch.asyncio import *
109

110
async def snmp_walk():
111
    async for (errorIndication, errorStatus, errorIndex, varBinds) in walk_cmd(
112
        SnmpEngine(),
113
        CommunityData('public'),
114
        await UdpTransportTarget.create(('demo.pysnmp.com', 161)),
115
        ContextData(),
116
        ObjectType(ObjectIdentity('1.3.6.1.2.1.1')),  # Walk system subtree
117
        lexicographicMode=False
118
    ):
119
        if errorIndication:
120
            print(f"Error: {errorIndication}")
121
            break
122
        elif errorStatus:
123
            print(f"Error: {errorStatus.prettyPrint()}")
124
            break
125
        else:
126
            for varBind in varBinds:
127
                print(f"{varBind[0]} = {varBind[1]}")
128

129
asyncio.run(snmp_walk())
130
```
131

132
## Architecture
133

134
PySNMP is built around a layered architecture that provides flexibility from high-level convenience functions to low-level protocol control:
135

136
- **High-Level API (hlapi)**: User-friendly async/await interface for common SNMP operations
137
- **SNMP Engine**: Central coordinator managing authentication, transport, and message processing
138
- **Protocol Layer**: RFC-compliant implementation of SNMP v1/v2c/v3 protocols
139
- **Transport Layer**: Network communication over UDP/IPv4 and IPv6
140
- **SMI Framework**: Structure of Management Information for MIB object handling
141
- **Security**: Complete USM (User-based Security Model) with authentication and privacy
142

143
The library supports both SNMPv3 architecture (recommended) and legacy v1 architecture, with full backward compatibility and seamless integration with asyncio for modern Python applications.
144

145
## Capabilities
146

147
### High-Level API Operations
148

149
The primary interface for SNMP operations, providing async functions for GET, SET, WALK, and notification operations with built-in error handling and transport management.
150

151
```python { .api }
152
async def get_cmd(snmpEngine, authData, transportTarget, contextData, *varBinds, **options): ...
153
async def set_cmd(snmpEngine, authData, transportTarget, contextData, *varBinds, **options): ...
154
async def next_cmd(snmpEngine, authData, transportTarget, contextData, *varBinds, **options): ...
155
async def bulk_cmd(snmpEngine, authData, transportTarget, contextData, *varBinds, **options): ...
156
async def walk_cmd(snmpEngine, authData, transportTarget, contextData, *varBinds, **options): ...
157
async def bulk_walk_cmd(snmpEngine, authData, transportTarget, contextData, *varBinds, **options): ...
158
async def send_notification(snmpEngine, authData, transportTarget, contextData, notifyType, *varBinds, **options): ...
159
def is_end_of_mib(varBinds): ...
160
```
161

162
[High-Level API Operations](./high-level-api.md)
163

164
### Authentication and Security
165

166
Comprehensive authentication and privacy protocols for SNMP v1/v2c community strings and SNMPv3 User-based Security Model (USM) with multiple authentication and encryption algorithms.
167

168
```python { .api }
169
class CommunityData: ...
170
class UsmUserData: ...
171

172
# Authentication Protocols  
173
USM_AUTH_NONE: int
174
USM_AUTH_HMAC96_MD5: int
175
USM_AUTH_HMAC96_SHA: int
176
USM_AUTH_HMAC128_SHA224: int
177
USM_AUTH_HMAC192_SHA256: int
178
USM_AUTH_HMAC256_SHA384: int
179
USM_AUTH_HMAC384_SHA512: int
180

181
# Privacy Protocols
182
USM_PRIV_NONE: int
183
USM_PRIV_CBC56_DES: int
184
USM_PRIV_CBC168_3DES: int
185
USM_PRIV_CFB128_AES: int
186
USM_PRIV_CFB192_AES: int
187
USM_PRIV_CFB256_AES: int
188
USM_PRIV_CFB192_AES_BLUMENTHAL: int
189
USM_PRIV_CFB256_AES_BLUMENTHAL: int
190
```
191

192
[Authentication and Security](./authentication.md)
193

194
### SNMP Data Types and Exceptions
195

196
Complete implementation of SNMP data types from RFC 1902 and RFC 1905, including integers, strings, object identifiers, counters, gauges, and specialized exception values.
197

198
```python { .api }
199
class Integer32: ...
200
class OctetString: ...
201
class ObjectIdentifier: ...
202
class Counter32: ...
203
class Counter64: ...
204
class Gauge32: ...
205
class TimeTicks: ...
206
class IpAddress: ...
207
class Opaque: ...
208
class Bits: ...
209

210
# Exception Values
211
class NoSuchObject: ...
212
class NoSuchInstance: ...
213
class EndOfMibView: ...
214
class UnSpecified: ...
215
```
216

217
[SNMP Data Types and Exceptions](./data-types.md)
218

219
### Core Engine and Transport
220

221
SNMP engine management, transport targets for UDP/IPv4 and IPv6 communication, and context data for SNMP operations.
222

223
```python { .api }
224
class SnmpEngine: ...
225
class UdpTransportTarget: ...
226
class Udp6TransportTarget: ...
227
class ContextData: ...
228
```
229

230
### SMI Objects
231

232
Structure of Management Information objects for working with MIB variables, object identities, and SNMP notifications with automatic OID resolution.
233

234
```python { .api }
235
class ObjectIdentity: ...
236
class ObjectType: ...
237
class NotificationType: ...
238
```