CLI et outils pour développeurs

Installation du CLI

Le CLI NexDNS est un binaire unique sans dépendances externes. Choisissez la méthode d’installation adaptée à votre environnement.

Script d’installation

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

Détecte votre plateforme, télécharge l’archive de version correspondante, la vérifie avec les sommes de contrôle publiées avec la version et installe le binaire dans /usr/local/bin. Lisez-le d’abord avec curl https://get.nexdns.tech/cli si vous préférez ne pas transmettre à un shell un script non lu.

Installer avec Go

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

Homebrew

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

La formule est publiée sous forme de cask : elle s’installe donc avec <code>--cask</code> et non avec la forme en une ligne <code>brew install</code>.

Télécharger une archive de release

Des binaires précompilés pour Linux, macOS et Windows (amd64 et arm64) sont joints à chaque release sur GitHub. Décompressez l’archive et placez nexdns dans un répertoire de votre PATH.

Docker

docker pull nexdns/cli

Vérifier l’installation

Après l’installation, confirmez que le CLI est disponible et vérifiez sa version :

nexdns version

Authentification

Le CLI nécessite un token API pour communiquer avec l’API NexDNS. Vous pouvez créer un token sur nexdns.tech/settings/api-keys.

Exigence du plan : le CLI passe par l’API REST et nécessite donc une clé API, disponible à partir du plan Pro. Il en va de même pour le provider Terraform, le provider OctoDNS et les plugins ACME.

Enregistrer le token dans la configuration

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Variable d’environnement (CI/CD)

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxx

Vérifier le statut d’authentification

nexdns auth status

Fichier de configuration

Le token est stocké dans ~/.nexdns/config.yaml. Le CLI résout les identifiants dans l’ordre de priorité suivant :

1. --token (priorité la plus élevée)
2. Variable d’environnement NEXDNS_TOKEN
3. Fichier de configuration ~/.nexdns/config.yaml

Gestion des zones

Gérez les zones DNS en ligne de commande. Toutes les commandes de zone sont sous la sous-commande nexdns zone.

Lister les zones

La liste est paginée. Utilisez --all pour parcourir toutes les pages, ou --search, --page et --per-page pour la restreindre.

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

Ajouter une zone

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

Pour créer une zone secondaire qui se transfère depuis votre propre serveur primaire, passez --type slave avec l’adresse IP publique du primaire. Les zones secondaires sont disponibles à partir du plan Pro.

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

Informations sur la zone

nexdns zone info example.com

Exporter une zone

Exporte la zone au format fichier de zone BIND, prêt à être redirigé vers un fichier. Passez --format json pour obtenir à la place un inventaire exploitable par une machine.

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

Importer un fichier de zone

Utilisez --dry-run pour prévisualiser les modifications avant de les appliquer :

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

Par défaut, un import n’ajoute que ce qui manque. Ajoutez --replace pour supprimer également les enregistrements que le fichier ne définit pas : la zone correspond alors exactement au fichier. Les enregistrements de serveurs de noms et l’enregistrement SOA propres à la zone ne sont jamais modifiés.

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

Garantir l’existence d’une zone

Crée la zone uniquement si elle n’existe pas déjà (idempotent) :

nexdns zone ensure example.com

Déplacer une zone vers un autre groupe de serveurs de noms

Déplace la zone vers un autre groupe de serveurs de noms, désigné par son slug. La zone continue de répondre pendant toute l’opération : les serveurs de noms du nouveau groupe sont provisionnés avant que la commande ne rende la main, et les anciens continuent de servir pendant que les résolveurs se mettent à jour. Mettez ensuite à jour la délégation auprès de votre bureau d’enregistrement – nexdns zone info affiche les nouveaux serveurs de noms.

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

Une zone peut être déplacée trois fois par jour. Au-delà, la commande signale la limite et ne modifie rien.

Vérifier la propagation DNS

Interroge directement les résolveurs publics – et non l’API – vous voyez donc ce que voit Internet. La commande se termine avec un code de sortie non nul lorsqu’une vérification échoue, ce qui permet de s’en servir comme point de contrôle de déploiement.

nexdns zone check example.com

Supprimer une zone

Demande d’abord une confirmation. Ajoutez --force pour ignorer l’invite dans un script ; sans terminal, l’invite se solde automatiquement par un refus et rien n’est supprimé.

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

Gestion des enregistrements

Gérez les enregistrements DNS au sein d’une zone. Toutes les commandes d’enregistrement sont sous la sous-commande nexdns record.

Lister les enregistrements

Filtrez avec --type, --name (un label, ou @ pour l’apex de la zone) ou --search, qui porte sur les noms et le contenu.

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

Ajouter des enregistrements

L’argument content ne porte que la valeur principale. Tout le reste dont un type d’enregistrement a besoin – priorité, poids, port, tag et flags CAA, paramètres DS et TLSA – passe par une option distincte : rien n’est à assembler à la main.

# 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

Le TTL s’applique à l’ensemble d’enregistrements. Omettez --ttl lorsque vous ajoutez une valeur à un nom qui existe déjà : le TTL en place est conservé. Si vous le passez, il s’applique à toutes les valeurs portant ce nom. Pour un nom entièrement nouveau, la valeur par défaut est de 3600 secondes.

Mettre à jour un enregistrement

Modifiez le contenu, le TTL, la priorité ou le label. Les identifiants d’enregistrement sont dérivés de l’enregistrement lui-même : une modification renvoie donc un nouvel identifiant – relisez-le toujours dans la réponse plutôt que de réutiliser l’ancien.

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

Créer l’enregistrement s’il est absent

Crée l’enregistrement uniquement s’il n’existe pas déjà (correspondance exacte du type, du nom et du contenu). Les enregistrements existants au contenu différent ne sont pas modifiés – sûr pour les configurations round-robin. Idempotent :

nexdns record ensure example.com A www 1.2.3.4

Supprimer un enregistrement

nexdns record delete example.com <record-id>

DNSSEC

Gérez la signature DNSSEC de vos zones.

Vérifier le statut DNSSEC

nexdns dnssec status example.com

Activer DNSSEC

nexdns dnssec enable example.com

Obtenir les enregistrements DS

Récupérez les enregistrements DS à configurer auprès de votre bureau d’enregistrement de domaine :

nexdns dnssec ds-records example.com

Désactiver DNSSEC

Demande une confirmation : désactiver la signature d’une zone déléguée rompt la validation jusqu’au retrait de l’enregistrement DS auprès de votre bureau d’enregistrement. Ajoutez --force dans un script.

nexdns dnssec disable example.com --force

DNS en tant que code

Définissez votre infrastructure DNS de manière déclarative dans un fichier nexdns.yaml et gérez-la avec le contrôle de version. Le CLI compare votre configuration locale à l’état actuel et n’applique que les modifications nécessaires.

Format de configuration

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

Prévisualiser les modifications

Afficher un diff de ce qui changerait sans rien appliquer :

nexdns apply

Appliquer les modifications

Appliquer les modifications après avoir examiné le diff :

nexdns apply --confirm

Diff uniquement

nexdns diff

Supprimer les enregistrements retirés du fichier

Un enregistrement supprimé de nexdns.yaml est conservé en place tant que vous ne demandez pas explicitement les suppressions. C’est volontaire : cela évite qu’un fichier partiel vide une zone. Ajoutez --delete pour que le fichier fasse foi.

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

Choisir le fichier et la zone

Utilisez --file pour une configuration située hors du répertoire de travail, et --zone pour n’agir que sur une seule zone d’un fichier multi-zones. Un --zone qui ne désigne aucune zone du fichier est une erreur, pas une opération silencieusement ignorée.

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

Récupérer l’état actuel

Générer un nexdns.yaml à partir de la configuration DNS actuelle :

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

Substitution de variables d’environnement

Utilisez la syntaxe ${VARIABLE} dans votre fichier de configuration. Le CLI substitue les variables d’environnement au moment de l’application, ce qui facilite la réutilisation des configurations entre les environnements :

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

Webhooks

Abonnez un point de terminaison aux événements émis par vos zones et gérez ces abonnements depuis le terminal. Les webhooks sont disponibles à partir du plan Pro ; la clé API doit porter les portées webhooks.read et webhooks.write.

Abonner un point de terminaison

Le secret de signature n’est affiché qu’une fois, à la création, et ne peut pas être récupéré ensuite – stockez-le là où votre récepteur pourra le lire. Chaque livraison porte une signature HMAC calculée avec ce secret, ce qui permet au récepteur de vérifier que la requête vient bien de nous.

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

Événements disponibles

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

Inspecter les abonnements

show ajoute les dix tentatives de livraison les plus récentes, avec leur code de statut et, en cas d’échec, l’erreur – ce qui suffit généralement à distinguer une URL erronée d’un récepteur qui rejette la charge utile.

nexdns webhook list
nexdns webhook show <webhook-id>

Envoyer un événement de test

Met en file d’attente une livraison de test. Un succès signifie ici que la plateforme a accepté l’événement, pas que votre point de terminaison a répondu – relisez le résultat avec nexdns webhook show.

nexdns webhook test <webhook-id>

Modifier ou suspendre un abonnement

Ne passez que ce qui change ; la commande lit l’abonnement courant et renvoie le reste. Utilisez --active=false pour arrêter les livraisons sans supprimer le point de terminaison, et --force pour supprimer sans invite de confirmation.

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

Compte et configuration

Vérifiez à quel compte appartient un token, quel plan lui est associé et quelles clés API existent.

nexdns account info
nexdns account api-keys

Paramètres enregistrés

Le fichier de configuration contient cinq paramètres – api-url, token, output, color et timeout – tous lisibles et modifiables depuis le CLI. config view affiche la configuration effective, y compris l’origine du token.

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

Variables d’environnement

Chaque paramètre dispose aussi d’une variable d’environnement, ce que les runners CI utilisent généralement. NEXDNS_CONFIG désigne un autre fichier de configuration, pratique lorsque plusieurs comptes sont pilotés depuis une seule machine.

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

Supprimer un token enregistré

Efface le token du fichier de configuration. Le fichier lui-même, ainsi que l’URL d’API qui y est enregistrée, sont conservés.

nexdns auth logout

Complétion du shell

Des scripts de complétion sont générés pour bash, zsh, fish et PowerShell.

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

Scripts et CI

Le CLI est conçu pour être piloté par des pipelines : chaque échec correspond à un code de sortie distinct, les invites se soldent par un refus plutôt que de rester bloquées, et aucune action destructive n’a lieu sans avoir été demandée.

Codes de sortie

Une sous-commande mal orthographiée se termine avec le code 2 au lieu d’afficher l’aide et de réussir : une faute de frappe dans un pipeline ne peut donc pas passer pour une opération réussie.

Invites de confirmation

Les commandes destructives demandent confirmation avant d’agir. Sans terminal – c’est le cas de tout runner CI – l’invite se solde par un refus et la commande se termine avec le code 0 sans avoir rien changé : passez donc --force lorsque c’est bien votre intention.

Des échecs qui passaient auparavant inaperçus

• Un ${VAR} non résolu dans nexdns.yaml interrompt l’exécution et nomme chaque variable sans valeur, au lieu d’écrire le texte littéral dans un enregistrement.
• Un --zone qui ne désigne aucune zone du fichier est une erreur.
• zone check se termine avec un code de sortie non nul lorsqu’une vérification de propagation échoue.
• apply --confirm se termine avec un code de sortie non nul dès qu’une opération a échoué, et indique combien.

Limitation de débit et traitements en masse

Le budget d’API est défini par compte et par plan, dans une fenêtre glissante d’une minute. Le CLI lit ce budget dans chaque réponse et attend le renouvellement de la fenêtre avant de le dépasser : un import volumineux se termine donc intact au lieu de perdre des enregistrements, il prend simplement plus de temps. Une limite à fenêtre plus longue, comme le plafond du nombre de changements de groupe de serveurs de noms pour une même zone, est signalée plutôt qu’attendue.

Docker

Le CLI est disponible en tant qu’image Docker. Transmettez votre token API via la variable d’environnement NEXDNS_TOKEN.

Exécuter des commandes

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

Importer un fichier de zone

Montez un répertoire local pour transmettre des fichiers de zone au conteneur :

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

Options globales

Les options suivantes sont disponibles pour toutes les commandes :

Chacune de ces options lit également une variable d’environnement : NEXDNS_TOKEN, NEXDNS_API_URL, NEXDNS_TIMEOUT et NEXDNS_CONFIG. NO_COLOR désactive la couleur quelle que soit la valeur de --color.

Terraform

Le provider Terraform NexDNS vous permet de gérer les zones et les enregistrements en tant que ressources Terraform. Installez le provider depuis le Terraform Registry et configurez-le avec votre 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"
}

Intégration DNSControl

DNSControl est un outil DNS-as-code de Stack Overflow. Utilisez le provider NexDNS pour gérer vos zones de manière déclarative. Le provider est inclus dans DNSControl à partir de la version 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 est un outil DNS-as-code de GitHub. Installez le provider NexDNS et configurez-le comme source ou cible dans votre configuration OctoDNS.

Installer le provider

pip install octodns-nexdns

Fichier 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

Fichier 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.