XenServer

Monitor host and dom0 resources with SNMP

February 17, 2025

Contributed by:

Note:

The SNMP feature is available for XenServer Premium or Trial Edition customers. For more information about XenServer licensing, see Licensing. To upgrade, or to get a XenServer license, visit the XenServer website.

With the Pool Admin role, you can use SNMP to remotely monitor resources consumed by your XenServer host and dom0 - the control domain of your host. An SNMP manager, also known as a network management system (NMS), sends query requests to an SNMP agent running on a XenServer host. The SNMP agent replies to these query requests by sending data collected on various metrics back to the NMS. The data that can be collected is defined by object identifiers (OIDs) in a text file called a management information base (MIB). An OID represents a specific piece of measurable information about a network device, such as CPU or memory usage.

You can also configure traps, which are agent-initiated messages that alert the NMS that a specific event has occurred in XenServer. Both query requests and traps can be used to monitor the status of your XenServer pools. These are defined as metric and trap objects and are identified by OIDs in a MIB file XENSERVER-MIB.txt, available to download from the XenServer Downloads page. The following tables provide information about these metric and trap objects.

Metric objects

You can request a specific piece of information about your XenServer hosts by using the metrics listed in the following table. These metrics are used by the SNMP manager when sending query requests to an SNMP agent and so you can view this data in your NMS.

You can view the returned data from these metric objects from your NMS or from the xe CLI. To query the metric objects from the xe CLI, run host-data-source-query or vm-data-source-query and provide the RRDD data source as a value for the data-source parameter. For example:

xe host-data-source-query data-source=cpu_avg host=<host UUID>
<!--NeedCopy-->

Note:

By default, the NMS sends OID query requests to SNMP agents using port 161.

Object identifier (OID)	RRDD data source	Returned data	Type
1.3.6.1.4.1.60953.1.1.1.1	`memory`	Dom0 total memory in MB	Unsigned32
1.3.6.1.4.1.60953.1.1.1.2	`memory_internal_free`	Dom0 free memory in MB	Unsigned32
1.3.6.1.4.1.60953.1.1.1.3	`cpu_usage`	Dom0 CPU usage as a percentage	Float
1.3.6.1.4.1.60953.1.1.1.4	`memory_total_kib`	Host total memory in MB	Unsigned32
1.3.6.1.4.1.60953.1.1.1.5	`memory_free_kib`	Host free memory in MB	Unsigned32
1.3.6.1.4.1.60953.1.1.1.6	`cpu_avg`	Host CPU usage as a percentage	Float
1.3.6.1.4.1.60953.1.1.1.7	(see note 1)	pCPUs number	Unsigned32
1.3.6.1.4.1.60953.1.1.1.8	`running_vcpus`	Running vCPUs number	Unsigned32
1.3.6.1.4.1.60953.1.1.1.9	`running_domains`	Running VMs number	Unsigned32

Notes:

The name of a pCPU is in the format cpu followed by a number. To query the number of pCPUs from the xe CLI, run the following command:

xe host-data-source-list host=<host UUID> | grep -E 'cpu[0-9]+$'

This returns a list of the CPU metrics that match the regular expression cpu[0-9]+.

Traps

Traps are alerts sent by the SNMP agent to notify the SNMP manager when certain events occur, allowing you to monitor your XenServer hosts and identify issues early. You can configure your SNMP settings to generate a trap when a limit is reached (for example, if the host CPU usage is too high). When a trap is generated, it is sent to your NMS and the following fields are returned as part of the trap object.

Note:

By default, the SNMP agent on the pool coordinator host sends traps to the NMS using UDP port 162.

Object identifier (OID)	Field name	Type	Description
1.3.6.1.4.1.60953.1.10.1.1	`operation`	String	Can be one of the following values: `add` or `del`. `operation` is `add` if a trap is generated by XenServer and sent to your NMS (an alert is also created in XenCenter) or `del` if an alert is destroyed (for example, if you dismiss an alert).
1.3.6.1.4.1.60953.1.10.1.2	`ref`	String	The reference for the trap object.
1.3.6.1.4.1.60953.1.10.1.3	`uuid`	String	The UUID of the trap object.
1.3.6.1.4.1.60953.1.10.1.4	`name`	String	The name of the trap object.
1.3.6.1.4.1.60953.1.10.1.5	`priority`	Integer	The severity of the trap. Can be one of the following values: `1`: Critical, `2`: Major, `3`: Warning, `4`: Minor, `5`: Information, `others`: Unknown.
1.3.6.1.4.1.60953.1.10.1.6	`class`	String	The category of the trap generated. Can be one of the following values: `VM`, `Host`, `SR`, `Pool`, `VMPP`, `VMSS`, `PVS_proxy`, `VDI`, or `Certificate`.
1.3.6.1.4.1.60953.1.10.1.7	`obj-uuid`	String	The xapi object UUID of the various classes of the field `class`.
1.3.6.1.4.1.60953.1.10.1.8	`timestamp`	String	The time at which the trap is generated.
1.3.6.1.4.1.60953.1.10.1.9	`body`	String	Detailed information about the field `name`.

Prerequisites

All hosts in a pool must be running the same XenServer version and this version must contain the SNMP plugin.

Note:

If you cannot see the SNMP tab in XenCenter, it might be because the host or a member of the pool is not running a version of XenServer that supports SNMP. Update the host or pool to the latest version of XenServer.
The NMS you are using must support SNMPv2c or SNMPv3.
Your NMS and XenServer must be network-connected.

Constraints

You can configure SNMP settings for an entire pool or for a standalone host that is not part of a pool. Currently, you cannot configure SNMP settings for an individual host in a pool.
If you add a host to a pool that already has SNMP enabled and configured on it, XenCenter does not automatically apply the pool’s SNMP settings to the new host. You must reconfigure SNMP settings on the pool after adding the new host or configure the new host with the same SNMP settings before adding it to the pool.

Note:

When reconfiguring SNMP settings on a pool after adding a new host, ensure the host is up and running and not in maintenance mode.
Before performing a rolling pool upgrade from Citrix Hypervisor 8.2 CU1 to XenServer 8.4 or applying updates to your XenServer hosts and pools, back up the following configuration files if you manually modified them before and need them:
- /etc/snmp/snmpd.xs.conf
- /etc/sysconfig/snmp
- /var/lib/net-snmp/snmpd.conf
When the SNMP agent is offline, traps cannot be generated. For example, if the SNMP agent is restarted or the pool coordinator is rebooted or re-designated.

Configure SNMP by using the xe CLI

You can configure SNMP by using the xe CLI or XenCenter. For more information on how to configure SNMP by using XenCenter, see Monitoring host and dom0 resources with SNMP.

`result` objects

When configuring SNMP, all responses are returned in JSON format. If a command executes successfully, it returns the key value pair "code": 0. Some commands (such as the get-config command) return a nested JSON object called result. The result JSON object is also required for the set-config command which is used to update the SNMP configuration.

The result JSON object is made up of the following objects common, agent, and nmss:

common

Field	Allowed values	Default value
`enabled`	`no` (disable SNMP service) or `yes` (enable SNMP service)	`no`
`debug_log`	`no` (disable debug logging) or `yes` (enable debug logging)	`no`
`max_nmss`	N/A (This field is read-only and specifies the max number of supported NMSs)	`1`

agent

Field	Allowed values	Default value
`v2c`	`no` (disable SNMPv2c) or `yes` (enable SNMPv2c)	`yes`
`community`	COMMON_STRING_TYPE (see note 1)	`public`
`v3`	`no` (disable v3) or `yes` (enable v3)	`no`
`user_name`	COMMON_STRING_TYPE (see note 1)
`authentication_password`	COMMON_STRING_TYPE where length >= 8 (see note 1)
`authentication_protocol`	`MD5` or `SHA`
`privacy_password`	COMMON_STRING_TYPE where length >= 8 (see note 1)
`privacy_protocol`	`DES` or `AES`
`engine_id`	N/A (This field is read-only and is generated when the SNMP agent starts for the first time)

nmss

Field	Allowed values	Default value
`uuid`	NMS UUID (You set this when you configure the NMS trap receiver and this value should be consistent across all hosts in a pool)
`address`	NMS IPv4 address or host name (FQDN)
`port`	`1` to `65535`	`162`
`v2c`	`no` (disable SNMPv2c), `yes` (enable SNMPv2c), or support either SNMPv2c or v3.	`yes`
`community`	COMMON_STRING_TYPE (see note 1)	`public`
`v3`	`no` (disable v3), `yes` (enable v3), or support either SNMPv2c or SNMPv3.	`no`
`user_name`	COMMON_STRING_TYPE (see note 1)
`authentication_password`	COMMON_STRING_TYPE where length >= 8 (see note 1)
`authentication_protocol`	`MD5` or `SHA`
`privacy_password`	COMMON_STRING_TYPE where length >= 8 (see note 1)
`privacy_protocol`	`DES` or `AES`

Notes:

COMMON_STRING_TYPE refers to a string that meets the following requirements:

Any combination of letter, number, hyphen (-), period (.), pound (#), at sign (@), equals (=), colon (:) or underscore characters (_).

Length between 6 and 32 inclusive.

Passwords are not stored in plaintext in any configuration file in XenServer. They are converted to a localized key and stored. The get-config command shows the password as a hidden constant comprised of asterisks (*).

Configure the SNMP service

Get the status of the SNMP service:

xe host-call-plugin host-uuid=<host-uuid> plugin=snmp fn=status
<!--NeedCopy-->

Start, stop, or restart the SNMP service:

xe host-call-plugin host-uuid=<host-uuid> plugin=snmp fn=<operation>
<!--NeedCopy-->

where operation is start, stop, or restart.

Get the SNMP configuration details:

xe host-call-plugin host-uuid=<host-uuid> plugin=snmp fn=get-config
<!--NeedCopy-->

If successful, this command returns the key value pair "code": 0 and the result JSON object containing the configuration details of the SNMP service. For example:

"code": 0,
  "result": {
    "common": {
      "enabled": "no",
      "debug_log": "no",
      "max_nmss": 1
    },
    "agent": {
      "v2c": "yes",
      "v3": "no",
      "community": "public",
      "user_name": "",
      "authentication_password": "",
      "authentication_protocol": "",
      "privacy_password": "",
      "privacy_protocol": "",
      "engine_id": "<engine_id>"
    },
    "nmss": []
  }
<!--NeedCopy-->

Copy the result JSON object to your preferred text editor and remove all newline (\n) characters from the file. Update the fields with your SNMP configuration details. Configure your NMS by referring to your NMS documentation and specifying values for the fields required for the nmss object. For more information, refer to the objects listed above.

To configure the SNMP service, run the set-config command and provide the edited result JSON object as a parameter value to the args:config parameter.

Set the SNMP configuration:

xe host-call-plugin host-uuid=<host-uuid> plugin=snmp fn=set-config args:config='<result>'
<!--NeedCopy-->

where result is the result JSON object returned from the get-config command that you copied and edited.

Note:

To configure SNMP for an entire pool, you must run the set-config command for each host in the pool.

If the configuration changes are successful, the command returns the key value pair "code": 0. If the configuration changes are unsuccessful, the set-config command returns one of the following key value pairs which indicate that an error has occurred:

"code": 1: Common error string. For example, an unknown exception.
"code": 2: Error string (parameter is missing).
"code": 3: Returns a message object as a list where each element is in the format of [field_path, key, value, error string].

You can also send a test SNMP trap to your NMS to verify that the specified trap receiver information is correct.

Send a test SNMP trap:

xe host-call-plugin host-uuid=<host-uuid> plugin=snmp fn=send-test-trap args:config='{"nmss":[{"uuid":"<uuid>","address":"<address>","port":162,"v2c":"yes","v3":"no","community":"public","user_name":"<user_name>","authentication_password":"<authentication_password>","authentication_protocol":"<authentication_protocol>","privacy_password":"<privacy_password>","privacy_protocol":"<privacy_protocol>"}]}'
<!--NeedCopy-->

This command sends a test trap to your NMS with the msg_name of TEST_TRAP and the msg_body of This is a test trap from XenServer pool "<pool name>" to verify the NMS Trap Receiver configuration.

If you do not receive the test trap, check your SNMP configuration again. If unsuccessful, the send-test-trap command also returns one of the following key value pairs which indicate that an error has occurred:

"code": 1: Common error string. For example, an unknown exception.
"code": 2: Error string (parameter is missing).
"code": 3: Returns a message object as a list where each element is in the format of [field_path, key, value, error string].
"code": 4: Returns a message object as a list where each element is in the format of [nms address, nms port, error string].

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Monitor host and dom0 resources with SNMP

February 17, 2025

Contributed by:

February 17, 2025

Contributed by:

Monitor host and dom0 resources with SNMP

Metric objects

Traps

Prerequisites

Constraints

Configure SNMP by using the xe CLI

result objects

Configure the SNMP service

In this article

`result` objects