Skip to content

API

Jump to bottom
Petr Bena edited this page Aug 13, 2020 · 12 revisions

API documentation can be found simply by opening /api.php in your browser

In order to enable api, you need to edit your config file and put $g_api_enabled = true;

Some API allow GET method, but most of them need be sent via POST, here are some examples using curl

Cookies must be operational for user sessions to work. --insecure option is useful in case you are using self-signed or untrusted certificate.

Login

curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=login_token&token=test'  -c cookies -b cookies
{
    "result": "success"
}

Tokens

DNS tool supports login concept of tokens. These are shared secrets that are known by user and server, working in similar way to TSIG keys. User provides the secret to authenticate themselves. These secrets are stored in $g_api_tokens and can be used in $g_auth_roles_map instead of username in order to map roles to them. It's generally not recommended to use tokens for production systems as the security provided by them is very weak and because they have to be stored in plain text in configuration files.

Tokens can also contain underscore as username separator, so that if you create a token username_secretstring you will only see "username" as name of user in audit logs, hiding the secret part of token.

Check if you are logged in

curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=is_logged' -c cookies -b cookies
{
    "is_logged": true,
    "user": "test",
    "role": "root"
}

List available zones

curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=list_zones' -c cookies -b cookies

Manipulating DNS records

Display all records in a zone

curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=list_records&zone=domain.org' -c cookies -b cookies

Display single record

curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=get_record&record=test.domain.org' -c cookies -b cookies

Create a new record

In versions older than 1.6 you had to explicitly specify which zone you want to work in, since 1.6 this parameter is optional and if not provided, DNS tool will automatically lookup the name of correct zone from its configuration. You can still provide zone name in case that you want to modify records in parent zone, that are hidden by subzone (for example when you create a subzone and you need to delete all subzone records in parent zone).

curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=create_record&zone=domain.org&record=test&ttl=1&type=A&value=1.2.3.4' -c cookies -b cookies
Since version 1.6.0 you can also do this:
curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=create_record&record=test.domain.org&ttl=1&type=A&value=1.2.3.4' -c cookies -b cookies

Delete a record

When deleting a record, you need to provide all the details (value, TTL, etc.) - because it's possible to have multiple records with same name. Running delete with nsupdate without specifying all details would delete unspecified / random (probably first) record only from DNS server.

For that reason you have to explicitly specify all details.

curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=delete_record&record=test.domain.org&ttl=1&type=A&value=1.2.3.4' -c cookies -b cookies
Since version 1.6.0 parameter zone doesn't need to be specified, you can provide record in form of FQDN instead

Replace a record

Unlike calling 2 separate calls to delete and create a record, you can take advantage of replace_record in order to perform change in a single nsupdate transaction - that way you can ensure that there will be no moment of record absence. This is a recommended way to change DNS records and it behaves identically to "edit record" function available in UI

To replace a record you must provide its current FQDN (or key + zone), type, TTL and new value. All other values are optional, for example if you want to rename the key, you don't have to provide the value (provided there is only 1 unique key, not multiple same keys, for example used in round-robin setup), or if you want to replace the value, you don't need to provide new key name, as it remains the same.

When changing record you can change following:

  • Key name (within same zone - cross-zone operations are not supported, for that you have to use 2 individual API calls)
  • Record type
  • Record TTL
  • Record value

You can also request to automatically modify associated PTR records, this option only works if new or old (or both) types of record are A records.

curl -X POST --insecure 'https://your-server/dns/api.php' -d 'action=replace_record&record=test.domain.org&ttl=1&type=A&new_value=0.0.0.0&ptr=true' -c cookies -b cookies
Clone this wiki locally