CLI и инструменты разработчика

Установка

CLI NexDNS – это один исполняемый файл без внешних зависимостей. Выберите подходящий способ установки.

Скрипт установки

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

Определяет платформу, скачивает подходящий архив релиза, сверяет его с контрольными суммами, опубликованными вместе с релизом, и ставит бинарник в /usr/local/bin. Сначала прочитайте его командой curl https://get.nexdns.ru/cli, если не хотите передавать в оболочку непрочитанный скрипт.

Homebrew

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

Формула публикуется как cask, поэтому ставится с <code>--cask</code>, а не однострочной формой <code>brew install</code>.

Скачать архив релиза

Готовые сборки для Linux, macOS и Windows (amd64 и arm64) отдаёт сам сервис: текущую версию – https://get.nexdns.ru/cli/latest, архив и checksums.txt – https://get.nexdns.ru/cli/download/<версия>/. Распакуйте архив и положите nexdns в любой каталог из PATH.

Docker

docker pull nexdns/cli

Проверка установки

После установки убедитесь, что CLI доступен, и проверьте версию:

nexdns version

Аутентификация

Для работы CLI необходим API-токен. Создать токен можно на странице nexdns.ru/settings/api-keys.

Требования к тарифу: CLI работает через REST API, поэтому ему нужен API-ключ, доступный на тарифе Про и выше. То же относится к провайдеру Terraform, провайдеру OctoDNS и плагинам ACME.

Этот инстанс отдаёт API по адресу https://api.nexdns.ru/v1. По умолчанию CLI обращается к другому адресу, поэтому передайте этот URL при сохранении токена – он сохранится рядом с токеном, и все последующие команды будут использовать его.

Сохранить токен в конфигурацию

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
    --api-url https://api.nexdns.ru/v1

Переменная окружения (CI/CD)

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxx

Проверка статуса аутентификации

nexdns auth status

Файл конфигурации

Токен хранится в файле ~/.nexdns/config.yaml. CLI определяет учётные данные в следующем порядке приоритета:

1. Флаг --token (наивысший приоритет)
2. Переменная окружения NEXDNS_TOKEN
3. Файл конфигурации ~/.nexdns/config.yaml

Управление зонами

Управление DNS-зонами из командной строки. Все команды для зон доступны через подкоманду nexdns zone.

Список зон

Список выводится постранично. Используйте --all, чтобы пройти все страницы, или --search, --page и --per-page, чтобы сузить выборку.

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

Добавить зону

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

Чтобы создать вторичную зону, которая переносится с вашего собственного первичного сервера, передайте --type slave и публичный IP-адрес первичного сервера. Вторичные зоны доступны на тарифе Про и выше.

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

Информация о зоне

nexdns zone info example.com

Экспорт зоны

Экспортирует зону в формате зонного файла BIND – вывод можно сразу перенаправить в файл. Для машиночитаемой выгрузки передайте --format json.

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

Импорт файла зоны

Используйте --dry-run для предварительного просмотра изменений:

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

По умолчанию импорт только добавляет отсутствующие записи. Добавьте --replace, чтобы также удалить записи, которых нет в файле – тогда зона будет точно соответствовать файлу. Собственные NS- и SOA-записи зоны не затрагиваются.

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

Создать зону при отсутствии

Создаёт зону только если она ещё не существует (идемпотентная операция):

nexdns zone ensure example.com

Перенос зоны в другую группу DNS-серверов

Переносит зону в другую группу DNS-серверов, указанную по её slug. Зона продолжает отвечать всё время переноса: DNS-серверы новой группы готовятся до возврата команды, а прежние обслуживают запросы, пока резолверы обновляют данные. После переноса обновите делегирование у регистратора – новые DNS-серверы выводит nexdns zone info.

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

Зону можно перенести три раза в сутки. Сверх этого команда сообщает о лимите и ничего не меняет.

Проверка распространения DNS

Опрашивает публичные резолверы напрямую, а не через API, поэтому вы видите то же, что видит интернет. При неудачной проверке команда завершается с ненулевым кодом, поэтому её можно использовать как проверку перед развёртыванием.

nexdns zone check example.com

Удалить зону

Сначала запрашивает подтверждение. Добавьте --force, чтобы пропустить запрос в скрипте; без терминала подтверждение считается отказом, и ничего не удаляется.

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

Управление записями

Управление DNS-записями в зоне. Все команды для записей доступны через подкоманду nexdns record.

Список записей

Фильтруйте вывод флагами --type, --name (метка или @ для вершины зоны) и --search, который ищет по именам и содержимому.

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

Добавить записи

В аргументе content передаётся только основное значение. Всё остальное, что нужно типу записи – приоритет, вес, порт, тег и флаги CAA, параметры DS и TLSA – задаётся отдельными флагами, поэтому собирать строку вручную не нужно.

# 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 применяется ко всему набору записей. Если вы добавляете ещё одно значение к уже существующему имени и не передаёте --ttl, текущий TTL сохраняется; если передаёте – он применяется ко всем значениям этого имени. Для нового имени по умолчанию 3600 секунд.

Обновить запись

Изменяет содержимое, TTL, приоритет или метку. ID записи вычисляется из самой записи, поэтому после изменения возвращается новый ID – всегда берите его из ответа, а не используйте прежний.

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

Создать запись при отсутствии

Создаёт запись только если её ещё нет (точное совпадение типа, имени и значения). Существующие записи с другим значением не изменяются – безопасно для round-robin. Идемпотентная операция:

nexdns record ensure example.com A www 1.2.3.4

Удалить запись

nexdns record delete example.com <record-id>

DNSSEC

Управление DNSSEC-подписью для ваших зон.

Проверить статус DNSSEC

nexdns dnssec status example.com

Включить DNSSEC

nexdns dnssec enable example.com

Получить DS-записи

Получите DS-записи для настройки у вашего регистратора домена:

nexdns dnssec ds-records example.com

Отключить DNSSEC

Запрашивает подтверждение: если отключить подпись у делегированной зоны, валидация будет нарушена до тех пор, пока вы не удалите DS-запись у регистратора. В скриптах добавляйте --force.

nexdns dnssec disable example.com --force

DNS как код

Описывайте DNS-инфраструктуру декларативно в файле nexdns.yaml и управляйте ею через систему контроля версий. CLI сравнивает локальную конфигурацию с текущим состоянием и применяет только необходимые изменения.

Формат конфигурации

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

Предварительный просмотр изменений

Показать diff изменений без их применения:

nexdns apply

Применить изменения

Применить изменения после просмотра diff:

nexdns apply --confirm

Только diff

nexdns diff

Удаление записей, исчезнувших из файла

Запись, удалённая из nexdns.yaml, остаётся в зоне, пока вы не запросите удаление явно. Так сделано намеренно: неполный файл не должен опустошить зону. Добавьте --delete, чтобы файл стал единственным источником истины.

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

Выбор файла и зоны

Флаг --file указывает на конфигурацию за пределами рабочего каталога, а --zone ограничивает работу одной зоной из файла с несколькими зонами. Если --zone называет зону, которой в файле нет, команда завершается ошибкой, а не молча ничего не делает.

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

Получить текущее состояние

Сгенерировать nexdns.yaml из текущей конфигурации DNS:

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

Подстановка переменных окружения

Используйте синтаксис ${VARIABLE} в файле конфигурации. CLI подставляет переменные окружения при применении, что позволяет переиспользовать конфигурации в разных окружениях:

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

Webhooks

Подпишите свой эндпоинт на события ваших зон и управляйте подписками из терминала. Вебхуки доступны на тарифе Про и выше; API-ключу нужны разрешения webhooks.read и webhooks.write.

Подписать эндпоинт на события

Секрет для подписи выводится один раз, при создании, и получить его повторно нельзя – сохраните его там, откуда его прочитает ваш обработчик. Каждая доставка содержит HMAC-подпись, вычисленную этим секретом, поэтому обработчик может убедиться, что запрос действительно пришёл от нас.

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

Доступные события

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

Просмотр подписок

show дополнительно показывает десять последних попыток доставки с их кодом ответа и, если попытка не удалась, с текстом ошибки – обычно этого достаточно, чтобы отличить неверный URL от обработчика, который отклоняет данные.

nexdns webhook list
nexdns webhook show <webhook-id>

Отправить тестовое событие

Ставит тестовую доставку в очередь. Успех здесь означает, что событие принято платформой, а не что ваш эндпоинт ответил – результат смотрите командой nexdns webhook show.

nexdns webhook test <webhook-id>

Изменить или приостановить подписку

Передавайте только то, что меняется: команда читает текущую подписку и отправляет остальные поля без изменений. --active=false останавливает доставки, не удаляя эндпоинт, а --force удаляет подписку без запроса подтверждения.

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

Аккаунт и настройки

Посмотрите, какому аккаунту принадлежит токен, какой у него тариф и какие API-ключи созданы.

nexdns account info
nexdns account api-keys

Сохранённые настройки

В файле конфигурации хранятся пять параметров – api-url, token, output, color и timeout – и все они читаются и изменяются из CLI. Команда config view выводит действующую конфигурацию, включая источник токена.

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

Переменные окружения

У каждого параметра есть и переменная окружения – как правило, именно так его задают в CI. NEXDNS_CONFIG указывает на другой файл конфигурации: это удобно, когда с одной машины управляют несколькими аккаунтами.

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

Удалить сохранённый токен

Удаляет токен из файла конфигурации. Сам файл и сохранённый в нём адрес API остаются на месте.

nexdns auth logout

Автодополнение в командной оболочке

Скрипты автодополнения генерируются для bash, zsh, fish и PowerShell.

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

Скрипты и CI

CLI рассчитан на запуск из скриптов и CI: у каждой ошибки свой код возврата, запрос подтверждения отвечает отказом вместо ожидания, а деструктивные действия не выполняются без явного разрешения.

Коды возврата

Опечатка в подкоманде даёт код 2, а не справку с успешным завершением, поэтому ошибка в скрипте не пройдёт за выполненную операцию.

Запросы подтверждения

Деструктивные команды спрашивают подтверждение. Без терминала – а это любой запуск в CI – подтверждение считается отказом: команда завершается с кодом 0 и ничего не меняет, поэтому передавайте --force, когда действие действительно нужно.

Ошибки, которые раньше проходили незаметно

• Неразрешённая переменная ${VAR} в nexdns.yaml останавливает запуск и перечисляет все переменные без значения, вместо того чтобы записать в DNS-запись сам текст подстановки.
• Если --zone называет зону, которой нет в файле, это ошибка.
• zone check завершается с ненулевым кодом, если проверка распространения не прошла.
• apply --confirm завершается с ненулевым кодом, если хотя бы одна операция не удалась, и сообщает, сколько их было.

Лимиты запросов и массовые операции

Лимит запросов к API считается на аккаунт и зависит от тарифа, окно – одна минута, скользящее. CLI читает остаток лимита из каждого ответа и, если следующий запрос превысил бы лимит, ждёт начала нового окна, поэтому большой импорт доходит до конца без потери записей – просто занимает больше времени. О лимите с более длинным окном, например об ограничении на смену группы DNS-серверов для одной зоны, CLI сообщает, а не ждёт его окончания.

Docker

CLI доступен в виде Docker-образа. Передайте API-токен через переменную окружения NEXDNS_TOKEN.

Выполнение команд

docker run --rm -e NEXDNS_TOKEN=nxd_xxx \
    -e NEXDNS_API_URL=https://api.nexdns.ru/v1 nexdns/cli zone list

Импорт файла зоны

Подключите локальную директорию для передачи файлов зон в контейнер:

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

Глобальные флаги

Следующие флаги доступны для всех команд:

Каждый из них также читает переменную окружения: NEXDNS_TOKEN, NEXDNS_API_URL, NEXDNS_TIMEOUT и NEXDNS_CONFIG. NO_COLOR отключает цвет независимо от --color.

Terraform

Terraform-провайдер NexDNS позволяет управлять зонами и записями как ресурсами Terraform. Установите провайдер из Terraform Registry и настройте его с помощью API-токена.

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

provider "nexdns" {
  api_token = var.nexdns_token
  api_url   = "https://api.nexdns.ru/v1"
}

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

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

Интеграция с DNSControl

DNSControl – инструмент DNS-as-code от Stack Overflow. Используйте провайдер NexDNS для декларативного управления зонами. Провайдер входит в DNSControl начиная с версии 4.46.0.

creds.json

{
    "nexdns": {
        "TYPE": "NEXDNS",
        "api_token": "nxd_xxxxxxxxxxxxxxxxxxxx",
        "api_url": "https://api.nexdns.ru/v1"
    }
}

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 – инструмент DNS-as-code от GitHub. Установите провайдер NexDNS и настройте его как источник или цель в конфигурации OctoDNS.

Установка провайдера

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
    api_url: https://api.nexdns.ru/v1

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.