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";
}
?>;
Share this page:

Suggested articles

10 Comment(s)

Add comment

Comments

By: skuli434

Hello 

 I want to thank you for this great guide, really helped me lot, 

 

By:

I am just glad it helped someone out.

By: Igor

Thank you for the tutorial, it was very helpful!

One thing I wanted to add is the management of crypted passwords. If you wish to import the accounts from another server and have no the list of passwords in plan text you should use the switch

$params = array('_ispconfig_pw_crypted' => 1, 'password' =>'$1$asdasd ....

in the params.
 

By: bilbo_uk

Thanks for this HowTo.

It might be worth mentioning that the

$soap_location = 'http://localhost:8080/remote/index.php';
$soap_uri = 'http://localhost:8080/remote/';

must be the location of your ISPConfig3 server. So if you have moved the service to a different port then that is the port you must put here. (Also note it is not the apps-vhost port!)

Similarly if you have (as you should) secured your ISPConfig3 service with SSL then the protocol must be set to 'https'.

So if, for example, you are running ISPConfig3 on

https://mydomain.com:10000/index.php

then your soap params become

$soap_location = 'https://localhost:10000/remote/index.php';
$soap_uri = 'https://localhost:10000/remote/';

Probably obvious to most people but it wasn't to me! (I'm new to SOAP), and the

"You should also put in your soap?location and uri, but more than likely you will not have to change this." 

didn't really help me with any clues to what to enter :-(

Thanks

By: Franzcc

For all of those, who were tired of testing the API and not using php, i got it working with Perls SOAP::Lite Library.

It was quite a pain, read a lot of source, so enjoy the anwser and start to code:

That is a democode to create a website:

#!/usr/bin/env perluse strict;use warnings;#use SOAP::Lite +trace => 'all';use SOAP::Lite;$SOAP::Constants::PREFIX_ENV = "SOAP-ENV";my $params = {};$params->{server_id} = 1;$params->{ip_address} = '*';$params->{domain} = 'apitestdomain.com';$params->{type} = 'vhost';$params->{parent_domain_id} = 0;$params->{vhost_type} = 'name';$params->{hd_quota} = 100000;$params->{traffic_quota} = -1;$params->{cgi} = 'y';$params->{ssi} = 'y';$params->{suexec} = 'y';$params->{errordocs} = 1;$params->{is_subdomainwww} = 1;$params->{php} = 'php-fpm';$params->{stats_type} = 'webalizer';$params->{allow_override} = 'All';$params->{pm_max_requests} = 0;$params->{pm_process_idle_timeout} = 10;$params->{active} = 'y';$params->{traffic_quota_lock} = 'n';$params->{pm_max_children} = 10;$params->{pm_start_servers} = 2;$params->{pm_min_spare_servers} = 1;$params->{pm_max_spare_servers} = 5;$params->{pm_max_requests} = 0;$params->{php_fpm_use_socket} = 'y';my $options = {};$options->{location} = 'https://www.apihost.com:8080/remote/index.php';$options->{uri} = 'https://www.apihost.com:8080/remote/';my $username = 'api';my $password = 'xxxxxxxxxxxxxxxxx';my $client_id = 1;my $client = SOAP::Lite->new(proxy => $options->{location}, %{$options});my $session = $client->call("login", $username, $password);die $session->faultstring if ($session->fault);my $site = $client->call('sites_web_domain_add',    SOAP::Data->name('param0')->value($session->result)->type('string'),    SOAP::Data->name('param1')->value($client_id)->type('int'),    SOAP::Data->name('param2')->value($params)->type('map'),    SOAP::Data->name('param3')->value('false')->type('boolean'));die $site->faultstring if ($site->fault);printf("Site created successfully. ID: %d\n", $site->result);my $logout = $client->call('logout', $session->result);die $logout->faultstring if ($logout->fault);

By: till

Since ISPConfig 3.1, you can also use the REST api which returns the results in json format.

 

Examples:

 

Add a DNS zone:

 

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"session_id": "5b5034d3c2e54d79cd641fe53f3cf3d2","client_id": "1","params": {"server_id": 1,"origin": "example.com.","ns": "ns1.example.com.","mbox": "admin.example.com.","serial": 2016090601,"retry": 540, "refresh": 80, "expire": 604800, "minimum": 3600, "ttl": 604800, "xfer": "", "also_notify": "", "update_acl": "", "active": "Y"}}' "https://192.168.1.100:8080/remote/json.php?dns_zone_add" -k

 

Add a database user:

 

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"session_id": "5b5034d3c2e54d79cd641fe53f3cf3d2","client_id": "1","params": {"server_id": 1,"database_user": "c1testdbuser","database_user_prefix": "c1","database_password": "pwdtestdbuser"}}' "https://192.168.1.100:8080/remote/json.php?sites_database_user_add" -k

 

Add a database:

 

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"session_id": "5b5034d3c2e54d79cd641fe53f3cf3d2","client_id": "1","params": {"server_id": 1,"parent_domain_id": 2,"type": "MySQL","database_name": "rest","database_name_prefix": "c1","database_quota": 0, "database_user_id": 7, "database_ro_user_id": 0, "database_charset": "", "remote_access": "n", "active": "y", "remote_ips": ""}}' "https://192.168.1.100:8080/remote/json.php?sites_database_add" -k

By: Harald

In various contexts, the UI allows to filter based on certain values, e.g. finding all email forwards for a specific destination email address.

Is there a function to do this via the REST API? The only method I was able to find is

    public function mail_forward_get($session_id, $primary_id)    {        global $app;        if(!$this->checkPerm($session_id, 'mail_forward_get')) {            throw new SoapFault('permission_denied', 'You do not have the permissions to access this function.');            return false;        }        $app->uses('remoting_lib');        $app->remoting_lib->loadFormDef('../mail/form/mail_forward.tform.php');        return $app->remoting_lib->getDataRecord($primary_id);    }

but there I already have to pass the primary_id of the forwarder :(

Any ideas?

By: helmo

See also the examples and docs on https://git.ispconfig.org/ispconfig/ispconfig3/-/tree/master/remoting_client

By: Urban Thinking

This URL gives a 404 :-/

By: Gwyneth Llewelyn

Try this one instead: https://git.ispconfig.org/ispconfig/ispconfig3/-/tree/develop/remoting_client/ — there seems to have been some branch name rewriting.