Auto Light Dark
Auto Light Dark
Breadcrumbs

API Module - Admin and Audit

Admin and Audit

This section covers the functions found under the Admin section of ProVision.

ProVision's APIv1 system has been replaced by APIv2, and is now considered deprecated. 

Authentication Testing

testSSH

URL

/api/v1/api.php?target=auth&action=testSSH

Description

Returns success or failure of a connection to an external server via SSH.

Returns

Examples:

SUCCESSFUL

{"success":1,"message":"Success!"}

ERROR

{'success':0, 'message':'error message'}

Required Parameters

Name

Type

Example

Description

SSHServer

STRING

totally.awesome.com

IP or FQDN of server.

SSHPort

NUMBER

22

Port ssh is running on.

Optional Parameters

Name

Type

Example

Description

username

STRING

jsmith

Username on target server.

password

STRING

password123

Password for user.

directory

STRING

 /tmp

Directory to attempt to access after successful login.





Example URL

/api/v1/api.php?target=auth&action=testSSH&username=jsmith&password=password123&directory=%2Fvar%2Fnamed%2Fexample%2Fqa4&SSHPort=22&SSHServer=myssh.awesome.com

testLDAP

URL

/api/v1/api.php?target=auth&action=testLDAP

Description

Test basic connectivity to an LDAP server. Does not test actual authenticaion against server.

Returns

Examples:
SUCCESSFUL: {'success':1, 'id':'12345'}
ERROR: {'success':0, 'message':'unable to add block'}>

Required Parameters

Name

Type

Example

Description

ldapServer

STRING

ldap.awesome.com

IP or FQDN of the LDAP server.

ldapPort

NUMBER

 389

User-defined block code as defined in Admin-IPAM settings: Generic Code Per Block Name

ldapMode

STRING

 SSL

Options are: SSL, TLS, or None.

Optional Parameters

None

Example URL

/api/v1/api.php?target=auth&action=testLDAP&ldapPort=389&ldapServer=ldap.awesome.com&ldapMode=None

 

testSecure64

URL

/api/v1/api.php?target=auth&action=testSecure64

Description

Returns success or failure of a connection to an Secure64 DNS appliance.

Returns

Examples:

SUCCESSFUL

{"success":1,"message":"Success!"}

ERROR

{'success':0, 'message':'error message'}

Required Parameters

Name

Type

Example

Description

SSHServer

STRING

totally.awesome.com

IP or FQDN of server.

SSHPort

NUMBER

22

Port ssh is running on.

Optional Parameters

Name

Type

Example

Description

username

STRING

jsmith

Username on target server.

password

STRING

password123

Password for user.

directory

STRING

 /tmp

Directory to attempt to access after successful login.





Example URL

/api/v1/api.php?target=auth&action=testSecure64&username=jsmith&password=password123&directory=%2Fvar%2Fnamed%2Fexample%2Fqa4&SSHPort=22

Backup

backup now

URL

/api/v1/api.php?target=backup&action=now

Description

Performs a manual backup to the designated location.

Returns

Examples:
SUCCESSFUL: {"success":1,"message":"Backup via curl complete: "}
ERROR: {"success":0, "message":"Error Message"}>

Required Parameters

Name

Type

Example

Description

type

STRING

curl

File transfer type. Acceptable values are 'curl' or 'scp'

Optional Parameters

Name

Type

Example

Description

resource

INTEGER

2213

The server resource id to backup to. If left blank, backs up to the cloud.

Example URL

Backup to designated server: /api/v1/api.php?target=backup&action=now&type=scp&resource_id=2213

Backup to cloud: /api/v1/api.php?target=backup&action=now&type=curl

When specifying a backup server resource ID, that server must have the Hostname, Username, and Password fields correctly provided in ProVision. 


Log Management

Get

URL

/api/v1/api.php?target=log&action=get

Description

Returns a list of log entries. Use optional parameters to filter the list.

Returns

Examples:

SUCCESSFUL

{"success":1,"message":"Search Successful.","data":[{"logId":"31568","time": "2012-05-07 17:44:43", "logLevel":"INFO","userId":"39","userName": "user@example.com","logCategory": "User","message": "User Doe (user@example.com) logged in via local authentication","ip":"107.111.0.228"}]}

ERROR

{'success':0, 'message':'error message'}


Data Detail

Name

Type

Example

Description

log_id

INTEGER

24

Unique log entry id.

time

DATETIME

2012-05-07 22:10:07

Date and time year to second.

log_level

STRING

NOTICE

Standard syslog log levels in verbose format (EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, DEBUG).

user_id

INTEGER

11

The unique user id associated with the log entry.

username

STRING

user@example.com

The unique user name associated with the log entry.

log_category

STRING

IPAM

The ProVision category for the log entry (User, IPAM, Resource Holder, DNS, Peering, Assistant, NTP, Reporting).

message

STRING

Created new children from 1.0.0.0/24

The detailed log message.

ip

STRING

107.111.0.228

The remote IP address of the user who took the action being logged.

Required Parameters

None*

*There are no required parameters, but at least one optional parameter must be provided for the call to succeed.

Optional Parameters

Name

Type

Example

Description

block_id

INTEGER

310

Id of the IPAM netblocks to which the logs belong

get_attributes

BOOLEAN

1

Display the log attributes along with the log into the client's response. (The attributes for each log record). Valid values are 1 (true) and 0 (false).

log_id

INTEGER

24

Unique log entry id.

time_min

DATETIME

2015-05-07 [21:00:00]

Retrieve logs starting at this Date and optional time year to second.

time_max

DATETIME

2015-05-07 [22:00:00]

Retrieve logs ending at this Date and optional time year to second.

limit

INTEGER

100

Total log entries to retrieve. Default limit is 1000 records.

orderby

STRING

log_id

Order results by log_id, time, log_level

order

STRING

ASC

Order by ascending / descending (ASC / DESC).

offset

INTEGER

50

Offset from 0 to retrieve log entries

username

STRING

user@example.com

The unique user name associated with the log entry.

log_category

STRING

IPAM

The ProVision category for the log entry (User, IPAM, Resource Holder, DNS, Peering, Assistant, NTP, Reporting).

log_level

STRING

NOTICE

Standard syslog log levels in verbose format (EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, DEBUG).

ip

STRING

1.2.3.4

The remote IP address of the user whose action was logged

search

STRING

Aggregate Added

Search for a string in the logs. It searches in 'message', 'username', 'time', 'ip' and 'log_category'

time

DATETIME

2015-05-07 [21:00:00]

Search logs from a specific time.

Example URL

/api/v1/api.php?target=log&action=get&block_id=310&order_by=log_id&order=DESC

 Scheduler

addTask

URL

/api/v1/api.php?target=scheduler&action=addTask

Description

Add a new scheduled task. Request is POST-only. Params are a single JSON object:

Returns

Examples:
SUCCESSFUL: {"success":1,"message":"Message "}
ERROR: {"success":0, "message":"Error Message"}>

Required Parameters

Name

Type

Example

Description

user_id

INTEGER

100

User ID

name

STRING

Process Holding Tank

Name given to the new

class_name

STRING

\scheduler\Tasks\ProcessHoldingTask

PHP-namespaced name for the task class.

Currently available:

 \scheduler\Tasks\ProcessHoldingTask

 \scheduler\Tasks\BackupTask

 \scheduler\Tasks\DNSPushTask

data


{}


active

BOOL

true


repeat_items




Optional Parameters

Name

Type

Example

Description

repeat_start

STRING

2015-05-06

Date to start repeating task. Date must be in YYYY-MM-DD format.

repeat_end

STRING

null

Date to end repeating task or null. Date must be in YYYY-MM-DD format.

repeat_hour

INTEGER

8

Hour of day to repeat, from 0-23

repeat_minute

INTEGER

0

Minute of that hour to repeat, from 0-59

repeat_day

INTEGER

1

Day of month, from 1-31

repeat_week

INTEGER

1

Week of month, from 1-5

repeat_weekday

INTEGER

1

Days to repeat. Sun-Sat are from 0-6 respectively



updateTask

URL

/api/v1/api.php?target=scheduler&action=updateTask

Description

Update a scheduler task

Returns

Examples:
SUCCESSFUL: {"success":1,"message":"Message"}
ERROR: {"success":0, "message":"Error Message"}>

Required Parameters

Name

Type

Example

Description

id

INTEGER

4

ID of the task to be updated

user_id

INTEGER

100

User ID

name

STRING

Process Holding Tank

Name given to the new

class_name

STRING

\scheduler\Tasks\ProcessHoldingTask

PHP-namespaced name for the task class.

Currently available:

 \scheduler\Tasks\ProcessHoldingTask

 \scheduler\Tasks\BackupTask

 \scheduler\Tasks\DNSPushTask

data


{}


active

BOOL

true


repeat_items




Optional Parameters

Name

Type

Example

Description

repeat_start

STRING

2015-05-06

Date to start repeating task. Date must be in YYYY-MM-DD format.

repeat_end

STRING

null

Date to end repeating task or null. Date must be in YYYY-MM-DD format.

repeat_hour

INTEGER

8

Hour of day to repeat, from 0-23

repeat_minute

INTEGER

0

Minute of that hour to repeat, from 0-59

repeat_day

INTEGER

1

Day of month, from 1-31

repeat_week

INTEGER

1

Week of month, from 1-5

repeat_weekday

INTEGER

1

Days to repeat. Sun-Sat are from 0-6 respectively


deleteTask

URL

/api/v1/api.php?target=scheduler&action=deleteTask

Description

Delete a scheduler task

Returns

Examples:
SUCCESSFUL: {"success":1,"message":"Task \"New Task\" (2) deleted","data":null}
ERROR: {"success":0, "message":"Error Message"}>

Required Parameters

Name

Type

Example

Description

taskId

INTEGER

4

ID of the task to delete

Optional Parameters

None

Example URL

/api/v1/api.php?target=scheduler&action=deleteTask&taskId=2


executeTask

URL

/api/v1/api.php?target=scheduler&action=executeTask

Description

Execute a task immediately

Returns

Examples:
SUCCESSFUL: {"success":1,"message":"Holding tank processed. 0 IPv4 and 0 IPv6 blocks moved to the available pool. ","data":null}
ERROR: {"success":0, "message":"Error Message"}>

Required Parameters

Name

Type

Example

Description

taskId

INTEGER

4

ID of the task to run

Optional Parameters

None

Example URL

/api/v1/api.php?target=scheduler&action=executeTask&taskId=1


getTaskHistory

URL

/api/v1/api.php?target=scheduler&action=getTaskHistory

Description

Get history for a specific task

Returns

Examples:
SUCCESSFUL: { "success": 1, "data": [ { "log_id": "1005037", "time": "2015-05-07 12:29:45", "log_level": "6", "user_id": "31", "username": "usernamehere", "log_category": "System", "message": "task_id=1 task=Process Holding Tank action=finished message=Holding tank processed. 0 IPv4 and 0 IPv6 blocks moved to the available pool.", "ip": null }, { "log_id": "1005033", "time": "2015-05-07 12:28:50", "log_level": "6", "user_id": "31", "username": "usernamehere", "log_category": "System", "message": "task_id=1 task=Process Holding Tank action=finished message=Holding tank processed. 1 IPv4 and 0 IPv6 blocks moved to the available pool.", "ip": null }, { "log_id": "1005030", "time": "2015-05-07 12:28:14", "log_level": "6", "user_id": "31", "username": "usernamehere", "log_category": "System", "message": "Task \"Process Holding Tank\" (1) added", "ip": null } ] }
ERROR: {"success":0, "message":"Error Message"}>

Required Parameters

Name

Type

Example

Description

taskId

INTEGER

1

ID of the task to view

Optional Parameters

None

Example URL

/api/v1/api.php?target=scheduler&action=getTaskHistory&taskId=1


getTasks

URL

/api/v1/api.php?target=scheduler&action=getTasks

Description

Gets a list of scheduled tasks and their repeat settings

Returns

Examples:
SUCCESSFUL: { "success": 1, "data": [ { "id": "1", "user_id": "31", "name": "Process Holding Tank", "class_name": "\\scheduler\\Tasks\\ProcessHoldingTask", "active": true, "data": null, "last_run": "2015-05-07 12:29:45", "repeat_items": [ { "id": "1", "task_id": "1", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "4", "repeat_hour": "20", "repeat_minute": "0" }, { "id": "2", "task_id": "1", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "5", "repeat_hour": "20", "repeat_minute": "0" }, { "id": "3", "task_id": "1", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "6", "repeat_hour": "20", "repeat_minute": "0" }, { "id": "4", "task_id": "1", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "0", "repeat_hour": "20", "repeat_minute": "0" } ] }, { "id": "2", "user_id": "31", "name": "New Task", "class_name": "\\scheduler\\Tasks\\TestTask", "active": true, "data": null, "last_run": "2015-05-07 12:35:41", "repeat_items": [ { "id": "5", "task_id": "2", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "1", "repeat_hour": "21", "repeat_minute": "0" }, { "id": "6", "task_id": "2", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "2", "repeat_hour": "21", "repeat_minute": "0" }, { "id": "7", "task_id": "2", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "3", "repeat_hour": "21", "repeat_minute": "0" }, { "id": "8", "task_id": "2", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "4", "repeat_hour": "21", "repeat_minute": "0" }, { "id": "9", "task_id": "2", "repeat_start": "2015-05-06", "repeat_end": null, "repeat_interval": null, "repeat_year": "*", "repeat_month": "*", "repeat_day": "*", "repeat_week": "*", "repeat_weekday": "5", "repeat_hour": "21", "repeat_minute": "0" } ] } ] }

 
ERROR: {"success":0, "message":"Error Message"}>

Required Parameters

None

Optional Parameters

None

Example URL

/api/v1/api.php?target=scheduler&action=getTasks

Zone Templates

Get

URL

/api/v1/api.php?target=zoneTemplate&action=get

Description

Returns success or failure of a connection to an external server via SSH.

Returns

Examples:

SUCCESSFUL

{"success":1,"message":"Found 1 records for template \"Awesome Template\".","data":{"templateId":"1011","name":"Awesome Template","created":"2013-07-31 14:01:24","modified":"2013-07-31 14:01:24","userId":"112","soa":null,"refresh":"14400","retry":"3600","expire":"604800","minimum":null,"ttl":null,"userName":"joe@smith.com","records":[{"templateRecordId":"4","templateId":"1011","host":"www","type":"A","ttl":"3600","value":"1.2.3.4","ordering":"0"}]}}

ERROR

{'success':0, 'message':'error message'}

Required Parameters

None

Optional Parameters

Name

Type

Example

Description

templateId

NUMBER

3

ID of the specific template to get.





Example URL

/api/v1/api.php?target=zoneTemplate&action=get

 

Update

URL

/api/v1/api.php?target=zoneTemplate&action=update

Description

Create a new template or update an existing template.

Returns

Examples:
SUCCESSFUL: {"success":1,"message":"Template updated","data":{"templateId":"1011","name":"Awesome Template","created":"2013-08-05 23:15:52","modified":"2013-08-05 23:15:52","userId":"112","soa":"ns1.test.net hostmaster.ns1.test.net","refresh":"14400","retry":"3600","expire":"604800","minimum":null,"ttl":false,"userName":"anna@example.com","records":"1"}}
ERROR: {'success':0, 'message':'Error updating template: error details'}>

Required Parameters

Name

Type

Example

Description

name

STRING

Test Template

The name of the template to be created or updated.





Optional Parameters

Name

Type

Example

Description

soa

STRING

ns1.test.net hostmaster.ns1.test.net

A valid SOA for the template in for format

ttl

 INTEGER

 86400

 The TTL for the zone template, which is the default expiration time for all records without their own TTL.

refresh

 INTEGER

 14400

 The time period for slaves to refresh the zone.

retry

 INTEGER

 3600

 Time that a slave should retry refreshing the zone in case of incident.

expire

 INTEGER

604800

 Time for a slave to expire a zone.

mininum

 INTEGER

 3600

 The maximum caching time in the event of failed lookups.

count_records

INTEGER

5

Number of host records submitted with the update. All the following parameters names should be followed with their position in the count. In this example, the first record would have all the parameters for the first record followed by _1, the second record _2, and so on. This will be the order all records in the template follow.

host_1

STRING


The DNS record value.

ttl_1

INTEGER

3600

TTL of the specific host record.

type_1

STRING

A

A valid DNS record type.

value_1

IP

1.2.3.4

A valid IPv4 or IPv6 address.

Example URL

api/v1/api.php?target=zoneTemplate&action=update&templateId=1011&count_records=1&name=Awesome+Template&soa=ns1.test.net+hostmaster.ns1.test.net

&refresh=14400&retry=3600&expire=604800&minimum=3600&value_0=undefined+undefined&host_1=www&ttl_1=3600&type_1=A&value_1=1.2.3.4

 

Delete

URL

/api/v1/api.php?target=zoneTemplate&action=delete

Description

Deletes a DNS template.

Returns

Examples:

SUCCESSFUL

{"success":1,"message":"Template \"Test Template\" delete."}

ERROR

{"success":0,"message":"No template found for templateId \"1005\"."}

Required Parameters

Name

Type

Example

Description

templateId

INTEGER

3

ID of the template to delete.

Optional Parameters

None.

Example URL

/api/v1/api.php?target=zoneTemplate&action=delete&templateId=1005