SNMP Support in Avi Vantage

Overview

Avi Vantage supports SNMPv2c and SNMPv3. SNMPv3 enables user authentication with the server and payload encryption for the messages exchanged with the Avi Controller.

The MIB file, AVI-NETWORKS-MIB.my, is the same for both SNMPv2c and SNMPv3 implementations, and is available for download at: https://github.com/avinetworks/sdk/tree/master/mibs. It contains a description of the Avi Vantage SNMP configuration objects and notifications. Alternate download locations for MIBs are listed at the end of this article.

This article shows the MIB definitions for the Avi Vantage objects and the definitions for the notifications (traps). An example of how to configure a custom alert based on an SNMP notification also is provided.

Note: Starting with Avi Vantage release 20.1.1, SNMPv3 and the authentication type - SHA256 are supported.

Responding to SNMP Queries

To fetch SNMP objects from Avi Vantage, an external host needs to query the SNMP daemon, which runs only on the Controller cluster leader. It is therefore best to configure the external host to direct queries to the cluster IP of the Avi Controller cluster. If cluster IP is unavailable, the external host must know the IP addresses of each Controller, and the host can try for three times before it finds the current leader’s SNMP daemon.

Firewall rules should be configured to give that external host access to port 161 on the cluster IP or each of the Controller IPs.

During a brief period of time, say 1 to 4 minutes, while a Controller cluster is recovering from the failure of its leader, queries to the cluster IP will fail, which the external host may interpret as “Avi Vantage is down”. However, the data plane, i.e., the SEs would be up and delivering virtual services to clients.

Configuring SNMP Polling

To configure the community string for SNMP polling, log into the UI and navigate to Administration > Settings > Access Settings.

SNMPPolling

Click on the edit icon. Specify the relevant community string in SNMP Community in SNMP Settings section.

SNMPCommunity

Configuring SNMP System

You can configure the common system parameters, for instance, sysName, sysLocation and sysContact in the Avi Vantage Platform. In a Controller cluster, sysName is configured for each Controller node as the node name in the Cluster object. sysLocation and sysContact are specified in SystemConfiguration object. Because the SNMP configuration is specified at the System Configuration object level, it applies to all clouds overseen by the Controller cluster.

API to Configure SNMP System Parameters

Note: In the three REST API examples that follow, for sake of brevity, the portions of the PUT that apply to aspects of the system other than SNMP is excluded. Their absence is indicated by a series of three vertical dots.

API SNMPv2 Configuration

Note: For backward compatibility, omission of the version parameter causes Avi Vantage to default to “SNMP_VER2”.

PUT api/systemconfiguration
{
    .
    .
    .
    "snmp_configuration": {
        "version": "SNMP_VER2", "sys_contact": "jdoe@acme.com",
        "community": "public", "sys_location": "San Jose, CA"
    },

    .
    .
    .
}

}

API SNMPv3 Configuration

Note: If other than SNMPv2 is desired, the version parameter must be explicitly included. It is explicitly set to “SNMP_VER3” in the below example.

As of SNMPv3,

  • The possible values for auth_type are “SNMP_V3_AUTH_MD5” and “SNMP_V3_AUTH_SHA”.
  • The possible values for priv_type are “SNMP_V3_PRIV_AES” and “SNMP_V3_PRIV_DES”.
  • As per the SNMP RFC5343, the snmpEngineID value must be between 5 and 32 octets long. It is recommended to use decimal format to configure Engine ID.

The “snmpv3user” and “0x8000000001020304” values are merely representative of what would appear for the username and engine_id parameters.

PUT api/systemconfiguration
{
    .
    .
    .
    "snmp_configuration": {
            "version": "SNMP_VER3", "sys_contact": "jdoe@acme.com",
            "snmp_v3_config": {
            "user":
            { "username": "snmpv3user", "auth_type": "SNMP_V3_AUTH_MD5",
             "priv_passphrase": "<sensitive>", "auth_passphrase": "<sensitive>",
              "priv_type": "SNMP_V3_PRIV_AES" },
              "engine_id": "0x8000000001020304"
              }
        },

    .
    .
    .
}

}

CLI Views of SNMP System Parameters

version = SNMP_VER2

[admin:10-10-24-96]: > show systemconfiguration
+----------------------------------+----------------------------------+
| Field                            | Value                            |
+----------------------------------+----------------------------------+
| uuid                             | default                          |
| dns_configuration                |                                  |
|   search_domain                  |                                  |
| ntp_configuration                |                                  |
|   ntp_servers[1]                 |                                  |
|     server                       | 0.us.pool.ntp.org                |
|   ntp_servers[2]                 |                                  |
|     server                       | 1.us.pool.ntp.org                |
|   ntp_servers[3]                 |                                  |
|     server                       | 2.us.pool.ntp.org                |
|   ntp_servers[4]                 |                                  |
|     server                       | 3.us.pool.ntp.org                |
| portal_configuration             |                                  |
|   enable_https                   | True                             |
|   redirect_to_https              | True                             |
|   enable_http                    | True                             |
|   sslkeyandcertificate_refs[1]   | System-Default-Portal-Cert       |
|   sslkeyandcertificate_refs[2]   | System-Default-Portal-Cert-EC256 |
|   use_uuid_from_input            | False                            |
|   sslprofile_ref                 | System-Standard                  |
|   enable_clickjacking_protection | True                             |
|   allow_basic_authentication     | True                             |
|   password_strength_check        | False                            |
|   disable_remote_cli_shell       | False                            |
| global_tenant_config             |                                  |
|   tenant_vrf                     | False                            |
|   se_in_provider_context         | True                             |
|   tenant_access_to_provider_se   | True                             |
| email_configuration              |                                  |
|   smtp_type                      | SMTP_LOCAL_HOST                  |
|   from_email                     | admin@avicontroller.net          |
|   mail_server_name               | localhost                        |
|   mail_server_port               | 25                               |
| docker_mode                      | False                            |
| snmp_configuration               |                                  |
|   community                      | <sensitive>                      |
|   sys_location                   | San Jose, CA                     |
|   sys_contact                    | jdoe@acme.com                    |
|   version                        | SNMP_VER2                        |
+----------------------------------+----------------------------------+
[admin:10-10-24-96]: >

version = SNMP_VER3

[admin:10-10-24-96]: > show systemconfiguration
+----------------------------------+----------------------------------+
| Field                            | Value                            |
+----------------------------------+----------------------------------+
| uuid                             | default                          |
| dns_configuration                |                                  |
|   search_domain                  |                                  |
| ntp_configuration                |                                  |
|   ntp_servers[1]                 |                                  |
|     server                       | 0.us.pool.ntp.org                |
|   ntp_servers[2]                 |                                  |
|     server                       | 1.us.pool.ntp.org                |
|   ntp_servers[3]                 |                                  |
|     server                       | 2.us.pool.ntp.org                |
|   ntp_servers[4]                 |                                  |
|     server                       | 3.us.pool.ntp.org                |
| portal_configuration             |                                  |
|   enable_https                   | True                             |
|   redirect_to_https              | True                             |
|   enable_http                    | True                             |
|   sslkeyandcertificate_refs[1]   | System-Default-Portal-Cert       |
|   sslkeyandcertificate_refs[2]   | System-Default-Portal-Cert-EC256 |
|   use_uuid_from_input            | False                            |
|   sslprofile_ref                 | System-Standard                  |
|   enable_clickjacking_protection | True                             |
|   allow_basic_authentication     | True                             |
|   password_strength_check        | False                            |
|   disable_remote_cli_shell       | False                            |
| global_tenant_config             |                                  |
|   tenant_vrf                     | False                            |
|   se_in_provider_context         | True                             |
|   tenant_access_to_provider_se   | True                             |
| email_configuration              |                                  |
|   smtp_type                      | SMTP_LOCAL_HOST                  |
|   from_email                     | admin@avicontroller.net          |
|   mail_server_name               | localhost                        |
|   mail_server_port               | 25                               |
| docker_mode                      | False                            |
| snmp_configuration               |                                  |
|   sys_location                   | San Jose, CA                     |
|   sys_contact                    | jdoe@acme.com                    |
|   version                        | SNMP_VER3                        |
|   snmp_v3_config                 |                                  |
|     user                         |                                  |
|       username                   | snmpv3user                       |
|       auth_type                  | SNMP_V3_AUTH_SHA                 |
|       auth_passphrase            | <sensitive>                      |
|       priv_type                  | SNMP_V3_PRIV_AES                 |
|       priv_passphrase            | <sensitive>                      |
|     engine_id                    | 0x123456789ABCDEF                |
+----------------------------------+----------------------------------+
[admin:10-10-24-96]: >

Avi UI SNMP Configuration

For SNMPv2:

SNMPv2SystemConfig.jpg

For SNMPv3:

SNMPv3SystemConfig.jpg

MIB Objects for Avi Vantage

The following are the Avi Vantage configuration objects exposed through the AVI-NETWORKS-MIB.my:

Avi Controller

AviControllerEntry ::=
   	SEQUENCE {
     	aviControllerIndex      Integer32,
       	aviControllerUUID       SnmpAdminString,
       	aviControllerName       DisplayString,
       	aviControllerAddrType   InetAddressType,
      	aviControllerAddr       InetAddress,
       	aviControllerStatus     INTEGER
	}
aviControllerUUID 	    : Unique UUID of the Avi Controller VM
aviControllerName 	    : Name assigned to the Avi Controller (defaults
                          to the IP address of the Avi Controller)
aviControllerAddr 	    : Management v4 IP address of the Avi
                          Controller
aviControllerStatus 	: Runtime status of the Avi Controller

Service Engine

AviServiceEngineEntry ::=
    SEQUENCE {
       	aviServiceEngineIndex      Integer32,
       	aviServiceEngineUUID       SnmpAdminString,
       	aviServiceEngineName       DisplayString,
       	aviServiceEngineAddrType   InetAddressType,
       	aviServiceEngineAddr       InetAddress,
       	aviServiceEngineStatus     INTEGER
    }
aviServiceEngineUUID	: Unique UUID of the Avi Service Engine VM
aviServiceEngineName	: Name of the Service Engine VM 
                          assigned in the Virtual Infrastructure
aviServiceEngineAddr	: Management v4 IP address of the Avi Service 
                          Engine VM
aviServiceEngineStatus 	: Runtime status of the Avi Service Engine

Virtual Service

AviVirtualServiceEntry ::=
    SEQUENCE {
       	aviVirtualServiceIndex      Integer32,
       	aviVirtualServiceUUID       SnmpAdminString,
       	aviVirtualServiceName       DisplayString,
       	aviVirtualServiceAddrType   InetAddressType,
       	aviVirtualServiceAddr       InetAddress,
       	aviVirtualServiceStatus     INTEGER
    }
aviVirtualService UUID	: Unique UUID of the virtual service
aviVirtualServiceName	: Name assigned to the virtual service
aviVirtualServiceAddr	: Virtual IP (v4) address of the virtual service 
aviVirtualServiceStatus : Runtime status of the virtual service

Notifications (Traps)

The Controller cluster leader can issue SNMP trap notifications based on system events. For SNMP trap notifications to reach an external SNMP server, the following configurations should be done:

  • Since the leadership role can change from time to time, the external SNMP server should be configured to allow traffic from any one of the three Controllers in the cluster, i.e., all three addresses should be in the SNMP server’s allowed-access list.
  • The firewall rules should be configured to allow UDP traffic destined to port 162 on the SNMP trap server from any of the three cluster member’s IP addresses.

System events related to the Avi Controller cluster, Avi Service Engines, virtual services and SSL certification expiry can be classified into their respective SNMP traps. Other system events use the generic SNMP trap notification to generate traps.

Only the alerts generated for the following events are fed into the specific SNMP traps.

Events SNMP trap
VS_DOWN, VS_UP aviVirtualServiceStatusChanged
SE_DOWN, SE_UP aviServiceEngineStatusChanged
CONTROLLER_NODE_JOINED, CONTROLLER_NODE_LEFT aviControllerStatusChanged
SSL_CERT_EXPIRE aviSSLCertificateExpired
All other alerts aviSystemAlert

Notes:

  • aviSystemAlert is a generic trap notification and can be associated with any of the system events generated by the Avi Controller.
  • Starting with release 18.2.1, Avi Vantage supports large trap payload (a maximum of 4096 bytes) in SNMP trap notifications. Prior to this, the length of the SNMP trap payload was restricted to 256 bytes.

Example: Viewing the Trap Server Profiles

In the below window, a Controller with IP address 10.10.24.96 reveals its v2 and v3 trap server profiles by responding to https://10.10.24.96/api/snmptrapprofile HTTP request.


{
  "count": 2,
  "results": [
    {
      "uuid": "snmptrapprofile-aa815f66-2190-4ff4-a20f-0c9fe41deff4",
      "url": "https://10.10.24.96/api/snmptrapprofile/snmptrapprofile-aa815f66-2190-4ff4-a20f-0c9fe41deff4",
      "tenant_ref": "https://10.10.24.96/api/tenant/admin",
      "name": "SnmpTrap-2",
      "trap_servers": [
        {
          "version": "SNMP_VER2",
          "ip_addr": {
            "type": "V4",
            "addr": "10.10.0.235"
          },
          "community": "<sensitive>"
        }
      ],
      "_last_modified": "1509670261022622"
    },
    {
      "uuid": "snmptrapprofile-2e28610a-e100-4de7-ae92-20bd7a4ee3b7",
      "url": "https://10.10.24.96/api/snmptrapprofile/snmptrapprofile-2e28610a-e100-4de7-ae92-20bd7a4ee3b7",
      "tenant_ref": "https://10.10.24.96/api/tenant/admin",
      "name": "SnmpTrap-1",
      "trap_servers": [
        {
          "version": "SNMP_VER3",
          "ip_addr": {
            "type": "V4",
            "addr": "10.10.3.1"
          },
          "user": {
            "username": "snmpv3trapuser",
            "auth_type": "SNMP_V3_AUTH_MD5",
            "priv_passphrase": "<sensitive>",
            "auth_passphrase": "<sensitive>",
            "priv_type": "SNMP_V3_PRIV_AES"
          }
        }
      ],
      "_last_modified": "1509670185831024"
    }
  ]
}

aviControllerStatusChanged

aviControllerStatusChanged NOTIFICATION-TYPE
   	OBJECTS {
   	aviControllerStatus,
   	aviOperStatusReason
   	}
	STATUS     current
	DESCRIPTION
	"This alert is generated when Controller status 
   	Changes."
	::= { aviNotificationsObjects 1 }

This trap is generated when the Avi Controller status changes.

The following Controller-state-change system events can initiate the aviControllerStatusChange trap:

  • Controller-Node-Left
  • Controller-Node-Joined

For each of the above Avi Controller status-change events, there is a default system alert configuration and a respective default alert action.

aviServiceEngineStatusChanged

aviServiceEngineStatusChanged NOTIFICATION-TYPE
   	OBJECTS {
   	aviObjectURL,
   	aviServiceEngineStatus,
   	aviOperStatusReason
   	}
   	STATUS     current
   	DESCRIPTION
   	"This alert is generated when Service Engine status 
   	Changes."
	::= { aviNotificationsObjects 2 }

This trap is generated when the Avi SE status changes.

The following Avi SE status-change events can initiate the aviServiceEngineStatusChanged trap:

  • SE-Up
  • SE-Down

For each of the above Avi SE status-change events, there is a default system alert configuration.

aviVirtualServiceStatusChanged

aviVirtualServiceStatusChanged NOTIFICATION-TYPE
   	OBJECTS {
   	aviObjectURL,
   	aviVirtualServiceStatus,
   	aviVirtualServiceStatusReason
   	}
   	STATUS     current
   	DESCRIPTION
   	"This alert is generated when virtual service status 
   	changes."
   	::= { aviNotificationsObjects 3 }

This trap is generated when the virtual service status changes.

The following virtual service status-change events can initiate the aviVirtualServiceStatusChanged trap:

  • VS-Down
  • VS-Up

To configure SNMP traps for the Avi Controller status-change events, click here.

aviSSLCertificateExpired

aviSSLCertificateExpired NOTIFICATION-TYPE
	OBJECTS {
   	aviObjectURL,
   	aviSSLCertificateInfo
   	}
   	STATUS     current
   	DESCRIPTION
   	"This alert is generated when SSL Certificate 
   	Expires."
   	::= { aviNotificationsObjects 4 }

This trap is generated when an SSL certificate expires. The virtual service Ssl-Cert-Expire event can initiate the aviVirtualServiceStatusChanged trap. 

To configure SNMP traps for the Avi Controller status-change events, click here.

aviSystemAlert

aviSystemAlert NOTIFICATION-TYPE
	OBJECTS {
   	aviSystemAlertInfoDesc
   	}
   	STATUS     current
   	DESCRIPTION
   	"This is a generic system alert"
   	::= { aviNotificationsObjects 5 }

This is a generic trap notification. It can be associated with any of the system events generated by the Avi Controller.

Configuring SNMP Event-based Trap

This section shows the configuration for generating an SNMP trap when a “VS-Down” event occurs. The workflow is described here, and also shown here:

Alert-Workflow

  In the following example from the Avi Controller web interface, the “VS-Down” event is shown associated with a new alert action named “my-SNMP-alert-action.” However, you can modify the default alert action System-Alert-Level-High. You can leave the system default alert action unchanged, and instead create a new custom alert action.

snmp-alertconfig-workflow2

In Alert Configuration editor, the alert action is configured: snmp-alertconfig-workflow3

In Alert Action editor (navigate to Operations > Alerts > Alert Actions). The named action is associated with SNMP trap notification. snmp-alertconfig-workflow4

  • Name - Specify the notification as “my-SNMP-trap-notification”.
  • Alert Level - Select the alert level as Low, Medium or High from the drop-down list.
  • Email - Select the email notification configuration to send alerts via email.
  • Syslog - Select the system log notification configuration to use when sending alerts via Syslog.
  • SNMP Trap - Select SNMP trap notification to use when sending alerts via SNMP trap from the drop-down list.
  • ControlScript - Select ControlScript profile from the drop-down list.

The named notification is defined in the notification editor.

Note: Multiple SNMP servers are supported. (Click the green + box to add.)

snmp-alertconfig-workflow5
The above UI screen has evolved for Avi Vantage 17.2.3+ as shown below.

For SNMPv2:

SNMPv2Trap.jpg

For SNMPv3:

SNMPv3Trap.jpg


Verify if SNMP trap notification is defined:

snmp-alertconfig-workflow6

Alternate Download Locations for MIBs

The following are the alternate download locations for MIBs: