Documentation
Welcome to LuaDNS!
LuaDNS is a DNS hosting platform which allows easy DNS management (domains and records) and deployment through Git (optional).
Getting Started
In order to use this service you'll need a LuaDNS account, sign up for a free account here:
https://app.luadns.com/users/register
Git Integration
The git integration is a convenient way to manage your DNS settings, it allows you to keep all your zones and records in the repository and deploy changes automatically to our name servers when you are pushing the changes with git, see example repository.
After each git push
our build system will pull DNS settings from
your git repository. Your configuration files are parsed, validated and
then DNS zones and records are distributed to our name servers.
You'll receive an email with the build status.
To use git integration, you need to follow this steps:
- Set the repository URL in your the settings page.
- Configure your repository to grant read-only access when accessed with your build key, (this is optional if your git repository is public).
- Configure your repository to issue a POST request on each push to
https://api.luadns.com/notifications/YOUR_API_KEY/push
,
you'll find your API key on API Keys page.
GitHub
- Access your settings page and set repository.
- Access GitHub -> Repository -> Settings -> Deploy keys and add your LuaDNS deploy key there.
- Access GitHub -> Repository -> Settings -> Webhooks and add a new webhook:
- Payload URL: https://api.luadns.com/notifications/YOUR_API_KEY/push
- Leave other settings default
Bitbucket
- Access your settings page and set git repository.
- Bitbucket -> Repository -> Settings -> Access keys and add your LuaDNS deploy key there.
- Bitbucket -> Repository -> Settings -> Webhooks and add a new webhook:
- Title: LuaDNS
- URL: https://api.luadns.com/notifications/YOUR_API_KEY/push
- Leave other settings default
Gitea/Gogs
- Access your settings page and set git repository.
- Access Gitea -> Repository -> Settings -> Deploy Keys and add your LuaDNS deploy key there.
- Access Gitea -> Repository -> Settings -> Webhooks and add a Gitea Webhook:
- Target URL: https://api.luadns.com/notifications/YOUR_API_KEY/push
- HTTP Method: POST
- Leave other settings default
Example Repository
An example repository can be found here: https://github.com/luadns/dns
Troubleshooting
Use curl
to trigger a manual rebuild of your zones:
$ curl -X POST https://api.luadns.com/notifications/YOUR_API_KEY/push
DNSSEC
You can improve domain security by enabling DNSSEC, this allows you to digitally sign your DNS records.
To start using DNSSEC you must enable it from the zone settings page. When DNSSEC is enabled, a pair of DNSKEY will be generated automatically: KSK (Key Signing Key) and ZSK (Zone Signing Key). The zone is signed and distributed to our name servers to be served right away.
The KSK is used to sign DNSKEY records and ZSK is used to sign other records. Using two keys together allows us to roll a new ZSK without updating the DS record in the parent zone.
Before enabling DNSSEC check that your registrar supports DS records with algorithm 13 (ECDSA Curve P-256 with SHA-256).
Some registries supports automated DNSSEC provisioning via CDS/CDNSKEY record signaling (RFC 7344). We support CDS & CDNSKEY records, they are generated automatically when DNSSEC is enabled.
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:
AAAA, ALIAS, A, CNAME, DS, FORWARD, MX, NS, PTR, REDIRECT, SOA, SPF, SRV, SSHFP, TLSA, 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")
CAA Record
CAA Record Syntax:
-- @name = relative name
-- @value = value
-- @tag = tag (issue, issuewild, iodef, default: issue)
-- @flag = flag (default: 0)
-- @ttl = TTL (default: user default TTL)
caa(name, value, tag, flag, ttl)
Example:
caa("", "letsencrypt.org", "issue")
caa("", "mailto:user@example.com", "iodef")
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")
DS Record
DS Record Syntax:
-- @name = relative name
-- @keytag = key tag
-- @digest = digest (hexadecimal characters)
-- @algorithm = algorithm (default: 13)
-- @digest_type = digest type (default: 2)
-- @ttl = TTL (default: user default TTL)
ds(name, keytag, digest, algorithm, digest_type, ttl)
Example:
-- Add a DS record for `us` subdomain using default values for
-- algorithm (13 = ECDSAP256SHA256) and digest type (2 = SHA256).
ds("us", 22021, "D657C7EE6B88F0F4163B69BE8B4DCBEAEC32DA3C3E8AA5B62F6E630D97A7DDEF")
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 a301
redirect - 1 - exact mode, server issues a
301
redirect totarget
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, 4=Ed25519)
-- @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")
TLSA Record
TLSA Record Syntax:
-- @name = relative name
-- @usage = usage (0 - PKIX-TA, 1 - PKIX-EE, 2 - DANE-TA, 3 - DANE-EE)
-- @certificate = certificate association data (hex)
-- @selector = selector (0 - Cert, 1 - SPKI, default: 1)
-- @matching_type = matching type (1=SHA-256, 2=SHA-512, default: 1)
-- @ttl = TTL (default: user default TTL)
tlsa(name, usage, certificate, selector, matching_type, ttl)
Example:
-- File: example.com
tlsa("_25._tcp.mail", 3, "0c72ac70b745ac19998811b131d662c9ac69dbdbe7cb23e5b514b56664c5d3d6")
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 108.61.179.251.
Example:slave("ns1", "1.1.1.1")
orslave("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:
$ 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
$ 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 108.61.179.251.
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:
- Git repository: https://github.com/luadns/dns
- Bind zone file: https://github.com/luadns/dns/blob/master/example.org.bind
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
To configure your account to use vanity name servers follow this steps:
- Create ns1-2.yourcompany.com name servers (A & AAAA records) in yourcompany.com zone
- Add glue records (A & AAAA) for ns1-2.yourcompany.com servers at your registrar
- Add ns1-2.yourcompany.com to Vanity Servers in the settings page
Create Vanity Name Servers
Edit yourcompany.com zone and create A & AAAA records for each name server pointing to our IP addresses:
# A records
ns1.yourcompany.com -> 185.142.218.1
ns2.yourcompany.com -> 185.142.218.2
# AAAA records
ns1.yourcompany.com -> 2001:67c:25a0::1
ns2.yourcompany.com -> 2001:67c:25a0::2
If you have more than 4 name servers you can reuse one of the IPv4 & IPv6 addresses.
Add Glue Records for Vanity Name Servers
If you intend to use your vanity name servers ns1-2.yourcompany.com for yourcompany.com domain, you'll have to add glue records (same A & AAAA records) for each vanity name server at your registrar.
Use Your Vanity Servers
To use your vanity name servers instead of defaults, edit your account and add your name servers (one name server per line) in the "Vanity Servers" textarea.
Example:
ns1.yourcompany.com
ns2.yourcompany.com
Next time when you'll create/update a zone via web GUI or git, your name servers will be injected automatically instead of the default ones (ns1-4.luadns.net).