CLI i narzędzia deweloperskie

Instalacja

CLI NexDNS to pojedynczy plik binarny bez zewnętrznych zależności. Wybierz metodę instalacji odpowiednią dla Twojego środowiska.

Skrypt instalacyjny

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

Wykrywa twoją platformę, pobiera odpowiednie archiwum wydania, weryfikuje je względem sum kontrolnych opublikowanych wraz z wydaniem i instaluje plik binarny w /usr/local/bin. Przeczytaj go najpierw poleceniem curl https://get.nexdns.tech/cli, jeśli wolisz nie przekazywać powłoce nieprzeczytanego skryptu.

Instalacja przez Go

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

Homebrew

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

Formuła jest publikowana jako cask, więc instaluje się ją z <code>--cask</code>, a nie jednolinijkową formą <code>brew install</code>.

Pobranie archiwum wydania

Gotowe pliki binarne dla Linuksa, macOS i Windows (amd64 i arm64) są dołączone do każdego wydania na GitHubie. Rozpakuj archiwum i umieść nexdns w dowolnym katalogu z PATH.

Docker

docker pull nexdns/cli

Weryfikacja instalacji

Po instalacji sprawdź, czy CLI jest dostępne i wyświetl wersję:

nexdns version

Autoryzacja

CLI wymaga tokenu API do komunikacji z API NexDNS. Token możesz utworzyć pod adresem nexdns.tech/settings/api-keys.

Wymagany plan: CLI działa przez REST API, więc potrzebuje klucza API, dostępnego w planie Pro i wyższych. To samo dotyczy providera Terraform, providera OctoDNS i wtyczek ACME.

Zapisz token w konfiguracji

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Zmienna środowiskowa (CI/CD)

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxx

Sprawdź status autoryzacji

nexdns auth status

Plik konfiguracyjny CLI

Token jest przechowywany w ~/.nexdns/config.yaml. CLI rozwiązuje dane uwierzytelniające w następującej kolejności priorytetów:

1. --token flaga (najwyższy priorytet)
2. Zmienna środowiskowa NEXDNS_TOKEN
3. Plik konfiguracyjny ~/.nexdns/config.yaml

Zarządzanie strefami

Zarządzaj strefami DNS z wiersza poleceń. Wszystkie polecenia stref znajdują się pod komendą nexdns zone.

Wyświetl strefy

Lista jest podzielona na strony. Użyj --all, aby przejść wszystkie strony, albo --search, --page i --per-page, aby ją zawęzić.

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

Dodaj strefę

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

Aby utworzyć strefę podrzędną pobierającą dane z własnego serwera głównego, przekaż --type slave wraz z publicznym adresem IP tego serwera. Strefy podrzędne są dostępne w planie Pro i wyższych.

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

Informacje o strefie

nexdns zone info example.com

Eksportuj strefę

Eksportuje strefę w formacie pliku strefy BIND, gotowym do przekierowania do pliku. Aby otrzymać zamiast tego inwentarz czytelny dla maszyn, przekaż --format json.

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

Importuj plik strefy

Użyj --dry-run, aby podejrzeć zmiany przed ich zastosowaniem:

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

Domyślnie import dodaje tylko to, czego brakuje. Dodaj --replace, aby usunąć również rekordy nieopisane w pliku – wtedy strefa odpowiada plikowi dokładnie. Własne rekordy serwerów nazw i rekord SOA strefy nigdy nie są modyfikowane.

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

Zapewnij istnienie strefy

Tworzy strefę tylko wtedy, gdy jeszcze nie istnieje (idempotentnie):

nexdns zone ensure example.com

Przenieś strefę do innej grupy serwerów nazw

Przenosi strefę do innej grupy serwerów nazw, wskazanej jej slugiem. Strefa odpowiada bez przerwy: serwery nazw nowej grupy są przygotowane przed zakończeniem polecenia, a stare nadal obsługują zapytania, dopóki resolvery nie odświeżą danych. Następnie zaktualizuj delegację u rejestratora – nexdns zone info wypisuje nowe serwery nazw.

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

Strefę można przenieść trzy razy dziennie. Powyżej tego limitu polecenie zgłasza limit i nic nie zmienia.

Sprawdź propagację DNS

Odpytuje bezpośrednio publiczne resolvery, a nie API, więc widzisz to, co widzi internet. Kończy się kodem różnym od zera, gdy sprawdzenie się nie uda, dzięki czemu nadaje się na bramkę wdrożeniową.

nexdns zone check example.com

Usuń strefę

Najpierw pyta o potwierdzenie. Dodaj --force, aby pominąć pytanie w skrypcie; bez terminala pytanie jest automatycznie odrzucane i nic nie zostaje usunięte.

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

Zarządzanie rekordami

Zarządzaj rekordami DNS w strefie. Wszystkie polecenia rekordów znajdują się pod komendą nexdns record.

Wyświetl rekordy

Filtruj flagami --type, --name (etykieta lub @ dla wierzchołka strefy) albo --search, która dopasowuje nazwy i treść.

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

Dodaj rekordy

Argument content zawiera tylko wartość główną. Wszystko pozostałe, czego wymaga dany typ rekordu – priorytet, waga, port, tag i flagi CAA, parametry DS i TLSA – to osobne flagi, więc niczego nie trzeba składać ręcznie.

# 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 dotyczy całego zestawu rekordów. Jeśli dodajesz kolejną wartość do już istniejącej nazwy, pomiń --ttl – dotychczasowy TTL zostanie zachowany; podaj go, a każda wartość pod tą nazwą otrzyma nowy czas życia. Dla całkiem nowej nazwy domyślną wartością jest 3600 sekund.

Zaktualizuj rekord

Zmień treść, TTL, priorytet lub etykietę. Identyfikatory rekordów są wyliczane z samego rekordu, więc edycja zwraca nowe ID – zawsze odczytuj je z odpowiedzi, zamiast używać poprzedniego.

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

Utwórz rekord, jeśli go brak

Tworzy rekord tylko wtedy, gdy jeszcze nie istnieje (dokładne dopasowanie typu, nazwy i zawartości). Istniejące rekordy o innej zawartości pozostają nienaruszone – bezpieczne dla konfiguracji round-robin. Idempotentnie:

nexdns record ensure example.com A www 1.2.3.4

Usuń rekord

nexdns record delete example.com <record-id>

DNSSEC

Zarządzaj podpisywaniem DNSSEC dla stref.

Sprawdź status DNSSEC

nexdns dnssec status example.com

Włącz DNSSEC

nexdns dnssec enable example.com

Pobierz rekordy DS

Pobierz rekordy DS do skonfigurowania u rejestratora domen:

nexdns dnssec ds-records example.com

Wyłącz DNSSEC

Pyta o potwierdzenie, ponieważ wyłączenie podpisywania w delegowanej strefie psuje walidację, dopóki rekord DS nie zostanie wycofany u rejestratora. W skrypcie dodaj --force.

nexdns dnssec disable example.com --force

DNS jako kod

Definiuj infrastrukturę DNS deklaratywnie w pliku nexdns.yaml i zarządzaj nią za pomocą kontroli wersji. CLI porównuje lokalną konfigurację ze stanem aktualnym i stosuje tylko niezbędne zmiany.

Format konfiguracji

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

Podgląd zmian

Pokaż różnice bez stosowania zmian:

nexdns apply

Zastosuj zmiany

Zastosuj zmiany po przejrzeniu różnic:

nexdns apply --confirm

Tylko różnice

nexdns diff

Usuń rekordy, które zniknęły z pliku

Rekord usunięty z pliku nexdns.yaml pozostaje na miejscu, dopóki nie zażądasz usunięcia wprost. Jest to zamierzone: chroni strefę przed opróżnieniem przez niekompletny plik. Dodaj --delete, aby plik stał się źródłem prawdy.

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

Wybierz plik i strefę

Użyj --file dla konfiguracji poza katalogiem roboczym oraz --zone, aby działać na jednej strefie z pliku zawierającego wiele stref. Flaga --zone wskazująca strefę, której nie ma w pliku, jest błędem, a nie cichym pominięciem.

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

Pobierz aktualny stan

Wygeneruj plik nexdns.yaml z bieżącej konfiguracji DNS:

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

Podstawianie zmiennych środowiskowych

Użyj składni ${VARIABLE} w pliku konfiguracyjnym. CLI podstawia zmienne środowiskowe podczas stosowania, ułatwiając ponowne wykorzystanie konfiguracji w różnych środowiskach:

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

Webhooks

Zapisz swój endpoint na zdarzenia generowane przez strefy i zarządzaj tymi subskrypcjami z terminala. Webhooki są dostępne w planie Pro i wyższych; klucz API potrzebuje uprawnień webhooks.read i webhooks.write.

Zasubskrybuj endpoint

Sekret podpisujący jest wyświetlany tylko raz, przy tworzeniu, i nie da się go później odczytać – zapisz go tam, gdzie odbiorca będzie mógł go odczytać. Każda dostawa zawiera podpis HMAC obliczony tym sekretem, więc odbiorca może sprawdzić, że zapytanie rzeczywiście pochodzi od nas.

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

Dostępne zdarzenia

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

Przeglądaj subskrypcje

Polecenie show dodaje dziesięć ostatnich prób dostawy wraz z kodem statusu, a przy nieudanej próbie także błąd – zwykle wystarcza to, by odróżnić błędny URL od odbiorcy, który odrzuca przesyłane dane.

nexdns webhook list
nexdns webhook show <webhook-id>

Wyślij zdarzenie testowe

Kolejkuje testową dostawę. Powodzenie oznacza tutaj, że platforma przyjęła zdarzenie, a nie że endpoint odpowiedział – wynik odczytasz poleceniem nexdns webhook show.

nexdns webhook test <webhook-id>

Zmień lub wstrzymaj subskrypcję

Przekaż tylko to, co się zmienia; polecenie odczytuje bieżącą subskrypcję i ponownie wysyła pozostałe wartości. Użyj --active=false, aby zatrzymać dostawy bez usuwania endpointu, oraz --force, aby usunąć bez pytania o potwierdzenie.

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

Konto i konfiguracja

Sprawdź, do którego konta należy token, jaki plan ma to konto i jakie klucze API istnieją.

nexdns account info
nexdns account api-keys

Zapisane ustawienia

Plik konfiguracyjny przechowuje pięć ustawień – api-url, token, output, color i timeout – a wszystkie można odczytać i zapisać z CLI. config view wypisuje efektywną konfigurację wraz ze źródłem tokenu.

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

Zmienne środowiskowe

Każde ustawienie ma też zmienną środowiskową – zwykle właśnie z nich korzystają runnery CI. NEXDNS_CONFIG wskazuje alternatywny plik konfiguracyjny, co przydaje się, gdy z jednej maszyny obsługiwanych jest kilka kont.

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

Usuń zapisany token

Usuwa token z pliku konfiguracyjnego. Sam plik i zapisany w nim adres URL API pozostają bez zmian.

nexdns auth logout

Uzupełnianie w powłoce

Skrypty uzupełniania są generowane dla bash, zsh, fish i PowerShell.

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

Skrypty i CI

CLI jest zaprojektowane do pracy w pipeline'ach: każdy błąd ma osobny kod wyjścia, pytania nie zawieszają się, tylko są odrzucane, i nic destrukcyjnego nie dzieje się bez wyraźnego polecenia.

Kody wyjścia

Błędnie wpisana podkomenda kończy się kodem 2, a nie wypisaniem pomocy i sukcesem, więc literówka w skrypcie CI nie zostanie uznana za wykonaną operację.

Pytania o potwierdzenie

Polecenia destrukcyjne pytają przed wykonaniem. Bez terminala – czyli w każdym runnerze CI – pytanie jest odrzucane i polecenie kończy się kodem 0, nie zmieniając niczego, więc przekaż --force, jeśli naprawdę o to chodzi.

Błędy, które wcześniej przechodziły bez sygnału

• Nierozwiązana zmienna ${VAR} w pliku nexdns.yaml przerywa działanie i wskazuje każdą zmienną bez wartości, zamiast wpisać do rekordu jej dosłowną treść.
• Flaga --zone wskazująca strefę, której nie ma w pliku, jest błędem.
• Polecenie zone check kończy się kodem różnym od zera, gdy sprawdzenie propagacji się nie uda.
• Polecenie apply --confirm kończy się kodem różnym od zera, gdy jakakolwiek operacja się nie udała, i podaje ich liczbę.

Limit zapytań i praca masowa

Budżet API jest przypisany do konta i do planu, w przesuwnym oknie jednej minuty. CLI odczytuje budżet z każdej odpowiedzi i czeka na odnowienie okna, zamiast go przekroczyć, więc duży import kończy się w całości i nie traci rekordów – po prostu trwa dłużej. Limit o dłuższym oknie, na przykład ograniczenie częstotliwości zmiany grupy serwerów nazw dla jednej strefy, jest zgłaszany, a nie przeczekiwany.

Docker

CLI jest dostępne jako obraz Docker. Przekaż token API za pomocą zmiennej środowiskowej NEXDNS_TOKEN.

Uruchamianie poleceń

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

Importuj plik strefy

Zamontuj lokalny katalog, aby przekazać pliki stref do kontenera:

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

Flagi globalne

Następujące flagi są dostępne dla wszystkich poleceń:

Każda z nich odczytuje też zmienną środowiskową: NEXDNS_TOKEN, NEXDNS_API_URL, NEXDNS_TIMEOUT i NEXDNS_CONFIG. NO_COLOR wyłącza kolor niezależnie od --color.

Terraform

Provider Terraform NexDNS umożliwia zarządzanie strefami i rekordami jako zasobami Terraform. Zainstaluj provider z Terraform Registry i skonfiguruj go za pomocą tokenu 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 to narzędzie DNS jako kod od Stack Overflow. Użyj providera NexDNS do deklaratywnego zarządzania strefami. Provider jest dostępny w DNSControl od wersji 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 to narzędzie DNS-as-code od GitHub. Zainstaluj provider NexDNS i skonfiguruj go jako źródło lub cel w konfiguracji OctoDNS.

Zainstaluj provider

pip install octodns-nexdns

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

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.