Skip to content

SNMPv3 configuration

SNMPv3 only

This page is only relevant if you are using SNMPv3 authentication. If your devices use SNMPv2c or SNMPv1, you can skip this page entirely.

Configuration of SNMPv3, when supported by the monitored devices, is the most secure choice available for authentication and data privacy. We recommend using SNMPv3 whenever possible.

Supported authentication and privacy protocols

authProtocol supports the following values:

  • MD5 — HMAC-MD5-96.
  • SHA — HMAC-SHA-96 (SHA-1).
  • SHA224 — HMAC-SHA-224.
  • SHA256 — HMAC-SHA-256.
  • SHA384 — HMAC-SHA-384.
  • SHA512 — HMAC-SHA-512.

privProtocol supports the following values:

  • DES
  • 3DES
  • AES / AES128 — 128-bit AES. AES and AES128 are equivalent.
  • AES192 — 192-bit AES.
  • AES192BLMT — 192-bit AES, Blumenthal variant.
  • AES256 — 256-bit AES.
  • AES256BLMT — 256-bit AES, Blumenthal variant.

Values are case-insensitive. If authProtocol/privProtocol is left unset or does not match one of the values above, SC4SNMP falls back to no authentication / no privacy. MD5 and DES are considered cryptographically weak; prefer other protocols where the device supports them.

Each set of credentials is stored as a Kubernetes Secret object and referenced by name in values.yaml. This allows the secret to be created once - including automation by third-party password managers - then consumed without storing sensitive data in plain text.

# <secretname>=Arbitrary name of the secret often the same as the username or prefixed with "sc4snmp-"
# <namespace>=Namespace used to install sc4snmp
# <username>=the SNMPv3 Username
# <key>=key note must be at least 8 char long subject to target limitations
# <authProtocol>=One of MD5, SHA, SHA224, SHA256, SHA384, SHA512
# <privProtocol>=One of DES, 3DES, AES (=AES128), AES128, AES192, AES192BLMT, AES256, AES256BLMT
# Note MD5 and DES are considered insecure but are supported for standards compliance
microk8s kubectl create -n <namespace> secret generic <secretname> \
  --from-literal=userName=<username> \
  --from-literal=authKey=<key> \
  --from-literal=privKey=<key> \
  --from-literal=authProtocol=<authProtocol> \
  --from-literal=privProtocol=<privProtocol>

Configured credentials can be used in poller and trap services. In service configuration, secretname needs to be provided.

For poller: 

poller:
  usernameSecrets:
    - secret_name

For traps: 

traps:
  usernameSecrets:
    - secret_name

All SNMPv3 secrets are managed through a single secrets.json file stored in a folder on the host.

Prerequisites

Create a folder to store the secrets file. Inside this folder, create a secrets.json file that contains all SNMPv3 secrets.

{
  "secret_name": {
    "username": "user1",
    "privprotocol": "AES",
    "privkey": "privkey1",
    "authprotocol": "SHA",
    "authkey": "authkey1",
    "contextengineid": "engineid1"
  }
}

Note

The name of json file should be secrets.json. Username, authprotocol and authkey are mandatory parameters.

Configuration

In the .env file, set the path to the local folder containing the secrets.json:

SECRET_FOLDER_PATH=/absolute/path/to/secrets/folder

Secrets usage for worker-poller and worker-trap can be controlled by flags in .env:

ENABLE_TRAPS_SECRETS=true
ENABLE_WORKER_POLLER_SECRETS=true

Creating a new secret

Add an entry to secrets.json, then inside the docker_compose directory run:

sudo docker compose up -d

Updating existing secret

Update the required fields (e.g., keys, protocols, username) for any existing secret inside secrets.json, then run:

docker compose up -d --force-recreate <service_name>

Deleting a secret

Delete its entry from secrets.json, then run:

docker compose up -d --force-recreate <service_name>

Migration steps

Managing SNMPv3 secrets previously required updating docker compose files using the manage_secrets.py script. From SC4SNMP 1.15.0, this process has been simplified and can manage all SNMPv3 secrets using a single secrets.json file.

1. For setups not yet migrated to latest version

First, delete all existing secrets from docker-compose.yaml using manage_secrets.py with the following flags:

Flag Description
--secret_name Secret name
--path_to_compose Absolute path to directory with docker compose files
--delete Set this flag to true to delete the secret

This will delete the secret with a given name from all docker compose files. If this secret hasn’t been deleted from .env file, it will be removed from there.

2. For setups already migrated to latest version

Manually delete the secrets from the docker-compose.yaml file under the worker-poller and worker-trap services. Remove the corresponding entries from the .env file.

After deleting the secrets, follow the above steps to configure secrets.