Documentation

Welcome to LuaDNS!

LuaDNS is a DNS hosting platform which allows easy DNS management (domains and records) and deployment through Git.

Getting Started

In order to use LuaDNS service you'll need a LuaDNS account and a Git repository.

  1. Sign up for a free LuaDNS account here: https://api.luadns.com/signup
  2. Currently we are supporting the following Git hosting services:

GitHub Quickstart

Bitbucket Quickstart

Account Configuration

After account creation and email validation, you'll need to specify your Git repository (Account -> Git repository).

Example Git URLs:

  • GitHub public repository: https://github.com/joe/dns.git
  • Bitbucket private repository: git@bitbucket.org:joe/dns.git

Automatic rebuild and deployment

LuaDNS needs to know when you modify your domains configurations in your Git repository and this it's available through HTTP POST notifications mechanism.

To enable automatic zone rebuild and deployment, repository commit hooks has to be configured:

  • GitHub: Settings -> Webhooks -> Add webhook (Triggers: Repository push)
  • Bitbucket: Settings -> Webhooks -> Add webhook (Events: Just the push event)

Notification URL respects the following format:

https://api.luadns.com/notifications/**API-TOKEN**/push

(You'll find your API-TOKEN under Acccount settings.)

Manual notifications

If you want to launch a manual rebuild of your zones, use curl command to achieve this task, example (replace API-TOKEN with your API toke):

vitalie@black:~$ curl -X POST https://api.luadns.com/notifications/API-TOKEN/push

Repository permissions

When using private repositories on make sure that luadns user has read access to repository.

Example repository

An example repository can be found here: https://github.com/luadns/dns

Lua Zone File Format

Users have the option to store their configurations in a standard Bind format or to use more powerful Lua format.

Resource Records

LuaDNS supports most common Resource Records:

A, AAAA, ALIAS, CNAME, FORWARD, MX, NS, PTR, REDIRECT, SOA, SPF, SRV, SSHFP, TXT

A Record

A Record Syntax:

-- @name  = relative name
-- @ip    = IPv4 address
-- @ttl   = TTL (default: user default TTL)
a(name, ip, ttl)

Example:

a("mail", "1.2.3.4")

AAAA Record

AAAA Record Syntax:

-- @name  = relative name
-- @ip    = IPv6 address
-- @ttl   = TTL (default: user default TTL)
aaaa(name, ip, ttl)

Example:

aaaa("mail", "2001:4860:4860::8888")

ALIAS Record

ALIAS Record Syntax:

-- @name   = relative name
-- @target = target host (fqdn)
-- @ttl    = TTL (default: user default TTL)
alias(name, target, ttl)

This record is suited to solve the DNS restriction with CNAME on apex (root, naked) domains.

The system creates A and AAAA records for name with the IP addresses found while resolving target. The target is polled periodically and the A and AAAA records are updated when changes are detected.

Example:

alias(_a, "myapp.herokuapp.com")

CNAME Record

CNAME Record Syntax:

-- @name    = relative name
-- @alias   = alias (fqdn)
-- @ttl     = TTL (default: user default TTL)
cname(name, alias, ttl)

Example:

cname("www", "example.com")

FORWARD Record

The FORWARD pseudo record configures LuaDNS mail servers to accept and forward emails to an external email provider.

FORWARD Record Syntax:

-- @from    = mailbox name (without domain)
-- @to      = recipient (email address)
-- @ttl     = cache TTL (default: user default TTL)
forward(from, to, ttl)

Example:

-- File: example.com.lua
-- _a variable is set by the system to zone name
-- _a = "example.com"

-- Forward mailbox `joe@example.com` to `bob@mailinator.com`.
forward("bob", "bob@mailinator.com")

-- Catch-all forward.
-- Forward all unmatched mailboxes to alice@mailinator.com.
forward("*", "alice@mailinator.com")

MX Record

MX Record Syntax:

-- @name      = relative name
-- @exchanger = mail exchanger(fqdn)
-- @prio      = priority (default: 0)
-- @ttl       = TTL (default: user default TTL)
mx(name, exchanger, prio, ttl)

Example:

-- File: example.com.lua
-- _a variable is set by the system to zone name
-- _a = "example.com"
mx(_a, "aspmx.l.google.com", 10)

NS Record

NS Record Syntax:

-- @name    = relative name
-- @server  = name server (fqdn)
-- @ttl     = TTL (default: user default TTL)
ns(name, server, ttl)

Name servers are automatically added for each zone found in the repository, you don't have to specify them.

Example:

-- File: example.com.lua
-- delegate uk.example.com to uk-ns1.example.com, uk-ns2.example.com name servers
ns("uk", "uk-ns1.example.com")
ns("uk", "uk-ns2.example.com")

PTR Record

PTR Record Syntax:

-- @name  = relative name
-- @host  = host name (fqdn)
-- @ttl   = TTL (default: user default TTL)
ptr(name, host, ttl)

Example:

-- File: 1.168.192.in-addr.arpa.lua
ptr("1", "server.example.com")
-- File: 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.lua
ptr("1", "localhost.example.com")

REDIRECT Record

The REDIRECT pseudo record configures the DNS servers and HTTP redirection service to allow easy HTTP redirections.

REDIRECT Record Syntax:

-- @name   = relative name
-- @target = target url
-- @mode   = redirect mode (0=relative, 1=exact, 2=frame, default: 0)
-- @ttl    = cache TTL (default: user default TTL)
redirect(name, target, mode, ttl)

The mode parameter specifies how the name is going to be redirected to target:

  • 0 - relative mode, server appends the path and query string to target and issues a 301 redirect
  • 1 - exact mode, server issues a 301 redirect to target URL
  • 2 - frame mode, server returns a HTML page which loads the the target URL in a frame

Example:

-- File: example.com.lua
-- _a variable is set by the system to zone name
-- _a = "example.com"

-- Default mode (301 redirect)
-- Redirect http://example.com/* to http://www.example.com/*
--   http://example.com/foo => http://www.example.com/foo
--   http://example.com/foo?param=bar => http://www.example.com/foo?param=bar
redirect(_a, "http://www.example.com/")

-- Exact mode (301 redirect)
-- Redirect http://app.example.com/* to https://secure.example.com/home
--   http://app.example.com/foo => https://secure.example.com/home
--   http://app.example.com/foo?param=bar => https://secure.example.com/home
redirect("app", "https://secure.example.com/home", 1)

-- Frame mode
-- Returns a page which loads http://www.example.net/webmail in a frame
--   http://webmail.example.com/ => http://www.example.net/webmail
redirect("webmail", "http://www.example.net/webmail", 2)

SOA Record

SOA record it's created by automatically by the system, you don't have to specify one.

SPF Record

SPF Record Syntax:

-- @name    = relative name
-- @text    = text
-- @ttl     = TTL (default: user default TTL)
spf(name, text, ttl)

Example:

-- File: example.com.lua
-- _a variable is set by the system to zone name
-- _a = "example.com"
spf(_a, "v=spf1 a mx include:_spf.google.com ~all")

SRV Record

SRV Record Syntax:

-- @name    = relative name
-- @target  = host name(fqdn)
-- @port    = port number
-- @prio    = prio (default: 0)
-- @weight  = weight (default: 0)
-- @ttl     = TTL (default: user default TTL)
srv(name, target, port, prio, weight, ttl)

Example:

-- File: example.com
srv("_sip._tcp", "sipserver.example.com", 5060)

SSHFP Record

SSHFP Record Syntax:

-- @name        = relative name
-- @algorithm   = algorithm number (1=RSA, 2=DSA, 3=ECDSA)
-- @fp_value    = fingerprint (presented in hex)
-- @fp_type     = fingerprint type (1=SHA-1, 2=SHA-256, default: 1)
-- @ttl         = TTL (default: user default TTL)
sshfp(name, algorithm, fp_value, fp_type, ttl)

Example:

-- File: example.com
-- Run ssh-keygen tool to print the SSHFP fingerprint resource record:
-- $ ssh-keygen -f /etc/ssh/ssh_host_rsa_key.pub -r myserver
-- myserver IN SSHFP 1 1 34b1436fa3d5cf235563efe42a9223ae1c6b486e
-- $ ssh-keygen -f /etc/ssh/ssh_host_dsa_key.pub -r myserver
-- myserver IN SSHFP 2 1 0392244baae593a996b354f473b350c4c2afe9f3
sshfp("myserver", 1, "34b1436fa3d5cf235563efe42a9223ae1c6b486e")
sshfp("myserver", 2, "0392244baae593a996b354f473b350c4c2afe9f3")

TXT Record

TXT Record Syntax:

-- @name    = relative name
-- @text    = text
-- @ttl     = TTL (default: user default TTL)
txt(name, text, ttl)

Example:

-- File: example.com.lua
-- _a variable is set by the system to zone name
-- _a = "example.com"
txt(_a, "google-site-verification=vEj1ZcGtXeM_UEjnCqQEhxPSqkS9IQ4PBFuh48FP8o4")

Wildcard Record

Wildcard records are supported, example usage:

-- File: example.com.lua
-- Variable _a is replaced with zone name by LuaDNS
-- _a = "example.com"

-- *.example.com resolves to 1.2.3.4
a("*", "1.2.3.4")

-- Email for *.uk.example.com is handled by mx-eu.example.com
a("*.uk", concat("mx-eu", _a))

User default TTL

In a Resource Records definition user default TTL (default: 3600 seconds) is used when TTL is not specified, you can change your default TTL from the account settings page.

System Functions

  • concat(str1, str2) - Concatenates two names using dot, used usually to construct host names.
    Example usage: mx(_a, concat("mail", _a))
  • slave(name, ip, ttl) - defines a slave for the current zone, ip is an IPv4 address used to configure ACLs and to send NOTIFY messages. Required A and NS records are added automatically. To add multiple servers invoke function multiple times. Please, configure your ACLs on slave servers to use axfr.luadns.net or IP 78.47.238.210.
    Example: slave("ns1", "1.1.1.1") or slave("ns1.third-party-ns.com", "2.2.2.2")

System Variables

  • _a - variable is set by compiler to zone name (extracted from file name).
    Example: _a = "example.com" for configuration file example.com.lua.

Comments

Comments are simple Lua comments:

A comment starts with a double hyphen (--) anywhere outside a string. If the text immediately after -- is not an opening long bracket, the comment is a short comment, which runs until the end of the line. Otherwise, it is a long comment, which runs until the corresponding closing long bracket. Long comments are frequently used to disable code temporarily.

Templates

Templates are simulated through Lua functions. Global functions/templates should be grouped in templates.lua file in your repository. Functions defined here are available to each zone.

Example (templates.lua):

function google_app(domain)
  -- Configure Google Apps mail exchangers
  mx(domain, "aspmx.l.google.com", 5)
  mx(domain, "alt1.aspmx.l.google.com", 10)
  mx(domain, "alt2.aspmx.l.google.com", 10)
  mx(domain, "aspmx2.googlemail.com", 20)
  mx(domain, "aspmx3.googlemail.com", 20)

  -- Additional Google Apps records
  cname(concat("calendar", domain), "ghs.google.com")
  cname(concat("docs", domain), "ghs.google.com")
  cname(concat("mail", domain), "ghs.google.com")
  cname(concat("sites", domain), "ghs.google.com")

  -- Configure SPF
  txt(domain, "v=spf1 a mx include:_spf.google.com ~all")
end

Domain aliases

When dealing with multiple domains sharing the same configuration to avoid cluttering the repository with zone files, LuaDNS allows domain aliases to be specified in .clones files:

Example:

vitalie@black:~/workspace/luadns/examples$ ls -al example.com.*
-rw-r--r-- 1 vitalie vitalie  25 2012-04-18 00:31 example.com.clones
-rw-r--r-- 1 vitalie vitalie 266 2012-03-01 12:46 example.com.lua

vitalie@black:~/workspace/luadns/examples$ cat example.com.clones
example.org
example.info

The system will generate the same set of records for example.org, example.info mirroring records from example.com.

Zone transfers (AXFR)

LuaDNS can be configured to function together with external slave servers. To configure a slave server use slave function. Example:

-- File: example.com.lua
-- Zone: example.com

-- Add two slave servers (ns1.example.com, ns2.example.com)
-- required A and NS records are created automatically
slave("ns1", "1.1.1.1")
slave("ns2", "1.1.1.2")

-- Add two external slave servers
-- required NS records are created automatically
slave("ns1.third-party-ns.com", "2.2.2.1")
slave("ns1.third-party-ns.com", "2.2.2.2")

-- Please, configure your ACLs on slave servers
-- to use axfr.luadns.net or IP 78.47.238.210.

Examples

Basic Example

-- File: example.com.lua
-- Variable _a is replaced with zone name by LuaDNS
-- _a = "example.com"

-- A Records
a(_a, "1.2.3.4")

-- CNAME Records
cname("www", _a)

-- MX Records
mx(_a, _a)

Advanced Example

-- File: example.com.lua
-- Zone: example.com
-- Variable _a is replaced with zone name by LuaDNS
-- _a = "example.com"

-- A records
a(_a, "1.2.3.4")

-- CNAME records
cname("www", _a)
cname("ftp", _a)

-- Templates
google_app(_a)

-- Add 2 slave servers (ns1.example.com, ns2.example.com)
-- required A and NS records are created automatically
slave("ns1", "1.1.1.1")
slave("ns2", "1.1.1.2")

Bind Zone File Format

LuaDNS has native support for Bind zone files, add Bind files to your git repository (use .bind extension) and push modifications with git (git push origin master).

Your configuration files will be parsed, validated and deployed to our name servers, shortly you'll receive from us an email with status of the deployment.

Examples:

Information on Bind zone file format is available here: http://www.zytrax.com/books/dns/ch8

Supported directives

  • $TTL
  • $ORIGIN

Supported Records

  • A
  • AAAA
  • CNAME
  • MX
  • NS
  • PTR
  • SOA
  • SPF
  • SRV
  • SSHFP
  • TXT

Vanity Name Servers

There are many situations when you need to use your vanity name servers with your domains, example:

  • ns1.yourcompany.com
  • ns2.yourcompany.com
  • ns3.yourcompany.com
  • ns4.yourcompany.com
  • ns5.yourcompany.com

To use this feature edit your LuaDNS account, set vanity name servers (one name server per line) and trigger a new deployment with git push.

Powered by Jekyll