CLI ve geliştirici araçları

Kurulum

NexDNS CLI, harici bağımlılığı olmayan tek bir çalıştırılabilir dosyadır. Ortamınıza uygun kurulum yöntemini seçin.

Kurulum betiği

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

Platformunuzu algılar, uygun sürüm arşivini indirir, sürümle birlikte yayımlanan sağlama toplamlarıyla doğrular ve ikili dosyayı /usr/local/bin dizinine kurar. Okumadığınız bir betiği kabuğa aktarmak istemiyorsanız önce curl https://get.nexdns.tech/cli ile inceleyin.

Go ile kurulum

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

Homebrew

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

Formül bir cask olarak yayımlanır; bu nedenle tek satırlık <code>brew install</code> biçimi yerine <code>--cask</code> ile kurulur.

Sürüm arşivini indirin

Linux, macOS ve Windows (amd64 ve arm64) için önceden derlenmiş ikili dosyalar her sürüme GitHub üzerinden eklenir. Arşivi açın ve nexdns dosyasını PATH içindeki bir dizine koyun.

Docker

docker pull nexdns/cli

Kurulumu doğrulama

Kurulumdan sonra CLI'nin kullanılabilir olduğunu doğrulayın ve sürümünü kontrol edin:

nexdns version

Kimlik doğrulama

CLI, NexDNS API ile iletişim kurmak için bir API jetonu gerektirir. nexdns.tech/settings/api-keys adresinden bir jeton oluşturabilirsiniz.

Plan gereksinimi: CLI, REST API üzerinden çalışır ve bu nedenle Pro ve üzeri planlarda kullanılabilen bir API anahtarına ihtiyaç duyar. Aynısı Terraform sağlayıcısı, OctoDNS sağlayıcısı ve ACME eklentileri için de geçerlidir.

Jetonu yapılandırmaya kaydetme

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ortam değişkeni (CI/CD)

export NEXDNS_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxx

Kimlik doğrulama durumunu kontrol etme

nexdns auth status

Yapılandırma dosyası

Jeton ~/.nexdns/config.yaml dosyasında saklanır. CLI, kimlik bilgilerini aşağıdaki öncelik sırasına göre çözümler:

1. --token bayrağı (en yüksek öncelik)
2. NEXDNS_TOKEN ortam değişkeni
3. Yapılandırma dosyası ~/.nexdns/config.yaml

Bölge yönetimi

DNS bölgelerini komut satırından yönetin. Tüm bölge komutları nexdns zone alt komutu altındadır.

Bölgeleri listeleme

Liste sayfalanır. Her sayfayı dolaşmak için --all, listeyi daraltmak için --search, --page ve --per-page kullanın.

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

Bölge ekleme

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

Kendi birincil sunucunuzdan aktarım yapan bir ikincil bölge oluşturmak için birincil sunucunun genel IP adresiyle birlikte --type slave geçirin. İkincil bölgeler Pro ve üzeri planlarda kullanılabilir.

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

Bölge bilgisi

nexdns zone info example.com

Bölge dışa aktarma

Bölgeyi, doğrudan bir dosyaya yönlendirmeye hazır biçimde BIND bölge dosyası formatında dışa aktarır. Makine tarafından okunabilir bir envanter için --format json geçirin.

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

Bölge dosyası içe aktarma

Değişiklikleri uygulamadan önce önizlemek için --dry-run kullanın:

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

İçe aktarma varsayılan olarak yalnızca eksik olanı ekler. Dosyada tanımlanmayan kayıtların da silinmesi ve bölgenin dosyayla tam olarak eşleşmesi için --replace ekleyin. Bölgenin kendi ad sunucusu ve SOA kayıtlarına asla dokunulmaz.

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

Bölgenin mevcut olmasını sağlama

Bölgeyi yalnızca henüz mevcut değilse oluşturur (idempotent):

nexdns zone ensure example.com

Bölgeyi başka bir ad sunucusu grubuna taşıma

Bölgeyi, slug değeriyle belirtilen başka bir ad sunucusu grubuna taşır. Bölge bu süre boyunca yanıt vermeye devam eder: yeni grubun ad sunucuları komut geri dönmeden önce hazırlanır, eskiler ise çözümleyiciler kendini yenilerken hizmet vermeyi sürdürür. Ardından kayıt şirketinizdeki devri güncelleyin – nexdns zone info yeni ad sunucularını yazdırır.

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

Bir bölge günde üç kez taşınabilir. Bu sınırın ötesinde komut sınırı bildirir ve hiçbir şeyi değiştirmez.

DNS yayılımını kontrol etme

API'yi değil, doğrudan genel çözümleyicileri sorgular; böylece internetin gördüğünü görürsünüz. Bir kontrol başarısız olduğunda sıfırdan farklı bir kodla çıkar; bu da dağıtım hattında kontrol noktası olarak kullanılmasını sağlar.

nexdns zone check example.com

Bölge silme

Önce onay ister. Betikte istemi atlamak için --force ekleyin; terminal yoksa istem otomatik olarak reddedilir ve hiçbir şey silinmez.

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

Kayıt yönetimi

Bir bölge içindeki DNS kayıtlarını yönetin. Tüm kayıt komutları nexdns record alt komutu altındadır.

Kayıtları listeleme

--type, --name (bir etiket ya da bölge kökü için @) veya ad ile içerikte eşleşme yapan --search ile filtreleyin.

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

Kayıt ekleme

content argümanı yalnızca birincil değeri taşır. Bir kayıt türünün ihtiyaç duyduğu diğer her şey – öncelik, ağırlık, port, CAA etiketi ve bayrakları, DS ve TLSA parametreleri – ayrı bir bayraktır; böylece hiçbir şeyi elle birleştirmeniz gerekmez.

# 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, tüm kayıt kümesi için geçerlidir. Zaten var olan bir ada başka bir değer eklerken --ttl bayrağını atlarsanız mevcut TTL korunur; geçirirseniz o addaki her değerin süresi yeniden ayarlanır. Yepyeni bir ad için varsayılan 3600 saniyedir.

Kayıt güncelleme

İçeriği, TTL'yi, önceliği veya etiketi değiştirin. Kayıt kimlikleri kaydın kendisinden türetilir; bu yüzden bir düzenleme yeni bir kimlik döndürür – eskisini yeniden kullanmak yerine kimliği her zaman yanıttan okuyun.

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

Kayıt yoksa oluşturma

Kaydı yalnızca henüz mevcut değilse oluşturur (tür, ad ve içeriğin tam eşleşmesi). İçeriği farklı olan mevcut kayıtlara dokunulmaz – round-robin yapılandırmaları için güvenlidir. Idempotent:

nexdns record ensure example.com A www 1.2.3.4

Kayıt silme

nexdns record delete example.com <record-id>

DNSSEC

Bölgeleriniz için DNSSEC imzalamasını yönetin.

DNSSEC durumunu kontrol etme

nexdns dnssec status example.com

DNSSEC'i etkinleştirme

nexdns dnssec enable example.com

DS kayıtlarını alma

Alan adı kayıt şirketinizde yapılandırmak için DS kayıtlarını alın:

nexdns dnssec ds-records example.com

DNSSEC'i devre dışı bırakma

Onay ister, çünkü devredilmiş bir bölgede imzalamayı kapatmak, DS kaydı kayıt şirketinizden kaldırılana kadar doğrulamayı bozar. Betikte --force ekleyin.

nexdns dnssec disable example.com --force

Kod olarak DNS

DNS altyapınızı bir nexdns.yaml dosyasında bildirimsel olarak tanımlayın ve sürüm kontrolü ile yönetin. CLI, yerel yapılandırmanızı canlı durumla karşılaştırır ve yalnızca gerekli değişiklikleri uygular.

Yapılandırma formatı

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

Değişiklikleri önizleme

Hiçbir şey uygulamadan nelerin değişeceğini gösteren bir fark görüntüleyin:

nexdns apply

Değişiklikleri uygulama

Farkı inceledikten sonra değişiklikleri uygulayın:

nexdns apply --confirm

Yalnızca fark

nexdns diff

Dosyadan çıkan kayıtları kaldırma

nexdns.yaml dosyasından silinen bir kayıt, silme işlemini açıkça istemediğiniz sürece yerinde bırakılır. Bu bilinçli bir tercih: eksik bir dosyanın bölgeyi boşaltmasını önler. Dosyayı yetkili kaynak yapmak için --delete ekleyin.

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

Dosyayı ve bölgeyi seçme

Çalışma dizini dışındaki bir yapılandırma için --file, çok bölgeli bir dosyadan tek bir bölge üzerinde işlem yapmak için --zone kullanın. Dosyadaki hiçbir bölgeyi adlandırmayan bir --zone değeri hatadır, sessizce yok sayılan bir işlem değil.

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

Canlı durumu çekme

Mevcut canlı DNS yapılandırmasından bir nexdns.yaml dosyası oluşturun:

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

Ortam değişkeni değiştirme

Yapılandırma dosyanızda ${VARIABLE} söz dizimini kullanın. CLI, uygulama sırasında ortam değişkenlerini değiştirir ve yapılandırmaları ortamlar arasında yeniden kullanmayı kolaylaştırır:

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

Webhook'lar

Bölgelerinizin ürettiği olaylara bir uç nokta abone edin ve bu abonelikleri terminalden yönetin. Webhook'lar Pro ve üzeri planlarda kullanılabilir; API anahtarının webhooks.read ve webhooks.write izin kapsamlarına sahip olması gerekir.

Uç nokta abone etme

İmzalama gizli anahtarı yalnızca oluşturma sırasında bir kez yazdırılır ve sonradan alınamaz – alıcınızın okuyabileceği bir yerde saklayın. Her teslimat, bu gizli anahtarla hesaplanan bir HMAC imzası taşır; böylece alıcı, isteğin gerçekten bizden geldiğini doğrulayabilir.

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

Kullanılabilir olaylar

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

Abonelikleri inceleme

show, en son on teslimat denemesini durum koduyla birlikte, başarısız olan varsa hatasıyla ekler – bu genellikle yanlış bir URL ile veriyi reddeden bir alıcıyı ayırt etmeye yeter.

nexdns webhook list
nexdns webhook show <webhook-id>

Test olayı gönderme

Bir test teslimatını kuyruğa alır. Buradaki başarı, platformun olayı kabul ettiği anlamına gelir; uç noktanızın yanıt verdiği anlamına gelmez – sonucu nexdns webhook show ile okuyun.

nexdns webhook test <webhook-id>

Aboneliği değiştirme veya duraklatma

Yalnızca değişeni geçirin; komut mevcut aboneliği okur ve geri kalanı yeniden gönderir. Uç noktayı silmeden teslimatları durdurmak için --active=false, onay istemi olmadan silmek için --force kullanın.

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

Hesap ve yapılandırma

Bir jetonun hangi hesaba ait olduğunu, hangi planı taşıdığını ve hangi API anahtarlarının bulunduğunu görün.

nexdns account info
nexdns account api-keys

Kalıcı ayarlar

Yapılandırma dosyası beş ayar tutar – api-url, token, output, color ve timeout – ve hepsi CLI üzerinden okunup yazılabilir. config view, jetonun nereden geldiği dahil etkin yapılandırmayı yazdırır.

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

Ortam değişkenleri

Her ayarın bir ortam değişkeni de vardır; CI ortamları genellikle bunu kullanır. NEXDNS_CONFIG, alternatif bir yapılandırma dosyasını gösterir; tek makineden birden fazla hesap yönetildiğinde işe yarar.

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

Kayıtlı jetonu kaldırma

Jetonu yapılandırma dosyasından temizler. Dosyanın kendisi ve içinde kayıtlı API URL'si yerinde kalır.

nexdns auth logout

Kabuk tamamlama

Tamamlama betikleri bash, zsh, fish ve PowerShell için oluşturulur.

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

Betik yazma ve CI

CLI, otomatik iş akışlarından çalıştırılmak üzere tasarlanmıştır: her hata ayrı bir çıkış kodudur, istemler asılı kalmak yerine reddedilir ve istenmedikçe yıkıcı hiçbir işlem gerçekleşmez.

Çıkış kodları

Yanlış yazılmış bir alt komut, yardım metnini yazdırıp başarılı sayılmak yerine 2 koduyla çıkar; böylece bir iş akışındaki yazım hatası tamamlanmış bir işlem gibi görünemez.

Onay istemleri

Yıkıcı komutlar işlem yapmadan önce sorar. Terminal olmadığında – yani her CI ortamında – istem reddedilir ve komut hiçbir şeyi değiştirmeden 0 koduyla çıkar; bu nedenle gerçekten istediğinizde --force geçirin.

Eskiden sessizce geçen hatalar

• nexdns.yaml içinde çözümlenemeyen bir ${VAR}, metni olduğu gibi bir kayda yazmak yerine çalışmayı durdurur ve değeri olmayan her değişkeni belirtir.
• Dosyadaki hiçbir bölgeyi adlandırmayan bir --zone değeri hatadır.
• zone check, bir yayılım kontrolü başarısız olduğunda sıfırdan farklı bir kodla çıkar.
• apply --confirm, herhangi bir işlem başarısız olduğunda sıfırdan farklı bir kodla çıkar ve kaç tanesinin başarısız olduğunu bildirir.

Hız sınırları ve toplu işler

API istek bütçesi hesap ve plan başınadır ve kayan bir dakikalık pencerede işler. CLI, bütçeyi her yanıttan okur ve bütçeyi aşacağı noktada pencerenin yenilenmesini bekler; böylece büyük bir içe aktarma kayıt kaybetmeden eksiksiz tamamlanır, yalnızca daha uzun sürer. Bir bölgenin ne sıklıkta ad sunucusu grubu değiştirebileceği gibi daha uzun pencereli bir sınır ise beklenmez, bildirilir.

Docker

CLI, bir Docker imajı olarak kullanılabilir. API jetonunuzu NEXDNS_TOKEN ortam değişkeni aracılığıyla geçirin.

Komut çalıştırma

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

Bölge dosyası içe aktarma

Bölge dosyalarını konteynere aktarmak için yerel bir dizin bağlayın:

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

Genel bayraklar

Aşağıdaki bayraklar tüm komutlarda kullanılabilir:

Bunların her biri bir ortam değişkeni de okur: NEXDNS_TOKEN, NEXDNS_API_URL, NEXDNS_TIMEOUT ve NEXDNS_CONFIG. NO_COLOR, --color ne olursa olsun rengi kapatır.

Terraform

NexDNS Terraform sağlayıcısı, bölgeleri ve kayıtları Terraform kaynakları olarak yönetmenizi sağlar. Sağlayıcıyı Terraform Registry'den kurun ve API jetonunuzla yapılandırın.

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 entegrasyonu

DNSControl, Stack Overflow tarafından geliştirilen bir DNS-as-code aracıdır. Bölgelerinizi bildirimsel olarak yönetmek için NexDNS sağlayıcısını kullanın. Sağlayıcı, DNSControl 4.46.0 ve sonrasında yer alır.

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, GitHub tarafından geliştirilen bir DNS-as-code aracıdır. NexDNS sağlayıcısını kurun ve OctoDNS yapılandırmanızda kaynak veya hedef olarak yapılandırın.

Sağlayıcıyı kurma

pip install octodns-nexdns

Dosya 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

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