Skip to content

Latest commit

 

History

History
122 lines (103 loc) · 4.97 KB

README.md

File metadata and controls

122 lines (103 loc) · 4.97 KB
Raw

namectl

Simple controller that reads a DNS configuration for your domains and uses it to reconcile with the domain registrar to keep your actual records up to date with the local config. Supports multiple accounts within and across multiple registrars at once.

Dynamic DNS for both IPv4 and IPv6 are supported through using the ipify API to fetch the machine's IP.

Installation & use

# From this folder
pip install -e .

# Run namectl using the config at "path/to/config.yaml", reconcile every 5 minutes 
python -m namectl -c path/to/config.yaml -p 300

The DNS config is re-read on every reconciliation attempt. You can change/fix the config and the changes will be used for the next reconciliation.

Configuration

namectl configuration files specify a list of accounts which can be used to reconcile the desired records specified for each of the domains.

Configuration reference

Field Type Description
accounts list Top level key for account configuration
accounts[].name string Name of the account
accounts[].provider string Name of the DNS provider to use for this account
accounts[].credentials dict Credential config for this account. Check the provider for information on what's required
domains list Top level key for domain configuration
domains[].name string The name of the domain
domains[].account string The name of the account to use when reconciling records for this domain
domains[].records list List of desired DNS records for this domain
domains[].records[].hostname string Subdomain/hostname of the record
domains[].records[].type string DNS record type
domains[].records[].content string The desired content of the DNS record
domains[].records[].ttl int The desired TTL of the DNS record
domains[].records[].priority int For types that support it, the desired priority of the DNS record
domains[].records[].dynamic bool If true, the DNS record content will dynamically be set to the machine's IPv4 if the record type is A, or the IPv6 if the record type is AAAA
domains[].ignored_records list List of existing DNS records that should be ignored by namectl
domains[].ignored_records.hostname string Subdomain/hostname of the record to ignore
domains[].ignored_records.type string Type of the record to ignore. If set, both hostname and type must match for namectl to ignore the record

Example configuration

# List of all accounts
accounts:
- name: my-pb-acct
  provider: porkbun
  credentials:
    key:
      value: "pk1_xxxxxxxxx" # specify the API key directly
    secret:
      fromEnv: "PORKBUN_APISECRET" # read the API secret from the env variable PORKBUN_APISECRET

# List of domains to manage records for
domains:
- name: domain.com
  account: my-pb-acct # domain.com should be updated with the my-pb-acct account
  # List of records to reconcile
  records:
  # A domain.com -> 1.2.3.4
  # TTL defaults to 600
  - hostname: ""
    type: A
    answer: "1.2.3.4"
  # A domain.com -> dynamically updated IP of machine
  - hostname: ""
    type: A
    dynamic: true
  # ALIAS alias.domain.com -> domain.com
  - hostname: "alias"
    type: ALIAS
    answer: "domain.com"
    ttl: 1200
  # NS sub.domain.com -> ns.someother.io
  - hostname: "sub"
    type: NS
    answer: "ns.someother.io"
    ttl: 86400
  # TXT _note.domain.com -> "hi there"
  - hostname: "_note"
    type: TXT
    answer: "hi there"
  # List of records to ignore (e.g. manually or externally managed records)
  ignored_records:
  - hostname: "_acme_challenge"
    type: TXT
  - hostname: "manual"

Providers

Only porkbun is supported as a provider. This is because it's the only registrar I have domains with as of making this tool. namectl providers are pluggable, however, so you could make a provider if you wanted to. See dns_provider.py for information on what's required of a provider.

porkbun

This provider will not reconcile NS records on the bare domain, this is because Porkbun seems to treat NS records on your domains as inherently different to any other records for some reason. It just doesn't work with how namectl is designed. You'll have to specify the authoritative name servers through the web UI (sorry!)

Credentials configuration reference

Field Type Description
key dict Top level key for configuring the API key
key.fromEnv string Name of the environment variable to read the API key from. This takes precedence over key.value
key.value string The API key to use
secret dict Top level secret for configuring the API secret
secret.fromEnv string Name of the environment variable to read the API secret from. This takes precedence over secret.value
secret.value string The API secret to use