This recipe centers on SNMP. Here, you will learn how to use Orchestrator to receive SNMP traps from vCenter/ESXi and use them to trigger workflows.
For this recipe, we need an SNMP source. We will use vCenter and ESXi hosts as SNMP sources.
To prepare vCenter and ESXi servers to send or receive SNMP messages, refer to the There's more... section of this recipe.
We will split this recipe into configuring and using SNMP with Orchestrator.
To configure Orchestrator to send or receive SNMP messages from SNMP devices, follow these steps for each SNMP device:
- In Device address, enter the IP or FQDN of the device you want to send or receive SNMP messages to/from.
- In the Orchestrator Client, start the workflow by navigating to Library | SNMP | Device Management | Register an SNMP device.
- Name is just a string to identify the SNMP device in the inventory.
- The Advanced function is the configuration that is used to send SNMP messages. Here, you can configure the port, the protocol function, as well as the community string for sending.
Having configured ESXi to send and receive SNMP messages, let's try one out:
- In the Orchestrator Client, start the workflow by navigating to Library | SNMP | Query Management | Add a query to an SNMP device.
- In Device, select the ESXi server and select GET in Type.
- In OID, enter
1.3.6.1.2.1.1.5.0(this gets the hostname of the device). - In Name, enter
Hostname. - Next, run the query by running the workflow; navigate to Library | SNMP | Query Management | Run an SNMP query.
- Select the query underneath the ESXi SNMP device and click on Submit. Check the logs for the results.
Refer to the How it works... section for more information about OIDs.
vCenter can only send an SNMP message using an alarm configured to send SNMP messages. We will configure an alarm that goes off when a new resource pool is created:
- Open your vSphere Web Client.
- Navigate to the object the alarm should be added to, such as a cluster.
- Click on the Manage tab and then click on Alarm Definitions.
- Click on Add (the green plus icon).
- Give the new alarm a name such as
SNMP Example, opt to monitor Clusters, and select specific event occurring on this object. - Use add (the green plus icon) to add a trigger. Use the selector to choose Resource Pool created and set the status to Warning. Click on Next.
- Use add (the green plus icon) to add an action. Use the selector to choose Send a notification trap and click on Finish.
Note
To learn more about vCenter alarms, please take a look at the vSphere documentation, or check out this article: http://www.pearsonitcertification.com/articles/article.aspx?p=1928231&seqNum=6
After you have configured vCenter to send an SNMP alarm, we now use Orchestrator to receive the SNMP message:
- In Orchestrator, start the workflow by navigating to Library | SNMP | Wait for a trap on an SNMP device.
- Select the SNMP device you want to listen to. The OID is optional.
- The workflow will pause until it receives an SNMP message from the selected device.
- In vCenter, create a new resource pool. This should trigger the configured alarm and send an SNMP message to Orchestrator.
- Check the logs of the workflow after it has received the SNMP message.
Refer to the How it works... section for more information about OID.
To use Orchestrator to continually monitor a device for new SNMP messages, follow these steps:
- Switch Orchestrator to the Administer mode.
- Click on Policy Templates (the yellow page with a green border icon).
- Navigate to Library | SNMP | SNMP Trap and select Apply policy.
- Give the new policy a name and description.
- Select the SNMP device you would like to use and click on Submit.
- Orchestrator automatically switches to the Run mode, into the Policies section, and onto the policy you have just created. Select Edit (the pencil icon).
- In Scripting, expand the subscription and click on OnTrap.
- In the Script tab, you will find that there is already a script that will output the SNMP message to the logs.
- Save and close.
Instead of the existing script, you can create a script or workflow to phrase the SNMP messages. To get to the SNMP message data from the policy event as an array of properties, follow this script:
//get the SNMP data out of the Policy
var key = event.getValue("key");
var snmpResult = SnmpService.retrievePolicyData(key);
// convert the SNMPSnmpResult into Array of Property
var data = System.getModule("com.vmware.library.snmp").processSnmpResult(snmpResult);
You can then use the OID number to fork to different workflows to address the issues raised by the SNMP message. A very good example of this can be found at http://blogs.vmware.com/orchestrator/2013/04/vcenter-operations-integration-with-vcenter-orchestrator-in-5-minutes-or-less.html .
SNMP stands for Simple Network Management Protocol and is used to manage and monitor systems by sending or receiving SNMP messages. A system can be monitored or managed by either making it send SNMP messages, or by responding to requests for information.
Each SNMP message can be accompanied by a community string. When an SNMP message is received, the receiver checks the community string against the one defined in the SNMP trap. If the string matches the message, it is accepted. The community string acts as a security measure. The default community string is public.
The important thing to understand about vCenter is that vCenter can only send SNMP messages when it starts up or when a triggered alarm is configured to send an SNMP message; it doesn't respond to SNMP requests.
ESXi hosts, however, can not only send messages, but can also react to SNMP requests.
A Management Information Base (MIB) is a file that contains descriptions of Object Identifiers (OIDs). Each vendor defines its own OIDs that are then distributed in MIBs. The VMware MIBs can be downloaded from kb.vmware.com/kb/1013445.
A text file that can be downloaded from kb.vmware.com/kb/2054359 contains all the VMware OIDs in a more readable version.
The return data of the default SNMP workflows is an array of properties. Each of the array elements contains one OID. Each property contains the following keys:
|
Key |
Meaning |
Example key content |
|
|
The OID identifier |
|
|
|
The Orchestrator variable type |
|
|
|
The SNMP variable type |
|
|
|
The content of the message |
|
However, this is produced by the processSnmpResult action in the com.vmware.library.snmp module. The real SNMP results are stored in a bit more complex variable type, which is SNMPSnmpResult. In Orchestrator, it is easier to work with the array of properties, but check out the action and the variable type yourself.
The default port to send SNMP messages on is TCP 162; however, due to the fact that Linux systems have security restrictions for listening on ports below 1024, the Orchestrator SNMP listener is set to listen on port 4000. This is true for the Orchestrator appliance as well as for the Windows installation.
If you have a device that is not able to send SNMP messages on any port other than 162, here is a way around it (at least with the appliance):
- Log in to your Orchestrator appliance with the root.
- Run the following command:
iptables -t nat -A PREROUTING -p udp --dport 162 -j REDIRECT --to 4000 - To make this change stick, run the following command:
iptables-save
In this section, we take a look at how to configure SNMP on vCenter and on ESXi.
For vCenter to be able to send SNMP messages using alarms, we need to configure it first:
- You can add up to four different SNMP receivers that vCenter can send messages to. For each one you need to specify the following:
- Click on SNMP receivers.
- Click on Settings and then click on Edit.
- Navigate to your vCenter and then click on the Manage tab.
- Open your vSphere Web Client.
- The IP or FQDN of the SNMP receiver.
- The port. The default is
TCP 162; however, the listener on the Orchestrator appliance is set toTCP 4000. - The community string (if you're unsure, use the default,
public).
- When finished, click on OK.
- Don't forget to configure your firewall to allow
TCP 4000out.
There are quite a lot of ways to configure SNMP on ESXi hosts. However, they all come down to the same basic method: set SNMP locally for every ESXi, and then open the ESXi firewall. You can use PowerCLI or any other method to interact with the API or use host profiles. In the following steps, we will use the esxcli command directly on the ESXi host to configure SNMP v1 and v2. Please note that the default port of the Orchestrator SNMP listener is TCP 4000 not TCP 162:
- Configure the SNMP target(s):
esxcli system snmp set --targets target_address@port/community
- Set a different GET port for SNMP (if required):
esxcli system snmp set --port port
- Enable SNMP:
esxcli system snmp set --enable true
- Allow SNMP on the ESXi firewall:
esxcli network firewall ruleset set --ruleset-id snmp --allowed-all true -- enabled true esxcli network firewall refresh
We have used the local esxcli commands in this example simply because you could write an SSH workflow to patch all your ESXi hosts based on this example.
To configure SNMP v3 (using authentication and encryption), take a look at the vSphere Monitoring and Performance Guide, which is part of the VMware vSphere documentation set.
By default, ESXi SNMP is configured to send SNMP messages for CIM hardware monitoring. This means that you will receive SNMP messages if a hardware component of your ESXi server is alerted.
Check out the SNMP example that comes with vRO7.
An example of automating hardening for new VMs is here: http://blogs.vmware.com/vsphere/2012/07/automatically-securing-virtual-machines-using-vcenter-orchestrator.html
Here's an example showing you how to integrate vCOPs into Orchestrator: http://blogs.vmware.com/orchestrator/2013/04/vcenter-operations-integration-with-vcenter-orchestrator-in-5-minutes-or-less.html