REST API For managing the Artica system

The RESTful API allows you to perform system tasks using RESTful commands. (THE REST API SERVICE IS AVAILABLE WITH ENTERPRISE EDITION).

The RESTful API allows you to perform system tasks using RESTful commands.
(The REST API service is available with Enterprise Edition).

This feature has been developed for versions 4.x, 4.30x.
Although still present, this feature is no longer maintained and has been replaced by the Web API service present by default in version 4.50x.

Install the System RESTful service.

On the “Your system” and “Features”, search RESTful term.
Install the feature “System API RESTful”

After installing the RESTful feature, display or edit the REST API KEY in the “YourSystem” and Restful section.

This REST API Key can be used to allow query/set all RESTful API section (LDAP database, proxy, categories…)

Use the API

If the RESTful API is enabled for the Proxy service, you can use these commands to manage the “No cache section”

The RESTFul api needs to add the ArticaKey: API Key in the HTTP request header

$ch = curl_init();

$CURLOPT_HTTPHEADER[]="Accept: application/json";
$CURLOPT_HTTPHEADER[]="Pragma: no-cache,must-revalidate";
$CURLOPT_HTTPHEADER[]="Cache-Control: no-cache,must revalidate";
$CURLOPT_HTTPHEADER[]="Expect:";
$CURLOPT_HTTPHEADER[]="ArticaKey: TaR9uMaMBKo10gGlvta89hcqNdYKXmP1";
$MAIN_URI="https://192.168.1.1:9000/api/rest/system/info";

curl_setopt($ch, CURLOPT_HTTPHEADER, $CURLOPT_HTTPHEADER);
curl_setopt($ch, CURLOPT_TIMEOUT, 300);
curl_setopt($ch, CURLOPT_URL, $MAIN_URI);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch,CURLOPT_SSL_VERIFYHOST,0);
curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,0);

$response = curl_exec($ch);
$errno=curl_errno($ch);
if($errno>0){
echo "Error $errno\n".curl_error($ch)."\n$response\n";
curl_close($ch);
die();
}

$CURLINFO_HTTP_CODE=intval(curl_getinfo($ch,CURLINFO_HTTP_CODE));

if($CURLINFO_HTTP_CODE<>200){
echo "Error $CURLINFO_HTTP_CODE\n";
die();
}

$json=json_decode($response);
if(!$json->status){echo "Failed $json->message\n";die();}
echo "Success\n";

foreach ($json->results as $index=>$line){
echo "[$index]: {$line->items}, ({$line->ztype})\n";
}

System information

GET https://192.168.1.1:9000/api/rest/system/info

Produce an array of system information such as CPU percentage, Memory percentage, memory info, hardware info…

Status of all services

GET https://192.168.1.1:9000/api/rest/system/monitor/status

Produce a json array of each monitored service ( see “results” attribute )

Example with REST Client

system-rest --monitor --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Reload the watchdog service

GET https://192.168.1.1:9000/api/rest/system/monitor/reload

Example with REST Client

system-rest --monitor reload --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Active emergency modes.

Available in 4.30 with Service Pack 58 or above

GET https://192.168.1.1:9000/api/rest/system/monitor/emergencies

Currently, Artica have 14 emergency modes:

SquidUrgency: Global emergency mode for the proxy service
SquidUFDBUrgency: Emergency mode of the Web-filtering service.
MacToUidUrgency: Emergency mode of the translate extension: Mac To member and site name to category.
DynamicACLUrgency: Emergency on the Dynamic ACLs extension.
SquidSSLUrgency: Emergency on the SSL decrypt engine.
SizeQuotasCheckerEmergency: Emergency on the user quotas engine.
LogsWarninStop: Emergency on the logs system.
StoreIDUrgency: Emergency on the HyperCache feature.
ActiveDirectoryEmergency: Emergency on the Active Directory connection.
SquidUrgencyCaches: Emergency on the proxy system cache.
SquidMimeEmergency: Emergency on the MIME rules ACLs.
BasicAuthenticatorEmergency: Emergency on the basic authenticator extension.
DisableAnyCache: Mode do not cache.
SquidHotSpotUrgency: Emergency en the HotSpot feature.

The API return an array of

count: The number of active emergencies modes. 0 means no emergency
emergencies: The list of active emergencies modes ( see the list ) separated by a comma.

Example with REST Client

system-rest --monitor emergencies--hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Enable/Disable Active Directory emergency mode.

Available in 4.30 with Service Pack 58 or above

GET https://192.168.1.1:9000/api/rest/system/emergencies/activedirectory/(on|off|join)

The join token try to re-establish an Active Directory session (NTLM mode only)

Example with REST Client

system-rest --emergencies activedirectory on --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

system-rest --emergencies activedirectory off --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

system-rest --emergencies activedirectory join--hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Reboot the system

GET https://192.168.1.1:9000/api/rest/system/reboot

Provide a smooth reboot of the machine.

Artica Version

GET https://192.168.1.1:9000/api/rest/system/articaver

Return an array with following keys:

status=true/false.
message=full description of the version
version=The main version of Artica
ServicePack=version of Artica Service Pack ( available with 4.30 Service Pack 58 or above )
hostname=Hostname of the server.

Update Artica

Enable/disable update trough Rsync

GET https://192.168.1.1:9000/api/rest/system/rsync-update/[enable]/[server]/[port]

Where [enable] is 0 or 1, [server]: server address of the Artica server Rsync and [port]: Rsync port of the Artica server Rsync.

Launch Artica update (get method)

GET https://192.168.1.1:9000/api/rest/system/artica-update

Patch/Update Artica (upload method)

POST https://192.168.1.1:9000/api/rest/system

You have to post the following fields:

Patch-artica: yes

File_contents: file content to upload

Example:

$cFile = curl_file_create($filepath);

$post = array('patch-artica' => 'yes','file_contents'=> $cFile);

An example can be found on /usr/share/artica-postfix/exec.rest.system.php

This example can be used as rest-system tool

For example, to patch or update a remote artica server :

system-rest --patch /root/artica-4.05.092801.tgz --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Install a Debian package

GET https://192.168.1.1:9000/api/rest/system/debpkg/[package]

Where [package] is the Debian package name to install locally.

Manage Groups privileges (Active Directory )

This API let you Add members groups into the privileges area for Artica Web console access.

Available in 4.30 with Service Pack 58 or above

List Group privileges:

GET https://192.168.1.1:9000/api/rest/system/privs

return an array of tokens:

supported: list of all supported privileges.

privileges: array of privileges with the ID of the element, the full DN of the Active Directory Group and PRIVS listed privileges separated with a comma**.**

Example with REST Client

system-rest --privs --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Remove a Group privileges

GET https://192.168.1.1:9000/api/rest/system/privs/remove/[ID]

Where ID is the ID of the element specified with the List Group privileges API

Example with REST Client

system-rest --privs remove 1 --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Add/Edit privileges:

GET https://192.168.1.1:9000/api/rest/system/privs/[DN]/[privileges]

Where DN is the full Active Directory LDAP DN and privileges is a list of privileges separated with a comma

Example:

GET https://192.168.1.1:9000/api/rest/system/privs/CN=Administrators,CN=Builtin,DC=articatech,DC=lab/AllowAddUsers,AllowAddGroup,AsWebStatisticsAdministrator,AsArticaAdministrator,AsFirewallManager

Example with REST Client

system-rest --privs "CN=Administrators,CN=Builtin,DC=articatech,DC=lab" "AllowAddUsers,AllowAddGroup,AsWebStatisticsAdministrator,AsArticaAdministrator,AsFirewallManager" --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

License

Get license information

GET https://192.168.1.1:9000/api/rest/system/license

Return a json with the following values:

license_status: Enterpise, gold or Community

2. company: registered company

3. expire: Expiration in day

4. expire_in: text explain when to expire

Example with REST Client

rest-system --license --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Upload a gold license

A gold license is a special license that allows to install unlimited servers in an unlimited time.

The gold license did not require any Internet connection.

GET https://192.168.1.1:9000/api/rest/system/license/gold/XXXXX9-46XXX7-4558X9-XXXX9X

Where “XXXXX9-46XXX7-4558X9-XXXX9X” is the license serial sent by your partner.

Example with REST Client

system-rest –-gold XXXXX9-46XXX7-4558X9-XXXX9X --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Network

Change a network interface parameter

POST https://192.168.1.1:9000/api/rest/system/interface/[ifname]

Where [ifname] is the interface name

Example:

$ch = curl_init();
$CURLOPT_HTTPHEADER[]="Accept: application/json";
$CURLOPT_HTTPHEADER[]="Pragma: no-cache,must-revalidate";
$CURLOPT_HTTPHEADER[]="Cache-Control: no-cache,must revalidate";
$CURLOPT_HTTPHEADER[]="Expect:";
$CURLOPT_HTTPHEADER[]="ArticaKey: kyM6ixXavn8sE7P9GoBYgX3by6ZaRCc5";

//Change the Interface settings of eth0

$MAIN_URI="https://192.168.1.173:9000/api/rest/system/interface/eth0";

curl_setopt($ch, CURLOPT_HTTPHEADER, $CURLOPT_HTTPHEADER);
curl_setopt($ch, CURLOPT_TIMEOUT, 300);
curl_setopt($ch, CURLOPT_URL, $MAIN_URI);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch,CURLOPT_SSL_VERIFYHOST,0);
curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,0);

$POSTz= array(
"IPADDR"=>"192.168.1.23",
"NETMASK"=>"255.255.255.0",
"GATEWAY"=>"192.168.1.1"
"BROADCAST"=>"192.168.1.255",
"METRIC"=>"1",
"DEFAULT_ROUTE"=>"1");

curl_setopt($ch, CURLOPT_POSTFIELDS, $POSTz);

$response = curl_exec($ch);
$errno=curl_errno($ch);
if($errno>0)

}

$CURLINFO_HTTP_CODE=intval(curl_getinfo($ch,CURLINFO_HTTP_CODE));

if($CURLINFO_HTTP_CODE<>200)

}

$json=json_decode($response);
if(!$json->status){echo "Failed $json->message\n";die();}
echo "Success\n";

Apply network configuration to the system

GET https://192.168.1.1:9000/api/rest/system/interface/reconfigure

Change the server hostname

GET https://192.168.1.1:9000/api/rest/system/hostname/srvprox01.acme.corp

Manage hosts file.

Updating the host file update automatically entries in the DNS cache service.

Search in hosts table

GET https://192.168.1.1:9000/api/rest/system/hosts/search/[pattern]

Where [pattern] is a string to find in host table.(if no pattern set, dump all hosts from the table).

Return a json with hostname, IP address, and aliases.

Example with REST Client, search *serv1* pattern

system-rest --hosts search serv1 --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Add entry in hosts table

GET https://192.168.1.1:9000/api/rest/system/hosts/add/[ip]/[hostname]/[alias]

Where ip is the TCP/IP address, hostname is the full qualified hostname and alias is the alias of the hostname (usually the NetBIOS name)

Example with REST Client, add serv1.domain.tld with ip address 192.168.1.23

rest-system --hosts add 192.168.1.23 serv1.domain.tld serv1 --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

Delete an entry on hosts table

GET https://192.168.1.1:9000/api/rest/system/hosts/del/[key]

Where key is the entry “key” as md5 format of the row to delete

Example with REST Client, delete entry with key dc04c4d53fcae0dde8e9c1770a6f9b98

system-rest --hosts del dc04c4d53fcae0dde8e9c1770a6f9b98 --hostname=192.168.1.152:9000 --key=l7TkK6M6crhvsKe9AMxqvSBLn3bCpjMq

System Swap

List all swap spaces

GET https://192.168.1.1:9000/api/rest/system/swap/list

Return a json with all swap spaces details.

Create a new swap space

POST https://192.168.1.1:9000/api/rest/system/swap/new

With POST values:

path=directory where to store swap file.
size=size in MB of the swap space.

Delete a swap space

POST https://192.168.1.1:9000/api/rest/system/swap/delete

With post values

path=full path where the swap file is stored.

Clean all swap spaces

GET https://192.168.1.1:9000/api/rest/system/swap/clean

This action will reset the swap to 0

Features

The RESTful API of the features section allows you to query available features and order ARTICA to install/uninstall features.

Get the list of available features:

GET https://192.168.1.1:9000/api/rest/system/features/list

Return a json with “features” keys

The “features” keys are array of features in this way:

$json=json_decode($response);

if(!$json->status){echo "Failed $json->message\n";die();}

echo "Success\n";

$features=$json->features

// $KEY_FEATURE will be used to install/uninstall the feature

foreach($features as $KEY_FEATURE=>$infos)

}

Install a feature

GET https://192.168.1.1:9000/api/rest/system/features/install/$KEY

$KEY is the main key found in the feature list, for example to install the proxy service:

GET https://192.168.1.1:9000/api/rest/system/features/install/proxy_service

Or via system-rest (example to install the SNMP service on a remote Artica server)

system-rest --features install APP_SNMPD --key=rMG0ELGrcinJVueHkSkdri6sp0vC8Elf --host=192.168.1.58:9000

Return a status code 200 if the command is accepted and executed

Uninstall a feature

GET https://192.168.1.1:9000/api/rest/system/features/uninstall/$KEY

$KEY is the main key found in the feature list, for example to uninstall the proxy service:

GET https://192.168.1.1:9000/api/rest/system/features/uninstall/proxy_service

Or via system-rest on a remote Artica server ( uninstall the SNMP feature)

system-rest --features remove APP_SNMPD --key=rMG0ELGrcinJVueHkSkdri6sp0vC8Elf --host=192.168.1.58:9000

Return a status code 200 if the command is accepted and executed

SNMP Service

GET https://192.168.1.1:9000/api/rest/system/snmp/status

system-rest --snmp

Provide 2 arrays in the returned json:

1. Info: provide service status

2. params: Current settings and available tokens to modify

in Info, the toke SNMPWALK set if the service is open and respond correctly.

Each parameter inside “params” can be retrieved or defined.

Example: to retrieve the parameter “interface” for the listen interface :

GET https://192.168.1.1:9000/api/rest/system/snmp/interface

system-rest –-snmp interface

To define a parameter add the parameter to change in the url

example

https://192.168.1.1:9000/api/rest/system/snmp/interface /eth1

system-rest –-snmp interface eth1

Force using only snmpv3

To force use SNMPV3 instead SNMP V1/v2, turn the parameter disable_v2 to 1

example

https://192.168.1.1:9000/api/rest/system/snmp/disable_v2/1

system-rest –-snmp interface disable_v2 1

Statistics

Increase/decrease Statistics retention time

Get the current value

GET https://192.168.1.1:9000/api/rest/system/statistics/retention/days

Set the value

GET https://192.168.1.1:9000/api/rest/system/statistics/retention/days/[value]

Where [value] is a number of days.