How To Create Remote API Scripts For ISPConfig 3

Introduction

This guide will walk through the instructions on how to create an API script to create an ftp user in ISPConfig 3. It will give you the knowledge to develop scripts for any function available in ISPConfig 3.

Final Product

So let's look at the script we will be analyzing.

Breaking Down The Lines

The first place you start when creating an API script is at the function. The function is the part of the code that adds the ftp user to the databases.

$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params_ftp);

As you can see from the code above site_ftp_user_add is the function to add an ftp user. All the functions have names like this so you will never wonder what it does. In order to find out all functions that are available you need to look at /usr/local/ispconfig/interface/lib/classes/remoting.inc.php.

It will look like this:

?//* Add a record
	public function sites_ftp_user_add($session_id, $client_id, $params)
    {
		if(!$this->checkPerm($session_id, 'sites_ftp_user_add')) {
			$this->server->fault('permission_denied', 'You do not have the permissions to access this function.');
			return false;
		}
		return $this->insertQuery('../sites/form/ftp_user.tform.php',$client_id,$params);
	}

Alright so we know from the line that says,

public function sites_ftp_user_add($session_id… 

that there is a function called sites_ftp_user_add.

Let's look at the entire line where the function will reside in our new script.

$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params_ftp);

Let's break this line down so you know what you need to change to adjust this to any function.

$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params_ftp);

The $domain_id is a variable that you will not need to change as the variable is not used in the execution of the function. 

$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params_ftp);

$client-> is a variable you should never change, so do not mess with it.

$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params_ftp);

As stated above this is the function and will change depending on the task you wish the script to do.

$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params_ftp);

This section can change depending on the function. From the /usr/local/ispconfig/interface/lib/classes/remoting.inc.php you will see the line

public function sites_ftp_user_add($session_id, $client_id, $params)

This is where you will get what needs to go after the function.

Above the function line you will see the creation of the function's array. This is where the information that will be used to create the ftp user is given.

$params = array( 'server_id'			=> '1',
							'parent_domain_id'		=> $domain_id,
							'username'			=> $myusername,
							'password'			=> $mypassword,
							'quota_size'			=> '-1',
							'active'			=> 'y',
							'uid'				=> 'web'.$domain_id,
							'gid'				=> 'client'.$client_id,
							'dir'				=> '/var/www/clients/client'.$client_id.'/web'.$domain_id,
							'quota_files'			=> '100',
							'ul_ratio'			=> '-1',
							'dl_ratio'			=> '200',
							'ul_bandwidth'			=> '-1',
							'dl_bandwidth'			=> '100',);

This will always start with

$variable = array ( 

but we do not know what information we need to type in with every function without looking it up.

Going back to /usr/local/ispconfig/interface/lib/classes/remoting.inc.php you will look up the function being used:

?//* Add a record
	public function sites_ftp_user_add($session_id, $client_id, $params)
    {
		if(!$this->checkPerm($session_id, 'sites_ftp_user_add')) {
			$this->server->fault('permission_denied', 'You do not have the permissions to access this function.');
			return false;
		}
		return $this->insertQuery('../sites/form/ftp_user.tform.php',$client_id,$params);
	}

This is telling up what file has the array information needed. Now let's use our find command:

sudo find / -name ftp_user.tform.php

And open up the document. Should look like:

'password' => array (
			'datatype'	=> 'VARCHAR',
			'formtype'	=> 'PASSWORD',
			'encryption' => 'CRYPT',
			'default'	=> '',
			'value'		=> '',
			'width'		=> '30',
			'maxlength'	=> '255'
		),
		'quota_size' => array (
			'datatype'	=> 'INTEGER',
			'formtype'	=> 'TEXT',
			'validators'	=> array ( 	0 => array (	'type'	=> 'NOTEMPTY',
														'errmsg'=> 'quota_size_error_empty'),
										1 => array (	'type'	=> 'REGEX',
														'regex' => '/^(\-1|[0-9]{1,10})$/',
														'errmsg'=> 'quota_size_error_regex'),

As you can see I am showing two examples that would be transformed to

'password' => 'yourpassword'

and

'quota_size' => 'quota size'

Using everything we have learned so far we can create:

$params = array( 'server_id'			=> '1',
							'parent_domain_id'		=> $domain_id,
							'username'			=> $myusername,
							'password'			=> $mypassword,
							'quota_size'			=> '-1',
							'active'			=> 'y',
							'uid'				=> 'web'.$domain_id,
							'gid'				=> 'client'.$client_id,
							'dir'				=> '/var/www/clients/client'.$client_id.'/web'.$domain_id,
							'quota_files'			=> '100',
							'ul_ratio'			=> '-1',
							'dl_ratio'			=> '200',
							'ul_bandwidth'			=> '-1',
							'dl_bandwidth'			=> '100',);
	$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params);

Not too much farther to go. All we need to do now is have our remote user log in and log out. Make sure you have created a remote user in ISPConfig Control panel by going to the System tab and then click Add Remote User on the left.

Here is the beginning of the script to log into Soap.

$username = 'yourusername';
$password = 'yourpassword';
/*
$soap_location = 'http://localhost:8080/ispconfig3/interface/web/remote/index.php';
$soap_uri = 'http://localhost:8080/ispconfig3/interface/web/remote/';
*/
$soap_location = 'http://localhost:8080/remote/index.php';
$soap_uri = 'http://localhost:8080/remote/';

You should put your Shell User where it says "yourusername", and ?the password in "yourpassword." You should also put in your soap?location and uri, but more than likely you will not have to change this.

$client = new SoapClient(null, array('location' => $soap_location,
                                    
'uri'      => $soap_uri));
try {
    //* Login to the remote server
    if($session_id = $client->login($username,$password)) {
        echo 'Logged into remote server
sucessfully. The SessionID is '.$session_id.'
';

No changes are needed to this section unless you want to change

 echo 'Logged into remote server sucessfully. The SessionID is '.$session_id.'
';

to ouput a different message.

End the script with the following to log out. Nothing has to be changed in the last section.

	//* Logout
	if($client->logout($session_id)) {
		echo "FTP Created";
	}
	
} catch (SoapFault $e) {
	die('SOAP Error: '.$e->getMessage());
	echo "Please contact the server administator";
}
?>;