How to Write Your Own Utilities Using Plesk CLI and API-RPC

Every now and then the Plesk development team gets requests to expand the functionality of existing command line utilities or to add new ones. We try to take such requests into account, but, seeing as major Plesk releases only happen roughly once a year, many months may pass before a customer’s vision becomes a reality. However, there is another way to get the desired functionality. If you find yourself in a situation where no existing utility does exactly what you want to, you can create your own using Plesk API-RPC and expanding upon the functionality of existing Plesk CLI utilities.

Custom utilities are created by using a command line API client to send an API call to Plesk (local or remote) and receive the response, or by incorporating an existing Plesk CLI utility into a shell script. Our GitHub repository contains usable examples of command line API clients in a dozen different programming languages. You only need to modify them and, potentially, process the output (which will come in the form of an .xml response packet). This way you can create a utility that is able to do anything you can do via API (by the way, to learn what you can do via API, take a look at our API-RPC guide).

I will illustrate the concept with two examples. The first is written in bash, and it tells you on which Plesk server a particular domain is hosted. The second is written in PHP, and it displays resource usage data for all subscriptions on the server.

Where is example.com?

Imagine that you are a Plesk administrator, running a number of Plesk servers. You need to make some changes to the configuration of the example.com domain, but you cannot quite remember on which server the domain is hosted. Yes, you can log in to your billing solution (if you have one), or check every server in turn, but… doesn’t it sound like too much effort? There is a better solution. You can run the following custom script making use of the Plesk CLI utility ( domain-related ) instead:

First, create a file named whereisit.sh and paste the following code into the file:

#!/bin/bash

SERVERS="server1.example.com server2.example.com"
DOMAIN=$1

for SERVER in $SERVERS; do
   ssh root@${SERVER} "plesk bin domain -i ${DOMAIN} > /dev/null 2>&1"
   if [ 0 -eq $? ]; then
       echo "Domain '${DOMAIN}' found on '${SERVER}'"
   fi
done

Put the hostnames of all Plesk servers to be searched after SERVERS. Separate individual hostnames with the “space” symbol. Make the file executable:

chmod +x whereisit.sh

and run it:

./whereisit.sh example.com

The script will search all the servers you specify and provide output of the following form:

Domain 'example.com' found on 'server1.example.com'

Getting detailed resource usage information

If you need to retrieve information about resource usage on the server for every subscription and store it in a file, the following script will help you. To use it, first create a file named PleskApiClient.php and paste the code found here into it, then create a file named getstats.php and paste the following code inside:

#!/usr/bin/env php
<?php
require_once('PleskApiClient.php');

$host = getenv('REMOTE_HOST');
$login = getenv('REMOTE_LOGIN') ?: 'admin';
$password = getenv('REMOTE_PASSWORD');

$client = new PleskApiClient($host);
$client->setCredentials($login, $password);

$request = <<<EOF
<packet>
<customer>
    <get>
        <filter/>
        <dataset>
            <gen_info/>
        </dataset>
    </get>
</customer>
</packet>
EOF;

$response = new SimpleXMLElement($client->request($request));
$data = array();

foreach($response->customer->get->result as $customer) {
    $data[(int) $customer->id] = array(
        'id' => (int) $customer->id,
        'login' => $customer->data->gen_info->login,
        'email' => $customer->data->gen_info->email
    );
}

$customers = array_keys($data);
$customers = array_map(function($n){ return "<owner-id>$n</owner-id>";}, $customers);
$customers = implode("\n", $customers);

$request = <<<EOF
<packet>
<webspace>
    <get>
        <filter>
            $customers
        </filter>
        <dataset>
            <stat/>
        </dataset>
    </get>
</webspace>
</packet>
EOF;

$response = new SimpleXMLElement($client->request($request));

echo "subscription_id;client_id;login;email;traffic;subdomains;webusers;mailboxes;redirects;mailgroups;autoresponders;maillists;mysql_db;mssql_db;webapps;traffic_prevday;domains;sites\n";

foreach($response->webspace->get->result as $subscription) {
    echo implode(';', array_merge(
            array($subscription->id),
            $data[(int) $subscription->{'filter-id'}],
            array($subscription->data->gen_info->{'ascii-name'}),
            (array)$subscription->data->stat)
        ) . "\n";
}

Place both files in the same directory and run the script like this:

REMOTE_PASSWORD=<Plesk admin password> REMOTE_HOST=<Plesk server hostname or IP> /usr/bin/php getstats.php

The script will output the resource usage information in the semicolon-delimited CSV format, so you can, for example, import it in Excel. Here is a sample output:

id;login;email;traffic;subdomains;webusers;mailboxes;redirects;autoresponders;maillists;mysql_db;mssql_db;webapps;domains;sites
5;wunsch_alessandr;[email protected];0;0;0;0;0;0;0;0;0;0;1;0
7;alexandro0;[email protected];0;0;0;0;0;0;0;0;0;0;1;0
9;devon5;[email protected];303;0;0;0;0;0;0;0;0;0;1;0
13;crona.shane75;[email protected];344;0;0;0;0;0;0;0;0;0;2;1
14;myles;[email protected];1424;0;0;1;0;0;0;0;0;0;1;0

These two examples are merely the tip of the iceberg – you can create all kinds of custom utilities with this method. Your imagination (well, and your programming skills, too) is the limit here. Remember to refer to the API-RPC guide, and we also recommend you to use a browser extension for working with API to make your life easier. If you are using Google Chrome, Postman is a fine choice, but there are others as well – shop around and see what fits you best. You can also use the XML-RPC API Explorer Plesk extension – it is a handy tool to help you create and validate your API requests.