CLI a vývojářské nástroje

Instalace

NexDNS CLI je jeden binární soubor bez externích závislostí. Vyberte si způsob instalace, který vyhovuje vašemu prostředí.

Instalační skript

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

Rozpozná vaši platformu, stáhne odpovídající archiv vydání, ověří jej proti kontrolním součtům zveřejněným s vydáním a nainstaluje binárku do /usr/local/bin. Pomocí curl https://get.nexdns.tech/cli si jej nejprve přečtěte, pokud nechcete posílat do shellu nepřečtený skript.

Instalace pomocí Go

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

Homebrew

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

Formule se publikuje jako cask, takže se instaluje pomocí <code>--cask</code>, nikoli jednořádkovou formou <code>brew install</code>.

Stažení archivu vydání

Předkompilované binárky pro Linux, macOS a Windows (amd64 a arm64) jsou přiloženy ke každému vydání na GitHubu. Rozbalte archiv a umístěte nexdns do libovolného adresáře ve PATH.

Docker

docker pull nexdns/cli

Ověření instalace

Po instalaci ověřte, že CLI je dostupné, a zkontrolujte jeho verzi:

nexdns version

Autentizace

CLI vyžaduje API token pro komunikaci s NexDNS API. Token si můžete vytvořit na nexdns.tech/settings/api-keys.

Požadavek na tarif: CLI pracuje přes REST API, takže potřebuje API klíč, který je dostupný v tarifu Pro a vyšším. Totéž platí pro Terraform provider, OctoDNS provider a ACME pluginy.

Uložení tokenu do konfigurace

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Proměnná prostředí (CI/CD)

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxx

Kontrola stavu autentizace

nexdns auth status

Konfigurační soubor

Token je uložen v ~/.nexdns/config.yaml. CLI řeší přihlašovací údaje v následujícím pořadí priority:

1. Příznak --token (nejvyšší priorita)
2. Proměnná prostředí NEXDNS_TOKEN
3. Konfigurační soubor ~/.nexdns/config.yaml

Správa zón

Správa DNS zón z příkazové řádky. Všechny příkazy pro zóny jsou pod podpříkazem nexdns zone.

Výpis zón

Výpis je stránkovaný. Pomocí --all projdete všechny stránky, pomocí --search, --page a --per-page jej zúžíte.

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

Přidání zóny

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

Chcete-li vytvořit sekundární zónu, která se přenáší z vašeho vlastního primárního serveru, předejte --type slave s veřejnou IP adresou primárního serveru. Sekundární zóny jsou dostupné v tarifu Pro a vyšším.

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

Informace o zóně

nexdns zone info example.com

Export zóny

Exportuje zónu ve formátu souboru zóny BIND, připravenou k přesměrování do souboru. Pro strojově čitelný přehled použijte --format json.

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

Import souboru zóny

Použijte --dry-run pro náhled změn před jejich provedením:

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

Import ve výchozím nastavení pouze přidává to, co chybí. Přidejte --replace, aby se smazaly i záznamy, které soubor nedefinuje – zóna pak souboru přesně odpovídá. Vlastní NS a SOA záznamy zóny zůstávají vždy nedotčené.

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

Zajištění existence zóny

Vytvoří zónu pouze v případě, že dosud neexistuje (idempotentní):

nexdns zone ensure example.com

Přesun zóny do jiné skupiny nameserverů

Přesune zónu do jiné skupiny nameserverů určené jejím slugem. Zóna po celou dobu odpovídá: nameservery nové skupiny se připraví ještě před dokončením příkazu a ty staré obsluhují dotazy, dokud si resolvery neobnoví data. Poté aktualizujte delegaci u svého registrátora – nexdns zone info vypíše nové nameservery.

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

Zónu lze přesunout třikrát denně. Po vyčerpání limitu příkaz limit oznámí a nic nezmění.

Kontrola propagace DNS

Dotazuje se přímo veřejných resolverů, ne našeho API, takže vidíte to, co vidí internet. Při selhání kontroly skončí nenulovým kódem, takže se dá použít jako kontrolní bod při nasazení.

nexdns zone check example.com

Smazání zóny

Nejprve si vyžádá potvrzení. Ve skriptu přidejte --force, abyste dotaz přeskočili; bez terminálu se dotaz automaticky odmítne a nic se nesmaže.

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

Správa záznamů

Správa DNS záznamů v rámci zóny. Všechny příkazy pro záznamy jsou pod podpříkazem nexdns record.

Výpis záznamů

Filtrujte pomocí --type, --name (jedna část názvu, nebo @ pro apex zóny) nebo --search, který hledá v názvech i obsahu.

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

Přidání záznamů

Argument content nese pouze primární hodnotu. Vše ostatní, co daný typ záznamu potřebuje – prioritu, váhu, port, tag a flags u CAA, parametry DS a TLSA – je samostatný příznak, takže nic nemusíte skládat ručně.

# 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

TTL platí pro celou sadu záznamů. Když přidáváte další hodnotu k názvu, který už existuje, a --ttl vynecháte, zachová se stávající TTL; pokud ho zadáte, přenastaví se u všech hodnot na tomto názvu. Zcela nový název má výchozí hodnotu 3600 sekund.

Aktualizace záznamu

Změní obsah, TTL, prioritu nebo název. ID záznamu se odvozuje ze samotného záznamu, takže úprava vrátí nové ID – vždy si ho přečtěte z odpovědi, místo abyste znovu použili to původní.

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

Vytvoření záznamu, pokud chybí

Vytvoří záznam pouze v případě, že dosud neexistuje (přesná shoda typu, názvu a obsahu). Stávající záznamy s odlišným obsahem zůstanou nedotčené – bezpečné pro round-robin konfigurace. Idempotentní:

nexdns record ensure example.com A www 1.2.3.4

Smazání záznamu

nexdns record delete example.com <record-id>

DNSSEC

Správa podepisování DNSSEC pro vaše zóny.

Kontrola stavu DNSSEC

nexdns dnssec status example.com

Aktivace DNSSEC

nexdns dnssec enable example.com

Získání záznamů DS

Získání záznamů DS pro konfiguraci u vašeho registrátora domén:

nexdns dnssec ds-records example.com

Deaktivace DNSSEC

Vyžádá si potvrzení, protože vypnutí podepisování u delegované zóny naruší validaci, dokud u registrátora neodeberete záznam DS. Ve skriptu přidejte --force.

nexdns dnssec disable example.com --force

DNS jako kód

Definujte svou DNS infrastrukturu deklarativně v souboru nexdns.yaml a spravujte ji pomocí verzovacího systému. CLI porovná vaši lokální konfiguraci s aktuálním stavem a provede pouze nezbytné změny.

Formát konfigurace

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

Náhled změn

Zobrazení diffu toho, co by se změnilo, bez provedení jakýchkoli změn:

nexdns apply

Aplikace změn

Aplikujte změny po kontrole diffu:

nexdns apply --confirm

Pouze diff

nexdns diff

Odebrání záznamů, které ze souboru zmizely

Záznam smazaný ze souboru nexdns.yaml zůstane na místě, pokud si mazání výslovně nevyžádáte. Je to záměr: neúplný soubor tak nevyprázdní celou zónu. Přidejte --delete, aby byl soubor autoritativní.

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

Volba souboru a zóny

Použijte --file pro konfiguraci mimo pracovní adresář a --zone pro práci s jedinou zónou ze souboru s více zónami. Pokud --zone neodpovídá žádné zóně v souboru, jde o chybu, nikoli o tiché přeskočení.

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

Stažení aktuálního stavu

Vygenerujte soubor nexdns.yaml z aktuální živé konfigurace DNS:

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

Substituce proměnných prostředí

V konfiguračním souboru použijte syntaxi ${VARIABLE}. CLI nahradí proměnné prostředí při aplikaci, což usnadňuje opětovné použití konfigurací napříč prostředími:

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

Webhooks

Přihlaste endpoint k odběru událostí, které vaše zóny generují, a spravujte tyto odběry z terminálu. Webhooky jsou dostupné v tarifu Pro a vyšším; API klíč potřebuje oprávnění webhooks.read a webhooks.write.

Přihlášení endpointu k odběru

Podpisový tajný klíč se vypíše jen jednou, při vytvoření, a později ho už nelze získat – uložte ho tam, kde ho váš přijímající endpoint přečte. Každé doručení nese podpis HMAC vypočítaný tímto klíčem, takže si endpoint může ověřit, že požadavek skutečně přišel od nás.

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

Dostupné události

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

Prohlížení odběrů

show navíc vypíše deset posledních pokusů o doručení s jejich stavovým kódem a v případě selhání i chybu – to obvykle stačí k odlišení špatné URL od endpointu, který data odmítá.

nexdns webhook list
nexdns webhook show <webhook-id>

Odeslání testovací události

Zařadí do fronty testovací doručení. Úspěch zde znamená, že platforma událost přijala, ne že odpověděl váš endpoint – výsledek si přečtěte příkazem nexdns webhook show.

nexdns webhook test <webhook-id>

Změna nebo pozastavení odběru

Předejte jen to, co se mění; příkaz načte aktuální odběr a ostatní hodnoty odešle znovu. Použijte --active=false k zastavení doručování bez smazání endpointu a --force ke smazání bez potvrzovacího dotazu.

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

Účet a konfigurace

Zjistěte, kterému účtu token patří, jaký má tarif a jaké API klíče existují.

nexdns account info
nexdns account api-keys

Trvale uložená nastavení

Konfigurační soubor obsahuje pět nastavení – api-url, token, output, color a timeout – a všechna z nich lze pomocí CLI číst i zapisovat. config view vypíše výslednou konfiguraci včetně toho, odkud se vzal token.

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

Proměnné prostředí

Každé nastavení má také proměnnou prostředí, což je způsob, který obvykle používají CI runnery. NEXDNS_CONFIG ukazuje na alternativní konfigurační soubor, což se hodí, když z jednoho stroje spravujete několik účtů.

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

Odstranění uloženého tokenu

Odstraní token z konfiguračního souboru. Samotný soubor i URL API, které je v něm uložené, zůstanou zachovány.

nexdns auth logout

Doplňování v shellu

Skripty pro doplňování se generují pro bash, zsh, fish a PowerShell.

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

Skriptování a CI

CLI je navrženo pro řízení z pipeline: každá chyba má vlastní návratový kód, dotazy se samy odmítnou místo čekání a nic destruktivního se nestane bez výslovného pokynu.

Návratové kódy

Chybně napsaný podpříkaz skončí kódem 2, místo aby vypsal nápovědu a uspěl, takže překlep v pipeline nemůže projít jako dokončená operace.

Potvrzovací dotazy

Destruktivní příkazy se před provedením zeptají. Bez terminálu – tedy v každém CI runneru – se dotaz sám odmítne a příkaz skončí kódem 0, aniž by cokoli změnil, takže když to myslíte vážně, předejte --force.

Chyby, které dřív procházely bez povšimnutí

• Nevyřešená ${VAR} v souboru nexdns.yaml zastaví běh a vypíše každou proměnnou, která neměla hodnotu, místo aby do záznamu zapsala doslovný text.
• Pokud --zone neodpovídá žádné zóně v souboru, jde o chybu.
• zone check skončí nenulovým kódem, pokud kontrola propagace selže.
• apply --confirm skončí nenulovým kódem, pokud jakákoli operace selhala, a uvede, kolik jich bylo.

Omezení počtu požadavků a hromadné operace

Rozpočet API se počítá na účet a podle tarifu, v posuvném jednominutovém okně. CLI čte rozpočet z každé odpovědi a než by ho vyčerpalo, počká na překlopení okna, takže velký import proběhne celý a neztratí záznamy – jen trvá déle. Limit s delším oknem, například strop na to, jak často může jedna zóna změnit skupinu nameserverů, se místo čekání jen oznámí.

Docker

CLI je k dispozici jako Docker image. Předejte svůj API token prostřednictvím proměnné prostředí NEXDNS_TOKEN.

Spuštění příkazů

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

Import souboru zóny

Připojte lokální adresář pro předání souborů zón do kontejneru:

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

Globální příznaky

Následující příznaky jsou k dispozici u všech příkazů:

Každý z nich čte také proměnnou prostředí: NEXDNS_TOKEN, NEXDNS_API_URL, NEXDNS_TIMEOUT a NEXDNS_CONFIG. NO_COLOR vypne barvy bez ohledu na --color.

Terraform

NexDNS Terraform provider umožňuje spravovat zóny a záznamy jako Terraform resources. Nainstalujte provider z Terraform Registry a nakonfigurujte ho s vaším API tokenem.

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"
}

Integrace DNSControl

DNSControl je nástroj pro DNS-as-code od Stack Overflow. Použijte NexDNS provider pro deklarativní správu vašich zón. Provider je součástí DNSControl od verze 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 je nástroj pro DNS-as-code od GitHub. Nainstalujte NexDNS provider a nakonfigurujte ho jako zdroj nebo cíl ve vaší konfiguraci OctoDNS.

Instalace provideru

pip install octodns-nexdns

Soubor 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

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