cPanel® Blog

Writing a Multi-Server Load Average Monitoring Script in Under 10 Lines of PHP

Mostly the XML API is used for account management; however, there are other features in it that simplify system administration. The most obvious of these functions is the loadavg call.

Last year, I wrote a class for working with the XML API from PHP. This class returns SimpleXML objects for each XML API call made. This makes development of remote cPanel interactions extremely simple.

I’m going to go over how to build a quick-and-dirty multi-server load average monitoring system in PHP using this class.

For this script, we’ll store access credentials in an XML file class named monitor.xml. The reason for using XML is so that we can store this data in an easy-to-read/modify format (even programmatically). This is far simpler than using an array of associative arrays for doing this, as access hashes tend to be large.

This is the schema that I have decided upon using:
<monitor>
<server>
<ip>...</ip>
<accesshash>..</accesshash>
<user>..</user>
</server>
<server>
..
</server>
</monitor>

If you are not familiar with access hashes, these correspond to the hash stored in either ~/.accesshash or Setup Remote Access Keys in WHM.

To load this data structure inside of our script, we want to do the following:

$conf = simplexml_load_file("monitor.xml");

Once the configuration of this script has been set in place, we can start on the actual logic of this script, which in this case will consist (mostly) of a loop over all of the servers in the XML.
foreach ( $conf->server as $server ) {
# Logic Here
}

With the configuration and iteration worked out, we will want to include and instantiate the XML API class. This class only takes one parameter in its constructor: the host of the server it’s managing.
$conf = simplexml_load_file("monitor.xml");
include("xmlapi.php.inc");
foreach ( $conf->server as $server ) {
$xmlapi = new xmlapi( $server->ip );
}

Next, we will want to set up how to authenticate to the XML API.

Generally speaking, WHM Auth should always be used for any type of automation for numerous reasons, namely because it does not have the same security restrictions as Basic Auth or Cookie Auth. The only reason this shouldn’t be done is client-side applications where you may not necessarily know the username and password.

To do this with the XML API PHP class, you should use the hash_auth function, which will set the appropriate headers.
$conf = simplexml_load_file("monitor.xml");
include("xmlapi.php.inc");
foreach ( $conf->server as $server ) {
$xmlapi = new xmlapi( $server->ip );
$xmlapi->hash_auth( $server->user, $server->accesshash);
}

Once this has been set up, we are ready to run whatever commands we need to run. Using this class, we can call loadavg by just calling the loadavg method within the XML API class.
$conf = simplexml_load_file("monitor.xml");
include("xmlapi.php.inc");
foreach ( $conf->server as $server ) {
$xmlapi = new xmlapi( $server->ip );
$xmlapi->hash_auth( $server->user, $server->accesshash);
$loadavg = $xmlapi->loadavg;
}

At this point, $loadavg will contain the loadavg information, similar to what’s in /proc/cpuinfo, but in a SimpleXML format. All we have to do now is display this data:
$conf = simplexml_load_file("monitor.xml");
include("xmlapi.php.inc");
foreach ( $conf->server as $server ) {
$xmlapi = new xmlapi( $server->ip );
$xmlapi->hash_auth( $server->user, $server->accesshash);
$loadavg = $xmlapi->loadavg;
print "<br>" . $server->ip . ": " . $loadavg->one . ", " . $loadavg->five . ", " . $loadavg->fifteen;
}

We are ready to run this script. Once executed, you should see something like the following for each server in monitor.xml:
127.0.0.1: 0.00, 0.00, 0.00

Now that this has been written, there is a HUGE security issue within this script that needs to be addressed. The following line is our offending code:
$conf = simplexml_load_file("monitor.xml");

This is an issue, as it is loading monitor.xml from within a document root (for example, $USERHOME/public_html/monitor.xml). This means that anyone could download this file and then authenticate to your server’s WHM account. Instead, this file will need to be stored in a secure location outside of the document root, such as ~/monitor.xml.

The other concern with this is that this file should always have permissions of 400, never readable by other users. This script should only be executed as suPHP or off of a shared hosting system, so that it cannot be read by other users on the system.

cPanel

The web hosting industry’s most reliable, intuitive control panel since 1997. With our first-class support and rich feature set, it’s easy to see why our customers and partners make cPanel & WHM their hosting platform of choice. For more information, visit cPanel.com.