DNS-Lexicon Release 3.7.0
Total Page:16
File Type:pdf, Size:1020Kb
DNS-Lexicon Release 3.7.0 Aug 09, 2021 Table of Contents 1 Introduction 1 1.1 Why using Lexicon?...........................................1 1.2 Supported providers...........................................2 2 User guide 5 2.1 Installation................................................5 2.2 Usage...................................................6 2.3 Configuration...............................................7 2.4 Integration................................................8 3 Configuration reference 9 3.1 Providers options.............................................9 3.2 Passing provider options to Lexicon................................... 16 3.3 Passing general options to Lexicon................................... 17 3.4 The auto provider............................................ 17 4 Developer guide 19 4.1 Potential providers............................................ 19 4.2 Setup a development environment.................................... 20 4.3 Adding a new DNS provider....................................... 20 4.4 Testing your provider........................................... 21 4.5 CODEOWNERS file........................................... 23 5 Provider specification 25 5.1 General.................................................. 25 5.2 API Operations.............................................. 25 i ii CHAPTER 1 Introduction 1.1 Why using Lexicon? Lexicon provides a way to manipulate DNS records on multiple DNS providers in a standardized way. Lexicon can be used as: • a CLI tool: # Create a TXT entry in domain.net zone hosted by CloudFlare lexicon cloudflare create domain.net TXT --name foo --content bar • or a Python library: # Create a TXT entry in domain.net zone hosted by CloudFlare from lexicon.client import Client from lexicon.config import ConfigResolver action={ "provider_name":"cloudflare", "action":"create", "domain":"domain.net", "type":"TXT", "name":"foo", "content":"bar", } config= ConfigResolver().with_env().with_dict(action) Client(config).execute() Lexicon was designed to be used in automation, specifically letsencrypt. • Generating Intranet & Private Network SSL Certificates using Lets Encrypt & Lexicon 1 DNS-Lexicon, Release 3.7.0 1.2 Supported providers Only DNS providers who have an API can be supported by lexicon. The current supported providers are: • Aliyun.com • AuroraDNS • AWS Route53 • Azure DNS • Cloudflare • ClouDNS • CloudXNS • ConoHa • Constellix • DigitalOcean • Dinahosting • DirectAdmin • DNSimple v1, v2 • DnsMadeEasy • DNSPark • DNSPod • Dreamhost • Dynu • EasyDNS • Easyname • EUserv • ExoScale • Gandi RPC (old)/ LiveAPI • Gehirn • Glesys • GoDaddy • Google Cloud DNS • Gransy (sites subreg.cz, regtons.com and regnames.eu) • Hover • Hurricane Electric DNS • Hetzner • Infoblox 2 Chapter 1. Introduction DNS-Lexicon, Release 3.7.0 • Infomaniak • Internet.bs • INWX • Joker.com • Linode • Linode v4 • LuaDNS • Memset • Mythic Beasts (v2 API) • Njalla • Namecheap • Namesilo • Netcup • NFSN (NearlyFreeSpeech) • NS1 • OnApp • Online • OVH • Plesk • PointHQ • PowerDNS • Rackspace • Rage4 • RcodeZero • RFC2136 • Sakura Cloud by SAKURA Internet Inc. • SafeDNS by UKFast • SoftLayer • Transip • UltraDNS • Vercel • Vultr • Yandex • Zilore • Zonomi 1.2. Supported providers 3 DNS-Lexicon, Release 3.7.0 4 Chapter 1. Introduction CHAPTER 2 User guide 2.1 Installation Warning: It is strongly advised with pip to install Lexicon in a Python virtual environment, in order to avoid interference between Python modules preinstalled on your system as OS packages and modules installed by pip (see https://docs.python-guide.org/dev/virtualenvs/). To use lexicon as a CLI application, do the following: $ pip install dns-lexicon Some providers (like Route53 and TransIP) require additional dependencies. You can install the provider specific dependencies separately: $ pip install dns-lexicon[route53] To install lexicon with the additional dependencies of every provider, do the following: $ pip install dns-lexicon[full] You can also install the latest version from the repository directly. $ pip install git+https://github.com/AnalogJ/lexicon.git and with Route 53 provider dependencies: $ pip install git+https://github.com/AnalogJ/lexicon.git#egg=dns-lexicon[route53] Note: As an alternative you can also install Lexicon using the OS packages available for major Linux distributions (see lexicon or dns-lexicon package in https://pkgs.org/download/lexicon). 5 DNS-Lexicon, Release 3.7.0 2.2 Usage $ lexicon -h usage: lexicon[-h][--version][--delegated DELEGATED] {cloudflare,cloudxns,digitalocean,dnsimple,dnsmadeeasy,dnspark, ,!dnspod,easydns,luadns,namesilo,nsone,pointhq,rage4,route53,vultr,yandex,zonomi} ... Create, Update, Delete, List DNS entries positional arguments: {cloudflare,cloudxns,digitalocean,dnsimple,dnsmadeeasy,dnspark,dnspod,easydns, ,!luadns,namesilo,nsone,pointhq,rage4,route53,vultr,yandex,zonomi} specify the DNS provider to use cloudflare cloudflare provider cloudxns cloudxns provider digitalocean digitalocean provider ... rage4 rage4 provider route53 route53 provider vultr vultr provider yandex yandex provider zonomi zonomi provider optional arguments: -h, --help show this help message and exit --version show the current version of lexicon --delegated DELEGATED specify the delegated domain $ lexicon cloudflare -h usage: lexicon cloudflare[-h][--name NAME][--content CONTENT][--ttl TTL] [--priority PRIORITY][--identifier IDENTIFIER] [--auth-username AUTH_USERNAME] [--auth-token AUTH_TOKEN] {create,list,update,delete} domain {A,AAAA,CNAME,MX,NS,SPF,SOA,TXT,SRV,LOC} positional arguments: {create,list,update,delete} specify the action to take domain specify the domain, supports subdomains as well {A,AAAA,CNAME,MX,NS,SPF,SOA,TXT,SRV,LOC} specify the entry type optional arguments: -h, --help show this help message and exit --name NAME specify the record name --content CONTENT specify the record content --ttl TTL specify the record time-to-live --priority PRIORITY specify the record priority --identifier IDENTIFIER specify the record for update or delete actions --auth-username AUTH_USERNAME specify email address used to authenticate --auth-token AUTH_TOKEN (continues on next page) 6 Chapter 2. User guide DNS-Lexicon, Release 3.7.0 (continued from previous page) specify token used authenticate specify the entry type optional arguments: -h, --help show this help message and exit --name NAME specify the record name --content CONTENT specify the record content --ttl TTL specify the record time-to-live --priority PRIORITY specify the record priority --identifier IDENTIFIER specify the record for update or delete actions --auth-username AUTH_USERNAME specify email address used to authenticate --auth-token AUTH_TOKEN specify token used authenticate Using the lexicon CLI is pretty simple: # setup provider environmental variables: export LEXICON_CLOUDFLARE_USERNAME="[email protected]" export LEXICON_CLOUDFLARE_TOKEN="cloudflare-api-token" # list all TXT records on cloudflare lexicon cloudflare list example.com TXT # create a new TXT record on cloudflare lexicon cloudflare create www.example.com TXT --name="_acme-challenge.www.example.com. ,!" --content="challenge token" # delete a TXT record on cloudflare lexicon cloudflare delete www.example.com TXT --name="_acme-challenge.www.example.com. ,!" --content="challenge token" lexicon cloudflare delete www.example.com TXT --identifier="cloudflare record id" 2.3 Configuration 2.3.1 Authentication Most supported DNS services provide an API token, however each service implements authentication differently. Lexicon attempts to standardize authentication around the following CLI flags: • --auth-username - For DNS services that require it, this is usually the account id or email address • --auth-password - For DNS services that do not provide an API token, this is usually the account password • --auth-token - This is the most common auth method, the API token provided by the DNS service You can see all the --auth-* flags for a specific service by reading the DNS service specific help: lexicon cloudflare -h 2.3. Configuration 7 DNS-Lexicon, Release 3.7.0 2.3.2 Environmental variables Instead of providing authentication information via the CLI, you can also specify them via environmental variables. Every DNS service and auth flag maps to an environmental variable as follows: LEXICON_{DNS Provider Name}_{Auth Type} So instead of specifying --auth-username and --auth-token flags when calling lexicon cloudflare ..., you could instead set the LEXICON_CLOUDFLARE_USERNAME and LEXICON_CLOUDFLARE_TOKEN en- vironmental variables. If you’ve got a subdomain delegation configured and need records configured within that (eg, you’re try- ing to set test.foo.example.com where foo.example.com is configured as a separate zone), set LEXICON_DELEGATED to the delegated domain. LEXICON_DELEGATED=foo.example.com 2.3.3 TLD cache The tldextract library is used by Lexicon to find the actual domain name from the provided FQDN (eg. domain. net is the actual domain in www.domain.net). Lexicon stores tldextract cache by default in ~/ .lexicon_tld_set where ~ is the current user’s home directory. You can change this path using the LEXICON_TLDEXTRACT_CACHE environment variable. For instance, to store tldextract cache in /my/path/to/tld_cache, you can invoke Lexicon like this from a Linux shell: LEXICON_TLDEXTRACT_CACHE=/my/path/to/tld_cache lexicon myprovider create www.example. ,!net TXT ... 2.4 Integration Lexicon can be integrated with various tools and process to help handling DNS records. 2.4.1 Let’sEncrypt