Manipulate DNS records on various DNS providers in a standardized way.
Clone or download
adferrand Merge pull request #339 from AnalogJ/test-refactoring
Refactor tests in a python package
Latest commit 18296a4 Jan 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Revert back to system git, it is better integrated Oct 31, 2018
.pytest_cache Clean Oct 17, 2018
examples Added support for dehydrated HOOK_CHAIN Dec 30, 2018
lexicon Merge branch 'master' into test-refactoring Jan 16, 2019
tests Merge branch 'master' into test-refactoring Jan 16, 2019
.coveralls.yml fix token. Apr 5, 2016
.gitignore Clean repository Jan 6, 2019
.pylintrc Disable code duplication detection, not really relevant for lexicon w… Nov 19, 2018
CODEOWNERS add Hetzner Robot provider Dec 4, 2018
CONTRIBUTING.md Continue cleaning pylint in test area Jan 8, 2019
Dockerfile letsencrypt.sh was renamed to dehydrated. Oct 8, 2016
LICENSE Initial commit Feb 2, 2016
MANIFEST.in added VERSION file not _version.py as its better for thrid party tool… Feb 17, 2016
README.md Update README.md Jan 8, 2019
SPECIFICATION.md Update SPECIFICATION.md May 12, 2018
VERSION (v3.0.8) Automated packaging of release by CapsuleCD Jan 3, 2019
capsule.yml cleanup branches when merged. Nov 4, 2018
lexicon.1 Adds man page Oct 19, 2018
logo.svg adding logo from nounproject, and added reference in the license sect… Jul 12, 2018
optional-requirements.txt add Hetzner Robot provider Dec 4, 2018
requirements.txt Correct pylint errors. Optimize tests. Oct 31, 2018
setup.cfg add pip package requirements. Feb 5, 2016
setup.py add Hetzner Robot provider Dec 4, 2018
test-requirements.txt Fix dev setup Dec 5, 2018
test.py python 3 syntax error when running tests Dec 6, 2017
tox.ini Correct pylint invocation Jan 16, 2019

README.md

lexicon_view

lexicon

Manipulate DNS records on various DNS providers in a standardized/agnostic way.

Circle CI Coverage Status Docker Pulls PyPI PyPI GitHub license

Introduction

Lexicon provides a way to manipulate DNS records on multiple DNS providers in a standardized way. Lexicon has a CLI but it can also be used as a python library.

Lexicon was designed to be used in automation, specifically letsencrypt.

Providers

Only DNS providers who have an API can be supported by lexicon.

The current supported providers are:

Potential providers are as follows. If you would like to contribute one, follow the CONTRIBUTING.md and then open a pull request.

  • Aliyun.com
  • Azure DNS (docs)
  • AHNames (docs)
  • DurableDNS (docs) Can't set TXT records
  • cyon.ch
  • Dyn (docs) 💵 requires paid account
  • Dynu
  • DirectAdmin
  • EntryDNS (docs) 💵 requires paid account
  • FreeDNS (docs)
  • Host Virtual DNS (docs) 💵 requires paid account
  • HostEurope
  • Infoblox NIOS
  • ironDNS (docs) 💵 requires paid account
  • ISPConfig
  • InternetX autoDNS (docs)
  • Knot DNS
  • KingHost
  • Liquidweb (docs) 💵 requires paid account
  • Loopia (docs) 💵 requires paid account
  • Mythic Beasts(docs)
  • NFSN (NearlyFreeSpeech) (docs) 💵 requires paid account
  • RFC2136 (docs)
  • Servercow (docs)
  • selectel.com
  • TELE3 (docs)
  • UltraDNS (docs) 💵 requires paid account
  • UnoEuro API
  • VSCALE
  • WorldWideDns (docs) 💵 requires paid account
  • Zerigo (docs) 💵 requires paid account
  • Zoneedit (docs)
  • Zilore (docs)
  • Any others I missed

Setup

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 provider specific dependencies separately:

pip install dns-lexicon[route53]

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]

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
                          specify token used authenticate

Using the lexicon CLI is pretty simple:

# setup provider environmental variables:
export LEXICON_CLOUDFLARE_USERNAME="myusername@example.com"
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"

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

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 environmental variables.

Letsencrypt Instructions

Lexicon has an example dehydrated hook file that you can use for any supported provider. All you need to do is set the PROVIDER env variable.

PROVIDER=cloudflare dehydrated --cron --hook dehydrated.default.sh --challenge dns-01

Lexicon can also be used with Certbot and the included Certbot hook file (requires configuration).

TroubleShooting & Useful Tools

There is an included example Dockerfile that can be used to automatically generate certificates for your website.

ToDo list

  • Create and Register a lexicon pip package.
  • Write documentation on supported environmental variables.
  • Wire up automated release packaging on PRs.
  • Check for additional dns hosts with apis (from fog, dnsperf, libcloud)
  • Get a list of Letsencrypt clients, and create hook files for them (letsencrypt clients)

Contributing Changes.

If the DNS provider you use is not already available, please consider contributing by opening a pull request and following the CONTRIBUTING.md

License

References

tox