powerdns-cli

PowerDNS-CLI is a cli to interact with the PowerDNS Authoritative Nameserver. PowerDNS itself does only offer an API to interact with remotely and its pdns_util does only work on the PowerDNS-Host, not from another machine.

Installation

Installation is available through pypi.org:

pip install powerdns-cli

Or as an oci container:
podman run --rm -it ghcr.io/IamLunchbox/powerdns-cli:latest powerdns-cli

To manually install the package from git, checkout the repository and run pip install . in the git repository.

Configuration

powerdns-cli uses keyword-based actions. Flags may only follow after the last action keyword.
To get things going, for example, add a zone:
$ powerdns-cli zone add -a MyApiKey -u http://localhost example.com PRIMARY

All flags may alternatively be provided as environment variables. Each option must be prefixed with POWERDNS_CLI_ and the settings title in upper case. For example:

$ export POWERDNS_CLI_APIKEY="MyApiKey"
$ export POWERDNS_CLI_URL="http://localhost"
$ powerdns-cli zone add example.com PRIMARY

It is also possible to set the common configuration options in ./.powerdns-cli.conf, $HOME/.powerdns-cli.conf or $HOME/.config/powerdns-cli/configuration.toml. The file format is toml, strings will need to be quoted explicitly. This is the required structure and their defaults, the option keys are not case sensitive:

apikey = "mytestkey" # default is None
api-version = 4 # default is None
debug = false
insecure = false
json = false
server-id = "localhost"
timeout = 5
url = "http://example.com" # default is None

Only these settings can be accessed through the configuration file.

Depending on the context, for example editing records, further options may be available. Instead of the flag, the corresponding env variable may be used. All options reside under POWERDNS_CLI_*. To set the TTL through the environment of record add, use export POWERDNS_CLI_TTL=60.

Features

• Access to all API-Endpoints PowerDNS Auth exposes.
• CLI configuration through flags, environment variables or a configuration file.
• Exporting and importing data in JSON.
• Exporting RRSets in BIND.
• Idempotence.
• "Builtin" access to the current api-specification.

Usage

Usage: powerdns-cli [OPTIONS] COMMAND [ARGS]...

  Manage PowerDNS Authoritative Nameservers and their Zones/Records.

Options:
  -h, --help  Show this message and exit.

Commands:
  autoprimary  Change autoprimaries, which may modify this server.
  config       Show servers and their configuration
  cryptokey    Manage DNSSEC-Keys.
  metadata     Configure zone metadata.
  network      Set up networks views.
  record       Edit resource records (RRSets) of a zone.
  tsigkey      Set up server wide TSIGKeys, to sign transfer messages.
  version      Show the powerdns-cli version
  view         Configure views, which limit zone access based on IPs.
  zone         Manage zones and their configuration.

Refer to each action and its help page to find out more about each function.

Examples

# Add a zone
$ powerdns-cli zone add example.org. native
Successfully created example.org.

# Add some records
$ powerdns-cli record add www example.org A 127.0.0.1
www.example.org. A 127.0.0.1 created.

$ powerdns-cli record add @ example.org MX "10 mail.example.org."
example.org. MX 10 mail.example.org. created.

# Import example.com from integration test
$ cat ./integration/import-zone.json | powerdns-cli zone import - 
Successfully added example.com..

# Delete zone, skipping confirmation
$ powerdns-cli zone delete example.com -f
Successfully deleted example.com..

If something goes wrong or does not work, the -j-switch provides more verbose output as json:

$ powerdns-cli record add  @ example.org MX "10 mail.test.de"  -j
[...]
        {
            "request": {
                "method": "PATCH",
                "url": "http://localhost:8082/api/v1/servers/localhost/zones/example.org."
            },
            "response": {
                "status_code": 422,
                "reason": "Unprocessable Entity",
                "json": {
                    "error": "Record example.org./MX '10 mail.test.de': Not in expected format (parsed as '10 mail.test.de.')"
                },
                "text": ""
            }
        }
    ],
    "data": null,
    "success": false,
    "message": "Failed to create example.org. MX 10 mail.test.de."
}

The integration test uses all common cli options to test for api compatibility.

Scripting

• message and success are guaranteed to be set.
• message is emitted on stdout. It contains human readable output, except:
• If an action requests data, as do list and export, it resides in data. Otherwise, data is null.
• If an action requests data, message == data - so stdout will emit data as well.

Caveats

1. It is not possible to simply create a RRSet with several entries. Instead, powerdns-cli record add needs to be used repeatedly.
2. Use record replace to ensure a RRSet has only a single value.
3. There are no guardrails for removing records from a zone, only for removing a zone altogether.

Version Support

All the PowerDNS authoritative nameserver versions, which receive patches / security updates, are covered by integration tests. Suported versions are documented here. Therefore, PowerDNS Authoritative Nameserver versions 4.8+ are part of the testing right now.

If the PowerDNS-Team does not apply releases and changes to their publicly released docker images (see here), they won't be covered by the integration tests.