[Daemon] SNMP server

Introduction

The SNMP server implements industrial standard network management protocol - SNMP version 2 with mandatory community name, to offer telemetry data for remote monitoring.

Here are the supported OIDs (object identifiers):

OID	Type	Meaning
1.3.6.1.4.1.52535	(for illustration only)	IANA Private Enterprise Number for organisation name "hz.gl" owned by the author of laitos program.
1.3.6.1.4.1.52535.121	(for illustration only)	Supported OID nodes are directly underneath this OID. SNMP client may use this OID in a Walk (retrieve sub-tree) operation.
1.3.6.1.4.1.52535.121.100	octet string	Public IP address of laitos server
1.3.6.1.4.1.52535.121.101	integer	System clock - number of seconds since UNIX Epoch
1.3.6.1.4.1.52535.121.102	integer	Program up-time in number of seconds
1.3.6.1.4.1.52535.121.103	integer	Number of system CPU cores
1.3.6.1.4.1.52535.121.104	integer	Number of OS threads available to laitos (GOMAXPROCS)
1.3.6.1.4.1.52535.121.105	integer	Number of live goroutines
1.3.6.1.4.1.52535.121.110	integer	Total number of app commands executed
1.3.6.1.4.1.52535.121.111	integer	Total number of requests served by the web server
1.3.6.1.4.1.52535.121.112	integer	Total number of conversations served by the SMTP server
1.3.6.1.4.1.52535.121.114	integer	Total number of laitos supervisor password auto-unlock events
1.3.6.1.4.1.52535.121.115	integer	Total amount (bytes) of outstanding mail content to be delivered

Configuration

Construct the following JSON object and place it under key SNMPDaemon in configuration file:

Property	Type	Meaning	Default value
Address	string	The address network to listen on.	"0.0.0.0" - listen on all network interfaces.
Port	integer	UDP port number to listen on.	161 - the well-known port number designated for SNMP.
PerIPLimit	integer	Maximum number of requests a client (identified by IP) may make in a second.	33 - good enough for querying all supported OIDs 3 times a second
CommunityName	string	This passphrase must be presented by SNMP client in order for them to retrieve OID data. Be aware that the design of SNMP does not use encryption to protect this passphrase, it is transmitted in plain text.	(This is a mandatory property without a default value)

Here is a minimal setup example:

{
    ...

    "SNMPDaemon": {
        "CommunityName": "my-telemetry-secret-access"
    },

    ...
}

Run

Tell laitos to run SNMP daemon in the command line:

sudo ./laitos -config <CONFIG FILE> -daemons ...,snmpd,...

Usage

As an industrial standard, SNMP client is readily available on nearly all operating systems. For example, on Ubuntu Linux the client software can be installed by software package name snmp:

sudo apt install snmp

Subsequently, use these commands to interact with laitos SNMP server, substitute server-address with the server host name or IP:

# Retrieve all OIDs
> snmpwalk -v2c -c my-telemetry-secret-access server-address 1.3.6.1.4.1.52535.121
iso.3.6.1.4.1.52535.121.100 = STRING: "100.200.30.40"
iso.3.6.1.4.1.52535.121.101 = INTEGER: 1543480241
iso.3.6.1.4.1.52535.121.102 = INTEGER: 48680
iso.3.6.1.4.1.52535.121.103 = INTEGER: 4
iso.3.6.1.4.1.52535.121.104 = INTEGER: 8
iso.3.6.1.4.1.52535.121.105 = INTEGER: 58
iso.3.6.1.4.1.52535.121.110 = INTEGER: 0
iso.3.6.1.4.1.52535.121.111 = INTEGER: 627
iso.3.6.1.4.1.52535.121.112 = INTEGER: 5
iso.3.6.1.4.1.52535.121.114 = INTEGER: 0
iso.3.6.1.4.1.52535.121.115 = INTEGER: 0
iso.3.6.1.4.1.52535.121.115 = No more variables left in this MIB View (It is past the end of the MIB tree)

# Retrieve a single OID
> snmpget -v2c -c my-telemetry-secret-access server-address 1.3.6.1.4.1.52535.121.100
iso.3.6.1.4.1.52535.121.100 = STRING: "40.68.144.242"

Tips

By design, SNMP does not support encryption, therefore the requests, responses, and most importantly the passphrase will be transmitted in plain text. You must avoid re-using an important password in the passphrase configuration.