CLI e strumenti per sviluppatori

Installazione

La CLI NexDNS è un singolo binario senza dipendenze esterne. Scelga il metodo di installazione più adatto al Suo ambiente.

Script di installazione

curl -sL https://get.nexdns.tech/cli | sh

Rileva la tua piattaforma, scarica l’archivio della versione corrispondente, lo verifica con i checksum pubblicati insieme alla release e installa il binario in /usr/local/bin. Leggilo prima con curl https://get.nexdns.tech/cli se preferisci non passare a una shell uno script non letto.

Installare con Go

go install github.com/nexdns/cli/cmd/nexdns@latest

Homebrew

brew tap nexdns/tap
brew install --cask nexdns-cli

La formula è pubblicata come cask, quindi si installa con <code>--cask</code> anziché con la forma su una riga <code>brew install</code>.

Scaricare un archivio della release

I binari precompilati per Linux, macOS e Windows (amd64 e arm64) sono allegati a ogni release su GitHub. Estrai l’archivio e copia nexdns in una directory del tuo PATH.

Docker

docker pull nexdns/cli

Verifica dell’installazione

Dopo l’installazione, verifichi che la CLI sia disponibile e controlli la versione:

nexdns version

Autenticazione

La CLI richiede un token API per comunicare con l’API NexDNS. È possibile creare un token su nexdns.tech/settings/api-keys.

Requisito del piano: la CLI funziona tramite la REST API e richiede quindi una chiave API, disponibile dal piano Pro in su. Lo stesso vale per il provider Terraform, il provider OctoDNS e i plugin ACME.

Salvataggio del token nella configurazione

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Variabile d’ambiente (CI/CD)

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxx

Verifica dello stato di autenticazione

nexdns auth status

File di configurazione

Il token viene memorizzato in ~/.nexdns/config.yaml. La CLI risolve le credenziali nel seguente ordine di priorità:

1. --token flag (priorità più alta)
2. Variabile d’ambiente NEXDNS_TOKEN
3. File di configurazione ~/.nexdns/config.yaml

Gestione delle zone

Gestione delle zone DNS dalla riga di comando. Tutti i comandi per le zone sono sotto il sottocomando nexdns zone.

Elencare le zone

L’elenco è paginato. Utilizzare --all per scorrere tutte le pagine, oppure --search, --page e --per-page per restringerlo.

nexdns zone list
nexdns zone list --all
nexdns zone list --search example --per-page 50

Aggiungere una zona

nexdns zone add example.com --ns-group eu

Per creare una zona secondaria che si trasferisce dal proprio server primario, indicare --type slave con l’indirizzo IP pubblico del primario. Le zone secondarie sono disponibili dal piano Pro in su.

nexdns zone add example.com --type slave --master-ip 203.0.113.10

Informazioni sulla zona

nexdns zone info example.com

Esportare una zona

Esporta la zona nel formato del file di zona BIND, pronto da reindirizzare in un file. Con --format json si ottiene invece un inventario leggibile dalle macchine.

nexdns zone export example.com > example.com.zone
nexdns zone export example.com --format json

Importare un file di zona

Utilizzare --dry-run per visualizzare le modifiche prima di applicarle:

nexdns zone import example.com zone.txt --dry-run
nexdns zone import example.com zone.txt

Per impostazione predefinita un’importazione aggiunge soltanto ciò che manca. Con --replace vengono eliminati anche i record che il file non definisce, così la zona corrisponde esattamente al file. I record dei server dei nomi e il record SOA della zona non vengono mai toccati.

nexdns zone import example.com zone.txt --replace

Garantire l’esistenza della zona

Crea la zona solo se non esiste già (idempotente):

nexdns zone ensure example.com

Spostare una zona in un altro gruppo di server dei nomi

Sposta la zona in un altro gruppo di server dei nomi, indicato tramite il suo slug. La zona continua a rispondere per tutta la durata dell’operazione: i server dei nomi del nuovo gruppo vengono predisposti prima che il comando termini e i precedenti continuano a servire le query mentre i resolver si aggiornano. Successivamente va aggiornata la delega presso il registrar: nexdns zone info stampa i nuovi server dei nomi.

nexdns zone move example.com eu --dry-run
nexdns zone move example.com eu

Una zona può essere spostata tre volte al giorno. Oltre quel limite il comando segnala il limite e non modifica nulla.

Verificare la propagazione DNS

Interroga direttamente i resolver pubblici, non l’API, quindi mostra ciò che vede Internet. Esce con un codice diverso da zero quando un controllo non va a buon fine, il che lo rende utilizzabile come controllo bloccante in fase di rilascio.

nexdns zone check example.com

Eliminare una zona

Chiede prima una conferma. Negli script si aggiunge --force per saltare la richiesta; in assenza di un terminale la richiesta viene rifiutata automaticamente e non viene eliminato nulla.

nexdns zone delete example.com
nexdns zone delete example.com --force

Gestione dei record

Gestione dei record DNS all’interno di una zona. Tutti i comandi per i record sono sotto il sottocomando nexdns record.

Elencare i record

Per filtrare si usano --type, --name (un’etichetta, oppure @ per l’apice della zona) o --search, che cerca nei nomi e nei contenuti.

nexdns record list example.com
nexdns record list example.com --type MX
nexdns record list example.com --name www
nexdns record list example.com --search 203.0.113

Aggiungere record

L’argomento content contiene solo il valore principale. Tutto il resto di cui un tipo di record ha bisogno – priorità, peso, porta, tag e flag CAA, parametri DS e TLSA – è un flag separato, quindi non serve assemblare nulla a mano.

# A record
nexdns record add example.com A www 1.2.3.4 --ttl 300

# MX record with priority
nexdns record add example.com MX @ mail.example.com --priority 10

# SRV: priority, weight and port are separate flags
nexdns record add example.com SRV _sip._tcp sip.example.com --priority 10 --weight 60 --port 5060

# CAA: the value is the CA domain, the rest are flags
nexdns record add example.com CAA @ letsencrypt.org --tag issue --flags 0

# DS and TLSA: content is the bare hex digest
nexdns record add example.com DS child 0123456789abcdef --keytag 12345 --algorithm 13 --digest-type 2
nexdns record add example.com TLSA _443._tcp.www 0123456789abcdef --usage 3 --selector 1 --matching-type 1

Il TTL si applica all’intero set di record. Omettendo --ttl quando si aggiunge un altro valore a un nome già esistente, si mantiene il TTL corrente; indicandolo, il nuovo TTL viene applicato a tutti i valori presenti su quel nome. Per un nome del tutto nuovo il valore predefinito è 3600 secondi.

Aggiornare un record

Permette di modificare il contenuto, il TTL, la priorità o l’etichetta. Gli ID dei record derivano dal record stesso, quindi una modifica restituisce un nuovo ID: va sempre riletto dalla risposta invece di riutilizzare quello precedente.

nexdns record update example.com <record-id> --content 5.6.7.8
nexdns record update example.com <record-id> --ttl 600
nexdns record update example.com <record-id> --record-name api

Creare il record se mancante

Crea il record solo se non esiste già (corrispondenza esatta di tipo, nome e contenuto). I record esistenti con contenuto diverso non vengono modificati – sicuro per le configurazioni round-robin. Idempotente:

nexdns record ensure example.com A www 1.2.3.4

Eliminare un record

nexdns record delete example.com <record-id>

DNSSEC

Gestione della firma DNSSEC per le zone.

Controllare lo stato DNSSEC

nexdns dnssec status example.com

Abilitare DNSSEC

nexdns dnssec enable example.com

Ottenere i record DS

Recuperare i record DS per configurarli presso il registrar del dominio:

nexdns dnssec ds-records example.com

Disabilitare DNSSEC

Richiede una conferma: disabilitare la firma su una zona delegata interrompe la validazione fino a quando il record DS non viene ritirato presso il registrar. Negli script si aggiunge --force.

nexdns dnssec disable example.com --force

DNS come codice

Definisca la Sua infrastruttura DNS in modo dichiarativo in un file nexdns.yaml e la gestisca con il controllo di versione. La CLI confronta la configurazione locale con lo stato live e applica solo le modifiche necessarie.

Formato della configurazione

zones:
  example.com:
    dnssec: true
    records:
      - type: A
        name: "@"
        content: "1.2.3.4"
        ttl: 300
      - type: CNAME
        name: www
        content: example.com

Anteprima delle modifiche

Mostra un diff di ciò che cambierebbe senza applicare nulla:

nexdns apply

Applicare le modifiche

Applica le modifiche dopo aver esaminato il diff:

nexdns apply --confirm

Solo diff

nexdns diff

Rimuovere i record eliminati dal file

Un record rimosso da nexdns.yaml resta al suo posto, a meno che le eliminazioni non vengano richieste esplicitamente. È una scelta voluta: evita che un file incompleto svuoti una zona. Con --delete il file diventa la fonte di verità.

nexdns diff --delete
nexdns apply --confirm --delete

Scegliere il file e la zona

Utilizzare --file per una configurazione esterna alla directory di lavoro e --zone per agire su una singola zona di un file che ne contiene più di una. Un --zone che non corrisponde a nessuna zona del file è un errore, non un’operazione ignorata in silenzio.

nexdns apply --file production.yaml --zone example.com --confirm

Estrarre lo stato live

Genera un nexdns.yaml dalla configurazione DNS live corrente:

nexdns pull example.com
nexdns pull example.com --file nexdns.yaml
nexdns pull other.example --file nexdns.yaml --append

Sostituzione delle variabili d’ambiente

Utilizzi la sintassi ${VARIABLE} nel file di configurazione. La CLI sostituisce le variabili d’ambiente al momento dell’applicazione, rendendo facile riutilizzare le configurazioni tra ambienti diversi:

zones:
  ${DOMAIN}:
    records:
      - type: A
        name: "@"
        content: "${SERVER_IP}"

Webhooks

Consente di iscrivere un endpoint agli eventi generati dalle Sue zone e di gestire quelle iscrizioni dal terminale. I webhook sono disponibili dal piano Pro in su; la chiave API deve avere i permessi webhooks.read e webhooks.write.

Iscrivere un endpoint

Il secret di firma viene mostrato una sola volta, alla creazione, e non può essere recuperato in seguito: va conservato dove il servizio ricevente possa leggerlo. Ogni consegna include una firma HMAC calcolata con quel secret, così il servizio ricevente può verificare che la richiesta arrivi davvero da noi.

nexdns webhook create https://example.com/hooks/dns \
    --events zone.created,zone.deleted,record.created \
    --description "production"

Eventi disponibili

zone.created, zone.updated, zone.deleted, record.created, record.updated, record.deleted, dnssec.enabled, dnssec.disabled, zone.health.problem, zone.health.resolved

Esaminare le iscrizioni

show aggiunge i dieci tentativi di consegna più recenti con il relativo codice di stato e, in caso di errore, il messaggio corrispondente – di solito è quanto basta per distinguere un URL sbagliato da un servizio ricevente che rifiuta il payload.

nexdns webhook list
nexdns webhook show <webhook-id>

Inviare un evento di test

Mette in coda una consegna di test. Un esito positivo qui significa che la piattaforma ha accettato l’evento, non che il Suo endpoint abbia risposto: l’esito effettivo si legge con nexdns webhook show.

nexdns webhook test <webhook-id>

Modificare o sospendere un’iscrizione

Va indicato solo ciò che cambia: il comando legge l’iscrizione corrente e reinvia il resto. Con --active=false le consegne si interrompono senza eliminare l’endpoint; con --force l’eliminazione avviene senza richiesta di conferma.

nexdns webhook update <webhook-id> --events zone.created,dnssec.enabled
nexdns webhook update <webhook-id> --active=false
nexdns webhook delete <webhook-id> --force

Account e configurazione

Permette di verificare a quale account appartiene un token, quale piano vi è associato e quali chiavi API esistono.

nexdns account info
nexdns account api-keys

Impostazioni salvate

Il file di configurazione contiene cinque impostazioni – api-url, token, output, color e timeout – e tutte possono essere lette e scritte dalla CLI. config view stampa la configurazione effettiva, indicando anche da dove proviene il token.

nexdns config view
nexdns config set output json
nexdns config set timeout 60
nexdns config get api-url

Variabili d’ambiente

Ogni impostazione ha anche una variabile d’ambiente, che è la via normalmente usata dai runner CI. NEXDNS_CONFIG punta a un file di configurazione alternativo, comodo quando da una sola macchina si gestiscono più account.

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export NEXDNS_API_URL=https://api.nexdns.tech/v1
export NEXDNS_TIMEOUT=60
export NEXDNS_CONFIG=/etc/nexdns/config.yaml

Rimuovere un token salvato

Rimuove il token dal file di configurazione. Il file stesso, e l’eventuale URL dell’API salvato al suo interno, restano invariati.

nexdns auth logout

Completamento nella shell

Gli script di completamento vengono generati per bash, zsh, fish e PowerShell.

nexdns completion bash > /etc/bash_completion.d/nexdns
nexdns completion zsh > "${fpath[1]}/_nexdns"

Scripting e CI

La CLI è pensata per essere guidata dalle pipeline: ogni errore ha un proprio codice di uscita, le richieste di conferma rispondono con un rifiuto invece di bloccarsi e nessuna operazione distruttiva avviene senza essere richiesta esplicitamente.

Codici di uscita

Un sottocomando digitato male esce con 2 invece di stampare la guida e terminare con successo, così un errore di battitura in una pipeline non può passare per un’operazione completata.

Richieste di conferma

I comandi distruttivi chiedono conferma prima di agire. In assenza di un terminale – cioè in qualsiasi runner CI – la richiesta viene rifiutata e il comando esce con 0 senza aver modificato nulla: quando l’operazione è voluta, va passato --force.

Errori che prima passavano inosservati

• Un ${VAR} non risolto in nexdns.yaml interrompe l’esecuzione ed elenca tutte le variabili rimaste senza valore, invece di scrivere il testo letterale in un record.
• Un --zone che non corrisponde a nessuna zona del file è un errore.
• zone check esce con un codice diverso da zero quando un controllo di propagazione non va a buon fine.
• apply --confirm esce con un codice diverso da zero quando una qualsiasi operazione è fallita e indica quante.

Limitazione delle richieste e operazioni di massa

Il budget dell’API è per account e per piano, in una finestra scorrevole di un minuto. La CLI legge il budget da ogni risposta e, prima di superarlo, attende che la finestra si azzeri: così un’importazione di grandi dimensioni si completa integralmente invece di perdere record, semplicemente impiegando più tempo. Un limite con una finestra più lunga, come il numero di volte in cui una zona può cambiare gruppo di server dei nomi, viene segnalato anziché atteso.

Docker

La CLI è disponibile come immagine Docker. Inserire il token API tramite la variabile d’ambiente NEXDNS_TOKEN.

Eseguire comandi

docker run --rm -e NEXDNS_TOKEN=nxd_xxx nexdns/cli zone list

Importare un file di zona

Montare una directory locale per passare i file di zona al container:

docker run --rm -e NEXDNS_TOKEN=nxd_xxx \
    -v "$PWD/zones:/zones" \
    nexdns/cli zone import example.com /zones/example.com.zone

Flag globali

I seguenti flag sono disponibili su tutti i comandi:

Ciascuno di questi flag legge anche una variabile d’ambiente: NEXDNS_TOKEN, NEXDNS_API_URL, NEXDNS_TIMEOUT e NEXDNS_CONFIG. NO_COLOR disattiva i colori indipendentemente da --color.

Terraform

Il provider Terraform NexDNS consente di gestire zone e record come risorse Terraform. Installare il provider dal Terraform Registry e configurarlo con il token API.

terraform {
  required_providers {
    nexdns = {
      source = "nexdns/nexdns"
    }
  }
}

provider "nexdns" {
  api_token = var.nexdns_token
}

resource "nexdns_zone" "main" {
  name     = "example.com"
  ns_group = "eu"
}

resource "nexdns_record" "www" {
  zone_id = nexdns_zone.main.id
  type    = "A"
  name    = "www"
  content = "1.2.3.4"
}

DNSControl

DNSControl è uno strumento DNS-as-code di Stack Overflow. Utilizzare il provider NexDNS per gestire le zone in modo dichiarativo. Il provider è incluso in DNSControl dalla versione 4.46.0.

creds.json

{
    "nexdns": {
        "TYPE": "NEXDNS",
        "api_token": "nxd_xxxxxxxxxxxxxxxxxxxx"
    }
}

dnsconfig.js

var REG_NONE = NewRegistrar("none");
var DSP_NEXDNS = NewDnsProvider("nexdns");

D("example.com", REG_NONE, DnsProvider(DSP_NEXDNS),
    A("@", "1.2.3.4"),
    A("www", "1.2.3.4"),
    MX("@", 10, "mail.example.com."),
    CNAME("blog", "example.com.")
);

OctoDNS

OctoDNS è uno strumento DNS-as-code di GitHub. Installare il provider NexDNS e configurarlo come sorgente o destinazione nella configurazione OctoDNS.

Installare il provider

pip install octodns-nexdns

File config/production.yaml

providers:
  config:
    class: octodns.provider.yaml.YamlProvider
    directory: ./config
  nexdns:
    class: octodns_nexdns.NexdnsProvider
    token: env/NEXDNS_API_TOKEN

zones:
  example.com.:
    sources:
      - config
    targets:
      - nexdns

File zones/example.com.yaml

"":
  type: A
  value: 1.2.3.4
www:
  type: A
  value: 1.2.3.4
blog:
  type: CNAME
  value: example.com.