Enable SNMP Support¶

SNMP support must be enabled and configured before you can begin using it to monitor StarlingX.

About this task

In order to enable and configure SNMP, complete the following steps.

Procedure

On the active controller, acquire Keystone administrative privileges.
```
$ source /etc/platform/openrc
~(keystone_admin)]$
```

Use the following command to list the system applications and check whether SNMP is uploaded or applied. If SNMP is already “uploaded”, go to Step 5 to configure and enable SNMP. If SNMP is already “applied”, SNMP is already configured and enabled, see Change Configuration of the SNMP application to make configuration changes.

~(keystone)admin)$ system application-list
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+
| application              | version   | manifest name                             | manifest file    | status   | progress  |
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+
| cert-manager             | 24.09-79  | cert-manager-fluxcd-manifests             | fluxcd-manifests | applied  | completed |
| dell-storage             | 24.09-25  | dell-storage-fluxcd-manifests             | fluxcd-manifests | uploaded | completed |
| nginx-ingress-controller | 24.09-64  | nginx-ingress-controller-fluxcd-manifests | fluxcd-manifests | applied  | completed |
| oidc-auth-apps           | 24.09-59  | oidc-auth-apps-fluxcd-manifests           | fluxcd-manifests | uploaded | completed |
| platform-integ-apps      | 24.09-141 | platform-integ-apps-fluxcd-manifests      | fluxcd-manifests | applied  | completed |
| rook-ceph                | 24.09-48  | rook-ceph-fluxcd-manifests                | fluxcd-manifests | uploaded | completed |
| snmp                     | 24.09-89  | snmp-fluxcd-manifests                     | fluxcd-manifests | applied  | completed |
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+

In order to load the SNMP application definitions (FluxCD manifest and Helm charts), where [snmp-<Major>.<Minor>-<Build>.tgz], for example, snmp-1.0-2.tgz is the app filename with version 1.0-2 available at the following path /usr/local/share/applications/helm use the following command.

~(keystone)admin)$ system application-upload <path>/snmp-1.0-36.tgz
+---------------+----------------------------------+
| Property      | Value                            |
+---------------+----------------------------------+
| active        | False                            |
| app_version   | 1.0-36                           |
| created_at    | 2022-06-27T10:45:42.733267+00:00 |
| manifest_file | fluxcd-manifests                 |
| manifest_name | snmp-fluxcd-manifests            |
| name          | snmp                             |
| progress      | None                             |
| status        | uploading                        |
| updated_at    | None                             |
+---------------+----------------------------------+

List the SNMP application using the following command to see the status of the upload and wait for the upload to complete.

~(keystone)admin)$ system application-list
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+
| application              | version   | manifest name                             | manifest file    | status   | progress  |
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+
| cert-manager             | 24.09-79  | cert-manager-fluxcd-manifests             | fluxcd-manifests | applied  | completed |
| dell-storage             | 24.09-25  | dell-storage-fluxcd-manifests             | fluxcd-manifests | uploaded | completed |
| nginx-ingress-controller | 24.09-64  | nginx-ingress-controller-fluxcd-manifests | fluxcd-manifests | applied  | completed |
| oidc-auth-apps           | 24.09-59  | oidc-auth-apps-fluxcd-manifests           | fluxcd-manifests | uploaded | completed |
| platform-integ-apps      | 24.09-141 | platform-integ-apps-fluxcd-manifests      | fluxcd-manifests | applied  | completed |
| rook-ceph                | 24.09-48  | rook-ceph-fluxcd-manifests                | fluxcd-manifests | uploaded | completed |
| snmp                     | 24.09-89  | snmp-fluxcd-manifests                     | fluxcd-manifests | applied  | completed |
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+

Create a Helm chart values file (for example, user_conf.yaml) with the definition of the configmap:user_conf attribute, defining your SNMP configuration of V2 communities, V2 trap sinks, V3 users and/or V3 trap sessions, as shown in the example below. The configmap:user_conf variable in the SNMP Helm chart is a multi-line variable that follows the syntax of Net-SNMP’s snmpd.conf file for configuring the SNMP agent, see http://www.net-snmp.org/docs/man/snmpd.conf.html, for detailed description of the commands.

Warning

Since this file may contain sensitive security information, this file should be removed from the system after executing the command and stored off-box, or regenerated, if required.
```
cat <<EOF > user_conf.yaml
configmap:
  user_conf: |-
    # Configure V2 Community
    # rocommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
    rocommunity testcommunity  default    -V all

    # Configure V2 Trap Sink / Destination
    # trap2sink HOST [COMMUNITY [PORT]]
    trap2sink 10.10.10.1:162 testcommunity

    # Configure V3 User
    # createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES] [privpassphrase]
    createUser testuser MD5 testpassword DES

    # Configure RW access for V3 User
    # rouser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
    rouser testuser priv

    # Configure V3 Trap Session / Destination
    # trapsess -v 3 -u USER -a [MD5|SHA] -A authpassphrase -l [noauth|auth|priv] -x [DES|AES] -X privpassphrase [<transport-specifier>:]<transport-address>
    trapsess -v 3 -u testuser -a MD5 -A testpassword -l authPriv -x DES -X testpassword udp:10.10.10.1:162
EOF
```
(Optional) You can add your own EngineID value, instead of having it auto-created. This keeps the EngineID value the same, even when the SNMP application restarts. The EngineID is required if you are using an SNMP trap viewer or SNMP monitoring tool. Add the engineID [STRING] value in the configmap:user_conf variable, as shown below.
```
cat <<EOF > user_conf.yaml
configmap:
  user_conf: |-
...
    engineID [STRING]
...
EOF
```
Note

The EngineID value consists of a string of 10-64 characters in hexadecimal numbers. In case you need to specify the whole string (i.e., Net-SNMP will not add characters), you can use the exactEngineID value instead. Add the exactEngineID 0X[STRING] value in the configmap:user_conf variable, as shown below.
```
cat <<EOF > user_conf.yaml
configmap:
  user_conf: |-
...
    exactEngineID 0X[STRING]
...
EOF
```

Update the values of the configmap:user_conf attribute on the Helm chart using the following command.

~(keystone_admin)$ system helm-override-update --reuse-values --values user_conf.yaml snmp snmp kube-system
+----------------+------------------------------------------------------------------------------------------------------------+
| Property       | Value                                                                                                      |
+----------------+------------------------------------------------------------------------------------------------------------+
| name           | snmp                                                                                                       |
| namespace      | kube-system                                                                                                |
| user_overrides | configmap:                                                                                                 |
|                |   user_conf: |-                                                                                            |
|                |     createUser testuser MD5 testpassword DES                                                               |
|                |     rouser testuser priv                                                                                   |
|                |     rocommunity testcommunity  default    -V all                                                           |
|                |     trapsess -v 3 -u testuser -a MD5 -A testpassword -l authPriv -x DES -X testpassword udp:10.10.10.1:162 |
|                |     trap2sink 10.10.10.1:162 testcommunity                                                                 |
+----------------+------------------------------------------------------------------------------------------------------------+

Run the following command to apply the changes and start the SNMP application.

~(keystone)admin)$ system application-apply snmp
+---------------+----------------------------------+
| Property      | Value                            |
+---------------+----------------------------------+
| active        | False                            |
| app_version   | 24.09-89                         |
| created_at    | 2022-06-27T10:45:42.733267+00:00 |
| manifest_file | fluxcd-manifests                 |
| manifest_name | snmp-fluxcd-manifests            |
| name          | snmp                             |
| progress      | None                             |
| status        | applying                         |
| updated_at    | 2022-06-27T10:45:51.253949+00:00 |
+---------------+----------------------------------+

List the SNMP application and check the status. Wait for the SNMP application to have fully started and is in the “applied” state.

~(keystone)admin)$ system application-list
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+
| application              | version   | manifest name                             | manifest file    | status   | progress  |
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+
| cert-manager             | 24.09-79  | cert-manager-fluxcd-manifests             | fluxcd-manifests | applied  | completed |
| dell-storage             | 24.09-25  | dell-storage-fluxcd-manifests             | fluxcd-manifests | uploaded | completed |
| nginx-ingress-controller | 24.09-64  | nginx-ingress-controller-fluxcd-manifests | fluxcd-manifests | applied  | completed |
| oidc-auth-apps           | 24.09-59  | oidc-auth-apps-fluxcd-manifests           | fluxcd-manifests | uploaded | completed |
| platform-integ-apps      | 24.09-141 | platform-integ-apps-fluxcd-manifests      | fluxcd-manifests | applied  | completed |
| rook-ceph                | 24.09-48  | rook-ceph-fluxcd-manifests                | fluxcd-manifests | uploaded | completed |
| snmp                     | 24.09-89  | snmp-fluxcd-manifests                     | fluxcd-manifests | applied  | completed |
+--------------------------+-----------+-------------------------------------------+------------------+----------+-----------+

Create a Helm chart values file (for example, snmp_port.yaml) with UDP and TCP port mapping rules, for the nginx-ingress-controller application, to expose the SNMP services on the required ports. Use external ports 161/UDP and 162/TCP.

kube-system/snmpd-service:161 is the standard SNMP Agent’s UDP port for receiving SNMP requests. It should be configured as mapped to external UDP port 161, the default for SNMP Agents. This port can be modified, see, Modifying 161/UDP port procedure for details on modifying this port.

kube-system/snmpd-service:162 is used internally by the SNMP application to receive trap info from StarlingX. It should be configured as mapped to external TCP port 162. This port can be modified, see Modifying 162/TCP port procedure below for details on modifying this port.
```
cat <<EOF > snmp_port.yaml
udp:
  161: "kube-system/snmpd-service:161"
tcp:
  162: "kube-system/snmpd-service:162"
EOF
```

Update the values of the SNMP port mappings in the Helm Chart for the nginx-ingress-controller application.

~(keystone_admin)$ system helm-override-update --reuse-values --values snmp_port.yaml nginx-ingress-controller ks-ingress-nginx kube-system
+----------------+------------------------------------------+
| Property       | Value                                    |
+----------------+------------------------------------------+
| name           | ks-ingress-nginx                         |
| namespace      | kube-system                              |
| user_overrides | tcp:                                     |
|                |   "162": kube-system/snmpd-service:162   |
|                | udp:                                     |
|                |   "161": kube-system/snmpd-service:161   |
|                |                                          |
+----------------+------------------------------------------+

Apply the changes to the nginx-ingress-controller application.

~(keystone_admin)$ system application-apply nginx-ingress-controller
+---------------+--------------------------------------+
| Property      | Value                                |
+---------------+--------------------------------------+
| active        | True                                 |
| app_version   | 24.09-64                             |
| created_at    | 2022-06-26T21:21:47.428225+00:00     |
| manifest_file | fluxcd-manifests                     |
| manifest_name | platform-integ-apps-fluxcd-manifests |
| name          | platform-integ-apps                  |
| progress      | none                                 |
| status        | applying                             |
| updated_at    | 2022-06-26T21:30:06.767995+00:00     |
+---------------+--------------------------------------+

Redirect the SNMP UDP traffic to port 161 by creating the next policies.yml file and apply it as below.

Change the ipVersion parameter value from 4 to 6 if you are using IPV6.

~(keystone_admin)$
cat <<EOF > policies.yml
apiVersion: crd.projectcalico.org/v1
kind: GlobalNetworkPolicy
metadata:
  name: snmp
spec:
  applyOnForward: false
  ingress:
  - action: Allow
    destination:
      ports:
      - 161
    ipVersion: 4
    protocol: UDP
  order: 200
  selector: has(iftype) && iftype == 'oam'
  types:
  - Ingress
EOF

Then, run the following command:

~(keystone_admin)$ kubectl apply -f policies.yml

Change configuration of the SNMP application ¶

If the SNMP application is already applied, use the following procedures to update its configuration.

Procedure

Create a Helm chart values file (for example, user_conf.yaml) with the definition of the configmap:user_conf attribute defining your SNMP configuration of V2 communities, V2 trap sinks, V3 users and/or V3 trap sessions, as shown in the example below. The configmap:user_conf variable in the SNMP Helm chart is a multi-line variable that follows the syntax of Net-SNMP’s snmpd.conf file for configuring the SNMP agent, see http://www.net-snmp.org/docs/man/snmpd.conf.html, for a detailed description of the commands.

Warning

Since this file may contain sensitive security information, this file should be removed from the system after executing the command and stored off-box, or regenerated, if required.
```
cat <<EOF > user_conf.yaml
configmap:
  user_conf: |-
    # Configure V2 Community
    # rocommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
    rocommunity testcommunity  default    -V all

    # Configure V2 Trap Sink / Destination
    # trap2sink HOST [COMMUNITY [PORT]]
    trap2sink 10.10.10.1:162 testcommunity

    # Configure V3 User
    # createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES] [privpassphrase]
    createUser testuser MD5 testpassword DES

    # Configure RW access for V3 User
    # rouser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
    rouser testuser priv

    # Configure V3 Trap Session / Destination
    # trapsess -v 3 -u USER -a [MD5|SHA] -A authpassphrase -l [noauth|auth|priv] -x [DES|AES] -X privpassphrase [<transport-specifier>:]<transport-address>
    trapsess -v 3 -u testuser -a MD5 -A testpassword -l authPriv -x DES -X testpassword udp:10.10.10.1:162
EOF
```
(Optional) You can add your own EngineID value, instead of having it auto-created. This keeps the EngineID value the same, even when the SNMP application restarts. The EngineID is required if you are using an SNMP trap viewer or SNMP monitoring tool. Add the engineID [STRING] value in the configmap:user_conf variable, as shown below.
```
cat <<EOF > user_conf.yaml
configmap:
  user_conf: |-
...
    engineID [STRING]
...
EOF
```
Note

The EngineID value consists of a string of 10-64 characters in hexadecimal numbers. In this case you need to specify the whole string (i.e., Net-SNMP will not add characters), you can use the exactEngineID value instead. Add the exactEngineID 0X[STRING] value in the configmap:user_conf variable, as shown below.
```
cat <<EOF > user_conf.yaml
configmap:
  user_conf: |-
...
    exactEngineID 0X[STRING]
...
EOF
```

Update the values of the configmap:user_conf attribute on the Helm chart using the following command.

~(keystone_admin)$ system helm-override-update --reuse-values --values user_conf.yaml snmp snmp kube-system
+----------------+------------------------------------------------------------------------------------------------------------+
| Property       | Value                                                                                                      |
+----------------+------------------------------------------------------------------------------------------------------------+
| name           | snmp                                                                                                       |
| namespace      | kube-system                                                                                                |
| user_overrides | configmap:                                                                                                 |
|                |   user_conf: |-                                                                                            |
|                |     createUser testuser MD5 testpassword DES                                                               |
|                |     rouser testuser priv                                                                                   |
|                |     rocommunity testcommunity  default    -V all                                                           |
|                |     trapsess -v 3 -u testuser -a MD5 -A testpassword -l authPriv -x DES -X testpassword udp:10.10.10.1:162 |
|                |     trap2sink 10.10.10.1:162 testcommunity                                                                 |
+----------------+------------------------------------------------------------------------------------------------------------+

Apply the changes.

~(keystone_admin)$ system application-apply snmp
+---------------+----------------------------------+
| Property      | Value                            |
+---------------+----------------------------------+
| active        | False                            |
| app_version   | 24.09-89                         |
| created_at    | 2024-06-27T10:45:42.733267+00:00 |
| manifest_file | fluxcd-manifests                 |
| manifest_name | snmp-fluxcd-manifests            |
| name          | snmp                             |
| progress      | None                             |
| status        | applying                         |
| updated_at    | 2024-06-27T10:45:51.253949+00:00 |
+---------------+----------------------------------+

Modifying 161/UDP port ¶

Modify the external UDP port used for receiving SNMP requests.

Note

After changing this external UDP port, any external SNMP managers being used must be updated to send their SNMP requests to StarlingX using this UDP port, instead of the default UDP port 161.

Procedure

Create a Helm chart values file (for example, snmp_port.yaml) with external ports 161/UDP and 162/TCP port mapping definitions, for the SNMP services for the nginx-ingress-controller’s Helm chart, as shown in the example below.

Update the external port in the UDP port mapping for internal port kube-system/snmpd-service:161. The example below shows the external port updated to 1061.
```
cat <<EOF > snmp_port.yaml
udp:
  1061: "kube-system/snmpd-service:161"
tcp:
  162: "kube-system/snmpd-service:162"
EOF
```

Update the values of the SNMP ports on the Helm chart for the nginx-ingress-controller application.

~(keystone_admin)$ system helm-override-update --reuse-values --values snmp_port.yaml nginx-ingress-controller ks-ingress-nginx kube-system
+----------------+------------------------------------------+
| Property       | Value                                    |
+----------------+------------------------------------------+
| name           | ks-ingress-nginx                         |
| namespace      | kube-system                              |
| user_overrides | tcp:                                     |
|                |   "162": kube-system/snmpd-service:162   |
|                | udp:                                     |
|                |   "1061": kube-system/snmpd-service:161  |
|                |                                          |
+----------------+------------------------------------------+

Apply the changes in the nginx-ingress-controller application.

~(keystone_admin)$ system application-apply nginx-ingress-controller
+---------------+-------------------------------------------+
| Property      | Value                                     |
+---------------+-------------------------------------------+
| active        | True                                      |
| app_version   | 24.09-64                                  |
| created_at    | 2022-06-26T20:49:02.437688+00:00          |
| manifest_file | fluxcd-manifests                          |
| manifest_name | nginx-ingress-controller-fluxcd-manifests |
| name          | nginx-ingress-controller                  |
| progress      | None                                      |
| status        | applying                                  |
| updated_at    | 2022-06-26T20:50:10.730709+00:00          |
+---------------+-------------------------------------------+

Modifying 162/TCP port ¶

Modify the external port used by the SNMP application to receive trap information from StarlingX.

To change the port 162/TCP, you need to modify both the SNMP application Helm chart, and the nginx-ingress-controller Helm chart. The new port must be set to the same port number in the two Helm charts, otherwise SNMP traps will not be generated.

Procedure

Modify your SNMP Helm chart values file (for example, user_conf.yaml) by adding the line “trap-server-port: [new port]” as shown in the example below (“30162” is the new port in this example).

cat <<EOF > user_conf.yaml
configmap:
  user_conf: |-
    createUser testuser MD5 testpassword DES
    rouser testuser priv
    rocommunity testcommunity  default    -V all
    trapsess -v 3 -u testuser -a MD5 -A testpassword -l authPriv -x DES -X testpassword udp:10.10.10.1:162
    trap2sink 10.10.10.1:162 testcommunity
  trap-server-port: 30162
EOF

Run the following commands to apply the configuration.

~(keystone_admin)$ system helm-override-update --reuse-values --values user_conf.yaml snmp snmp kube-system
~(keystone_admin)$ system application-apply snmp

Modify your nginx ingress controller Helm chart values file (for example, snmp_port.yaml). Update the external port in the TCP port mapping for internal port kube-system/snmpd-service:162. The example below shows the external port updated to 30162.
- The new port number must match the port number specified in your SNMP Helm chart values file (for example, user_conf.yaml).
- Do not modify port number “162” in kube-system/snmpd-service:162.
```
cat <<EOF > snmp_port.yaml
udp:
  161: "kube-system/snmpd-service:161"
tcp:
  30162: "kube-system/snmpd-service:162"
EOF
```

Run the following commands to apply the configuration.

~(keystone_admin)$ system helm-override-update --reuse-values --values snmp_port.yaml nginx-ingress-controller ks-ingress-nginx kube-system
~(keystone_admin)$ system application-apply nginx-ingress-controller