First, we'll make sure that we can get the agent to return any value at all. User parameters are configured on the agent side—the agent daemon contains the key specification, which includes references to commands. On A test host, edit zabbix_agentd.conf and look near the end of the file. An explanation of the syntax is available here:

UserParameter=<key>,<shell command> 

This means that we can freely choose the key name and command to be executed. It's suggested that you keep key names to lowercase alphanumeric characters and dots. For starters, add a very simple line like this:

UserParameter=quick.test,echo 1 

Just return 1, always. Save the configuration file and restart the Zabbix agent daemon. While it might be tempting to add an item like this in the frontend, it's highly recommended to test all user parameters before configuring them in the frontend. That'll provide the results faster and overall make your life simpler. The easiest way to test an item is with zabbix_get; we discussed this small utility in Chapter 3, Monitoring with Zabbix Agents and Basic Protocols. Run on A test host:

$ zabbix_get -s 127.0.0.1 -k quick.test 

That should return just 1. If it does, great—your first user parameter is working. If not, well, there's not much that could go wrong. Make sure the correct file was being edited, the agent daemon was really restarted, and that the correct host was queried.

We won't actually add this item in the frontend as it won't provide much value. Instead, let's re-implement an item that is already available in the Zabbix agent, counting the number of logged-in users. Edit zabbix_agentd.conf again and add the following near our previous modification:

UserParameter=system.test,who | wc -l 

Notice how we can chain multiple commands. In general, anything the underlying shell would accept would be good. Save the file and restart the Zabbix agent daemon. Now, quick test again by running this command from the Zabbix server (don't forget to replace 127.0.0.1 with the IP of your host) or from the host:

$ zabbix_get -s 127.0.0.1 -k system.test

That should return a number, as you are probably running zabbix_get from the same system; it should be at least 1. Let's create an item to receive this data in the frontend:

1. Open Configuration | Hosts, make sure Linux servers is selected in the Group drop-down menu, click on Items next to A test host, then click on Create item. Fill in these values:

• • Name: Users logged in
  • Type: Zabbix agent (active)
  • Key: system.test

We're using the active item type with our user parameter. User parameters are suggested to be used as active items as they can tie up server connections if they don't return very quickly. Notice how we used exactly the same key name as specified in the agent daemon configuration file.

2. When you're done, click on Add.
3. Now check Monitoring | Latest data. As this is an active item, we might have to wait for the agent to request the item list from the server, then return the data, which can take up to two minutes in addition to the server updating its cache in one minute. Sooner or later, the data will appear.

The great thing is that it's all completely transparent from the server side—the item looks and works as if it was built in.

We have gotten a basic user parameter to work, but this one replicates the existing Zabbix agent item, so it still isn't that useful. The biggest benefit provided by user parameters is the ability to monitor virtually anything, even things that aren't natively supported by the Zabbix agent, so let's try some slightly more advanced metrics.