NAME¶

desec - a simple deSEC.io API client

SYNOPSIS¶

desec [global-options] action [action-options]

DESCRIPTION¶

desec is a command-line client to manage domains hosted by deSEC.io using the deSEC.io API. It supports domain management, DNS record management, authentication token and token policy management, import and export of records in zone file and JSON format, and generation of TLSA records from certificate files. It also handles the API's rate limits and pagination transparently.

The functionality is split into subcommands (referred to as actions). Each action takes its own set of options; run desec action --help for details on a specific action.

GLOBAL OPTIONS¶

These options apply to desec itself and must be given before the action.

-h, --help

Show a help message and exit.

-V, --version

Show the program's version number and exit.

--token TOKEN

API authentication token. Defaults to the value of the DESEC_TOKEN environment variable. Mutually exclusive with --token-file.

--token-file TOKEN_FILE

File containing the API authentication token. The file may also be a script that prints the API authentication token to stdout. Scripts are distinguished from plain files by the executable permission bit on the file system. Defaults to $XDG_CONFIG_HOME/desec/token. Mutually exclusive with --token.

--non-blocking

When the API's rate limit is reached, return an appropriate error instead of waiting.

--blocking

When the API's rate limit is reached, wait and retry the request. This is the default behaviour.

--debug-http

Print details about HTTP requests and responses.

AUTHENTICATION¶

The deSEC API requires a token for authentication, which can be created on the deSEC.io website or through the API using an existing token. The token is looked up from the following sources, in order of decreasing precedence:

1.

The --token argument.

2.

The DESEC_TOKEN environment variable.

3.

The file given by the --token-file argument.

4.

The file $XDG_CONFIG_HOME/desec/token.

TOKEN MANAGEMENT ACTIONS¶

list-tokens

List all authentication tokens.

create-token [options]

Create and return a new authentication token. Options:

modify-token id [options]

Modify the existing authentication token id. Options:

delete-token id

Delete the authentication token id.

TOKEN POLICY ACTIONS¶

list-token-policies id

List all policies of the authentication token id.

add-token-policy id [options]

Add a policy for the authentication token id. Options:

modify-token-policy token_id policy_id [options]

Modify the existing policy policy_id of the authentication token token_id. Options:

delete-token-policy token_id policy_id

Delete the policy policy_id of the authentication token token_id.

DOMAIN ACTIONS¶

list-domains

List all registered domains.

domain-info domain

Get information about domain.

new-domain domain

Create the new domain domain.

delete-domain domain

Delete domain.

RECORD ACTIONS¶

The following options are common to several record actions:

get-records domain [-t TYPE] [-s SUBNAME]

List all records of domain, optionally restricted to a record type and/or subname.

add-record domain -t TYPE -r RECORD... [-s SUBNAME] [--ttl TTL]

Add a record set to domain. -t and -r are required.

change-record domain -t TYPE [-r RECORD...] [-s SUBNAME] [--ttl TTL]

Change an existing record set of domain. -t is required.

update-record domain -t TYPE -r RECORD... [-s SUBNAME] [--ttl TTL]

Add entries, possibly to an existing record set of domain. -t and -r are required.

delete-record domain -t TYPE [-r RECORD...] [-s SUBNAME]

Delete a record set of domain. -t is required. If no records are given with -r, all records of the given type and subname are deleted.

TLSA ACTIONS¶

These actions require the optional cryptography dependency.

add-tlsa domain -p PORT... -c CERT [options]

Add a TLSA record for an X.509 certificate (DANE), keeping any existing records.

set-tlsa domain -p PORT... -c CERT [options]

Set the TLSA record for an X.509 certificate (DANE), removing any existing records for the same port, protocol and subname.

Options for add-tlsa and set-tlsa:

IMPORT AND EXPORT ACTIONS¶

export domain -f FILE

Export all records of domain into FILE in JSON format.

export-zone domain -f FILE

Export all records of domain into FILE in zone file format.

import domain -f FILE [--clear]

Import records for domain from the JSON file FILE. With --clear, remove all existing records before import.

import-zone domain -f FILE [--clear] [-d]

Import records for domain from the zone file FILE. Requires the optional dnspython dependency. With --clear, remove all existing records before import. With -d, --dry-run, just parse the zone data without writing it to the API.

RECORD TYPES¶

The -t / --type option accepts the following DNS record types:

A, AAAA, AFSDB, APL, CAA, CDNSKEY, CDS, CERT, CNAME, DHCID, DNAME, DNSKEY,
DLV, DS, EUI48, EUI64, HINFO, HTTPS, KX, L32, L64, LOC, LP, MX, NAPTR, NID,
NS, OPENPGPKEY, PTR, RP, SMIMEA, SPF, SRV, SSHFP, SVCB, TLSA, TXT, URI

ENVIRONMENT¶

DESEC_TOKEN

API authentication token, used when --token is not given.

XDG_CONFIG_HOME

Base directory for the default token file location. Defaults to ~/.config if unset.

FILES¶

$XDG_CONFIG_HOME/desec/token

Default file from which the API token is read when neither --token nor DESEC_TOKEN is set.

EXIT STATUS¶

Returns 0 on success. On error, a message is printed and a non-zero, error-specific exit code is returned.

EXAMPLES¶

List all registered domains:

Add an A record:

Export a domain to a zone file:

SEE ALSO¶

Project home page: https://github.com/s-hamann/desec-dns

deSEC.io API documentation: https://desec.readthedocs.io/

AUTHOR¶

Written by desec-dns contributors.