Network hardware over SNMP

Poll the network hardware in your comms cupboards over SNMP and put it on the network pane. Read only.


Category	Network
Authentication	SNMPv3 credentials, or a v2c community string
Reaches	Management addresses on your network
Needs an agent	Yes, on managed hosting
Demo mode	Yes, off by default

Capabilities

network.listSites, network.listDevices, network.getDevice

Which lights up the network page, gated by the module.network module.

This is the connector that makes “support whatever schools actually run” tractable. Cisco Catalyst, Aruba, HPE, Extreme, Ruckus, Fortinet, Netgear and most of what is in a comms cupboard speak SNMP, and the standard MIBs cover what a service desk needs without one line of vendor-specific code. One connector, most of the estate.

It reads identity from SNMPv2-MIB, port counts from IF-MIB, model and serial from ENTITY-MIB, and PoE draw from POWER-ETHERNET-MIB.

v3 is the default, and it should stay that way

An SNMP community string on a printer reads toner levels. The same string on a core switch reads the topology of your school’s network, and a write community reconfigures it.

So this connector defaults to v3 with authPriv, where the credentials are not sent in clear on the wire at all, and every credential-shaped field is held in the encrypted store rather than alongside the settings.

v2c is still available, because a great deal of school hardware speaks nothing else. It is labelled legacy so that choosing it is a decision rather than a default. If you must use it, do not reuse a string that any other class of device answers to.

Preparing the hardware

For each device, or across the estate through your management tool:

Enable SNMPv3 and create a read-only user with authPriv: an authentication passphrase and a privacy passphrase. Use SHA and AES unless the hardware cannot.
Where the hardware genuinely cannot do v3, enable v2c with a read-only community string, and use one that is not shared with anything else.
Confirm each management address is static, or reserved in DHCP. A switch that moves address disappears from the pane.
If your gear restricts SNMP by source address, allow the machine the connector runs from: the API host when self-hosted, or the agent host on managed hosting.

Configuring it in Plugboard

Admin, Connectors, Network hardware (SNMP), Configure.

Settings

Field	Default	Value
`hosts`	empty	Device IPs or hostnames, comma-separated
`siteName`	`SNMP devices`	What to call this group on the pane
`version`	`v3`	`v3` or `v2c`
`v3User`	empty	The SNMPv3 username
`v3AuthProtocol`	`sha`	`sha`, `sha256`, `sha512` or `md5`
`v3PrivProtocol`	`aes`	`aes`, `aes256b` or `des`
`port`	`161`	The SNMP port
`timeoutMs`	`3000`	How long to wait per device, 500–30000
`demoMode`	`false`	Return a sample estate, making no SNMP calls

demoMode defaults to off. Enable it explicitly to explore sample data; leave it off and configure real hosts for live polling.

Everything in one instance shares one siteName, which becomes a vendor network you map to a campus on the pane. A school wanting its senior and junior comms rooms as separate campuses maps the group once. The group is the unit here, not the device.

IP addresses are more reliable than hostnames and are what most schools use. Hostnames work if DNS resolves them from wherever the polling happens.

Secrets (encrypted)

Field	Value
`v3AuthKey`	The SNMPv3 authentication passphrase
`v3PrivKey`	The SNMPv3 privacy passphrase
`community`	The v2c community string. Legacy

All three are sealed in the encrypted secret store with your other connector credentials, never kept with the settings above.

On managed hosting these fields are not on the platform at all. Once the connector is assigned to a site, an agent on your network runs it and reads the credentials from its own AGENT_SECRETS file:

{ "snmp-network": { "v3AuthKey": "...", "v3PrivKey": "..." } }

The username, protocols and host list stay in the settings above, and travel to the agent with the job. Only the passphrases live in the agent’s own file.

Plugboard refuses to hold an agent-run connector’s credentials on the platform, which is the point of the agent: it dials out, is never dialled into, and holds its own secrets.

The private network question

Switch management VLANs are on your LAN, always.

Self-hosted on that network: reaches them directly. You will also want ALLOW_PRIVATE_EGRESS=1, because Plugboard blocks outbound requests to private address ranges by default.

Managed hosting: needs a connector agent on a machine that can reach the management VLAN. There is no configuration that makes a hosted deployment reach a comms cupboard directly, and nobody should be told to try.

What you get

For each device:


Name	Its `sysName`, falling back to the address you configured
Kind	Switch, gateway, access point or firewall, from the model or description
Model and serial	From ENTITY-MIB, where the device populates it
Firmware	From the system description
MAC and IP
Ports	Fitted against up
PoE draw	In watts, where the device reports it
Uptime
Status	Up, down or unknown

A device that does not answer is down; a device that answers but does not populate a field leaves that field empty rather than guessing.

What it cannot do

Write anything. Read only. No write community is used, asked for, or supported.
Report clients. There is no network.listClients here, so the “where was this laptop last seen” question is not answered from SNMP. A switch can be asked which MAC is on which port, but it is a large walk with real per-vendor variation, and a connector that declares the capability and returns a partly-wrong answer is worse than one that says it cannot. Use Meraki or a local UniFi console for that.
Report WAN uplink loss or latency. Those come from a gateway vendor’s own API, not from a generic SNMP walk.
Discover devices. You give it a list of addresses; it does not scan.
Split one instance across campuses. One siteName per instance, and one instance per school.

Troubleshooting

Symptom	Cause
A sample estate appears	`demoMode` is still on
No response from one device	SNMP not enabled on it, wrong version, or the wrong credentials
Some devices work, others do not	Mixed credentials across the estate. One instance uses one set for every host
Everything times out, self-hosted	`ALLOW_PRIVATE_EGRESS` is not set
Everything times out, managed hosting	No agent, or the agent’s host cannot reach the management VLAN
Timeouts on a slow or distant device	Raise `timeoutMs`
A device answers but has no model or serial	It does not populate ENTITY-MIB. Common on cheaper hardware
Everything reads as “other”	The model and description do not name a kind we recognise
A device vanished	Its management address changed. Use a reservation
v3 fails with no useful message	Check the auth and privacy protocols match the device exactly. A mismatch fails identically to a wrong passphrase

Printers over SNMP is the same protocol for a different job, and a separate connector: toner levels rather than topology. Run both if you have both, and do not give them the same community string. A read-only string on a printer reads consumables, and the same string on a switch reads your network.

Meraki and UniFi fill the same pane and are merged with this one rather than competing with it. All the network connectors share one connector slot.