SNMPTCPMgr Class
Properties Methods Events Configuration Settings Errors
The SNMPTCPMgr class is used to implement TCP-based SNMP Management Applications.
Syntax
class ipworkssnmp.SNMPTCPMgr
Remarks
The SNMPTCPMgr class implements a TCP-based standard SNMP Manager as specified in the SNMP RFCs. The class supports SNMP v1, v2c, and v3.
The class provides both encoding/decoding and transport capabilities, making the task of developing a custom SNMP manager as simple as setting a few key properties and handling a few events. SNMP data, such as for instance SNMP object id-s (OID-s) are exchanged as text strings, thus further simplifying the task of handling them.
The class is activated/deactivated by setting the active property. This property enables or disables sending and receiving.
Messages are received through events such as on_response, on_trap, or on_inform_request. SNMP Traps are received through the on_trap event.
Messages are sent to other agents or managers by using class's methods such as send_get_request, send_get_next_request, send_get_bulk_request, send_set_request, and send_inform_request.
SNMP OIDs, types, and values are provided in the objects collection of SNMP objects for both sent and received packets.
SNMPv3 USM security is enabled by setting properties such as user, authentication_password, and encryption_password and calling the discover method to bind to a particular agent (remote_engine_id). Upon successful discovery, received packets are checked for integrity (authentication) and timeliness. Note that the discovery step is optional, and may be avoided if the values for remote_engine_id, remote_engine_boots, and remote_engine_time are known in advance and provided to the class through the respective properties.
By default, the class operates synchronously (except for the discover method), sending a request and waiting until the corresponding response has been received. This behavior may be overridden by setting timeout to 0, in which case the class returns control immediately after a send, and responses are received exclusively through the on_response event.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
accept_data | Enables or disables data reception. |
active | Enables or disables sending and receiving of SNMP packets. |
authentication_password | The password used for SNMPv3 authentication. |
authentication_protocol | The authentication protocol used for SNMPv3 packets. |
community | The community string used to authenticate SNMP packets. |
encryption_algorithm | The encryption algorithm used for SNMPv3 packets. |
encryption_password | The password used for SNMPv3 privacy. |
error_description | Description of the status code for the last SNMP packet received by the class. |
error_index | Index of the first variable (object) that caused an error from the last SNMP response. |
error_status | Status code for the last SNMP packet received by the class. |
local_engine_id | The Engine Id of the SNMP Manager. |
local_host | The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
local_port | The port in the local host where the SNMP Manager is bound to. |
obj_count | The number of records in the Obj arrays. |
obj_type | The current object's type. |
obj_id | The current object's id which is encoded as a string of numbers separated by periods. |
obj_type_string | A string representation of the current object's ObjectType . |
obj_value | The current object's value. |
remote_engine_boots | The remote engine boots (SNMPv3). |
remote_engine_id | The Engine Id of the remote agent. |
remote_engine_time | The remote engine time (SNMPv3). |
remote_host | The address of the remote host. Domain names are resolved to IP addresses. |
remote_port | The port where the remote SNMP agent is listening. |
request_id | The request-id to mark outgoing packets with. |
snmp_version | Version of SNMP used for outgoing requests. |
ssl_accept_server_cert_encoded | The certificate (PEM/base64 encoded). |
ssl_authenticate_clients | If true, the server asks the client(s) for a certificate. |
ssl_cert_encoded | The certificate (PEM/base64 encoded). |
ssl_cert_store | The name of the certificate store for the client certificate. |
ssl_cert_store_password | If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store. |
ssl_cert_store_type | The type of certificate store for this certificate. |
ssl_cert_subject | The subject of the certificate used for client authentication. |
ssl_enabled | Whether TLS/SSL is enabled. |
ssl_server_cert_encoded | The certificate (PEM/base64 encoded). |
store_walk_objects | Tells the class whether or not to store returned objects. |
timeout | A timeout for the class. |
user | The user name used for SNMPv3 authentication. |
walk_limit | The limit of oid's returned in a walk. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
config | Sets or retrieves a configuration setting. |
discover | Performs SNMPv3 discovery. |
do_events | Processes events from the internal message queue. |
hash_passwords | Hashes all passwords in the cache. |
interrupt | Interrupt the current method. |
reset | Clears the object arrays. |
send_get_bulk_request | Send a GetBulkRequest packet. |
send_get_next_request | Send GetNextRequest packet. |
send_get_request | Send GetRequest packet. |
send_inform_request | Send an InformRequest packet. |
send_set_request | Send Set Request packet. |
value | Returns the value corresponding to an OID. |
walk | Does an SNMP walk starting with the specified oid. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
on_bad_packet | Fired for erroneous and/or malformed messages. |
on_connected | Fired immediately after a connection completes (or fails). |
on_connection_status | TBD. |
on_disconnected | TBD. |
on_discovery_request | Fired when an SNMPv3 discovery packet is received. |
on_discovery_response | Fired when an SNMPv3 discovery response is received. |
on_error | Information about errors during data delivery. |
on_hash_password | Fired before and after a password is hashed. |
on_inform_request | Fired when an InformRequest packet is received. |
on_packet_trace | Fired for every packet sent or received. |
on_ready_to_send | Fired when the class is ready to send data. |
on_report | Fired when a Report packet is received. |
on_response | Fired when a GetResponse packet is received. |
on_ssl_client_authentication | Fired when the client presents its credentials to the server. |
on_ssl_server_authentication | Fires when connecting to the server. |
on_ssl_status | Shows the progress of the secure connection. |
on_trap | Fired when a SNMP trap packet is received. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
CheckMessageOrigin | Whether to match the origin IP address when receiving responses. |
CompatibilityMode | Whether to operate the class in a specific compatibility mode. |
ContextEngineId | Sets the context engine id of the SNMP entity. |
ContextName | Sets the context name of the SNMP entity. |
DecryptLogPackets | Whether to decrypt logged packets. |
ForceLocalPort | Forces the class to bind to a specific port. |
MsgMaxSize | The maximum supported message size. |
SourceAddress | The source address of the received packet. |
SourcePort | The source port of the received packet. |
TimeoutInMilliseconds | The timeout is treated as milliseconds. |
WalkInsideRange | Stops the SNMP walk if the OID value returned from an agent is outside the table. |
WalkStartOID | Specifies the OID to be used when a Walk is performed. |
ConnectionTimeout | Sets a separate timeout value for establishing a connection. |
FirewallAutoDetect | Tells the class whether or not to automatically detect and use firewall system settings, if available. |
FirewallHost | Name or IP address of firewall (optional). |
FirewallPassword | Password to be used if authentication is to be used when connecting through the firewall. |
FirewallPort | The TCP port for the FirewallHost;. |
FirewallType | Determines the type of firewall to connect through. |
FirewallUser | A user name if authentication is to be used connecting through a firewall. |
KeepAliveInterval | The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received. |
KeepAliveTime | The inactivity time in milliseconds before a TCP keep-alive packet is sent. |
Linger | When set to True, connections are terminated gracefully. |
LingerTime | Time in seconds to have the connection linger. |
LocalHost | The name of the local host through which connections are initiated or accepted. |
LocalPort | The port in the local host where the class binds. |
MaxLineLength | The maximum amount of data to accumulate when no EOL is found. |
MaxTransferRate | The transfer rate limit in bytes per second. |
ProxyExceptionsList | A semicolon separated list of hosts and IPs to bypass when using a proxy. |
TCPKeepAlive | Determines whether or not the keep alive socket option is enabled. |
TcpNoDelay | Whether or not to delay when sending packets. |
UseIPv6 | Whether to use IPv6. |
LogSSLPackets | Controls whether SSL packets are logged when using the internal security API. |
OpenSSLCADir | The path to a directory containing CA certificates. |
OpenSSLCAFile | Name of the file containing the list of CA's trusted by your application. |
OpenSSLCipherList | A string that controls the ciphers to be used by SSL. |
OpenSSLPrngSeedData | The data to seed the pseudo random number generator (PRNG). |
ReuseSSLSession | Determines if the SSL session is reused. |
SSLCACertFilePaths | The paths to CA certificate files on Unix/Linux. |
SSLCACerts | A newline separated list of CA certificate to use during SSL client authentication. |
SSLCheckCRL | Whether to check the Certificate Revocation List for the server certificate. |
SSLCipherStrength | The minimum cipher strength used for bulk encryption. |
SSLEnabledCipherSuites | The cipher suite to be used in an SSL negotiation. |
SSLEnabledProtocols | Used to enable/disable the supported security protocols. |
SSLEnableRenegotiation | Whether the renegotiation_info SSL extension is supported. |
SSLIncludeCertChain | Whether the entire certificate chain is included in the SSLServerAuthentication event. |
SSLNegotiatedCipher | Returns the negotiated ciphersuite. |
SSLNegotiatedCipherStrength | Returns the negotiated ciphersuite strength. |
SSLNegotiatedCipherSuite | Returns the negotiated ciphersuite. |
SSLNegotiatedKeyExchange | Returns the negotiated key exchange algorithm. |
SSLNegotiatedKeyExchangeStrength | Returns the negotiated key exchange algorithm strength. |
SSLNegotiatedVersion | Returns the negotiated protocol version. |
SSLProvider | The name of the security provider to use. |
SSLSecurityFlags | Flags that control certificate verification. |
SSLServerCACerts | A newline separated list of CA certificate to use during SSL server certificate validation. |
TLS12SignatureAlgorithms | Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True. |
TLS12SupportedGroups | The supported groups for ECC. |
TLS13KeyShareGroups | The groups for which to pregenerate key shares. |
TLS13SignatureAlgorithms | The allowed certificate signature algorithms. |
TLS13SupportedGroups | The supported groups for (EC)DHE key exchange. |
AbsoluteTimeout | Determines whether timeouts are inactivity timeouts or absolute timeouts. |
FirewallData | Used to send extra data to the firewall. |
InBufferSize | The size in bytes of the incoming queue of the socket. |
OutBufferSize | The size in bytes of the outgoing queue of the socket. |
BuildInfo | Information about the product's build. |
CodePage | The system code page used for Unicode to Multibyte translations. |
LicenseInfo | Information about the current license. |
ProcessIdleEvents | Whether the class uses its internal event loop to process events when the main thread is idle. |
SelectWaitMillis | The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process. |
UseInternalSecurityAPI | Tells the class whether or not to use the system security libraries or an internal implementation. |