Metadata-Version: 2.4
Name: powerdns-cli
Version: 1.2.3
Summary: PowerDNS Authoritative API client
Author-email: Raphael Grieger <r.grieger@hotmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/IamLunchbox/powerdns-cli
Project-URL: Issues, https://github.com/IamLunchbox/powerdns-cli/issues
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.3.0
Requires-Dist: click>=8.3.0
Requires-Dist: platformdirs>=4.5.0
Requires-Dist: tomli>=2.3.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: tox; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: tomli; extra == "dev"
Dynamic: license-file

[![PyPi version](https://badgen.net/pypi/v/powerdns-cli/)](ttps://pypi.org/project/powerdns-cli/)
[![GitHub latest commit](https://badgen.net/github/last-commit/IamLunchbox/powerdns-cli)](https://github.com/IamLunchbox/powerdns-cli/commits)
![Tests](https://github.com/IamLunchbox/powerdns-cli/actions/workflows/tests.yml/badge.svg)

# powerdns-cli
PowerDNS-CLI is a cli to interact with the
[PowerDNS Authoritative Nameserver](https://doc.powerdns.com/authoritative/). 
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:

```shell
$ 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:  

```toml
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
```shell
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

```shell
# 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:
```shell
$ 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](https://github.com/IamLunchbox/powerdns-cli/blob/main/.github/workflows/tests.yml) 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](https://doc.powerdns.com/authoritative/appendices/EOL.html).
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](https://hub.docker.com/r/powerdns/)), they
won't be covered by the integration tests.
