[[ch-dns-hosting]]
== DNS Hosting

To take full advantage of the Symbiosis system, your domain needs to be
configured to have Bytemark's name servers as authority for it.

What follows only applies if our name servers are used; if that is not the case
you will need to manage your DNS data outside of the Symbiosis system.
<<s-example-dns-records>> gives a listing of the records needed for
the correct functioning of the system.

All domains which are hosted upon a Symbiosis system will have their DNS records
automatically uploaded to the Bytemark Content DNS servers.

By default a set of typical records is created for each hosted domain with MX
records pointing to the local system, and aliases such as _www._ and
_ftp._ for convenience.  If you wish you may edit the records to make
custom additions or otherwise make changes to those defaults.

For the domain "my-brilliant-site.com" you will find the
auto-generated DNS records in
'/srv/my-brilliant-site.com/config/dns/my-brilliant-site.com.txt'

The DNS files are uploaded to the Bytemark content DNS service every
hour, and allow you to use the full range of available TinyDNS
options. These options are documented upon the
http://www.bytemark.co.uk/dnsc_example[Bytemark Website] and in the
http://cr.yp.to/djbdns/tinydns-data.html[TinyDNS documentation].

[[s-example-dns-records]]
=== Example DNS records
(((DNS records, example)))

This is an example of the records Symbiosis generates for
+my-brilliant-site.com+.  They are created automatically and stored in
'config/dns/my-brilliant-site.com.txt'.
(((config/,dns/,my-brilliant-site.com.txt)))

.DNS records example
-------------------------------------------------------------------------------
#
#  Nameserver records. <1>
#
.my-brilliant-site.com::a.ns.bytemark.co.uk:300
.my-brilliant-site.com::b.ns.bytemark.co.uk:300
.my-brilliant-site.com::c.ns.bytemark.co.uk:300

#
#  The domain name itself <2>
#
=my-brilliant-site.com:89.16.174.65:300

#
#  Useful aliases. <3>
#
+ftp.my-brilliant-site.com:89.16.174.65:300
+www.my-brilliant-site.com:89.16.174.65:300
+mail.my-brilliant-site.com:89.16.174.65:300   

#
# A record for MX <4>
#
+mx.my-brilliant-site.com:89.16.174.65:300

#
# The domain name itself -- AAAA record and reverse. <5>
#
6my-brilliant-site.com:200141c80001596d0000000000000065:300

#
# Useful aliases -- AAAA records only 
#
3ftp.my-brilliant-site.com:200141c80001596d0000000000000065:300
3www.my-brilliant-site.com:200141c80001596d0000000000000065:300
3mail.my-brilliant-site.com:200141c80001596d0000000000000065:300

#
# AAAA record for MX 
#
3mx.my-brilliant-site.com:200141c80001596d0000000000000065:300

#
#  MX record -- no IP defined, as this is done separately above. <6>
#
@my-brilliant-site.com::mx.my-brilliant-site.com:15:300

-------------------------------------------------------------------------------

<1> These lines create _NS_ and _SOA_ records for +my-brilliant-site.com+ pointing at
    a.ns.bytemark.co.uk, b.ns.bytemark.co.uk, and c.ns.bytemark.co.uk.
    The time-to-live for these records is 300 seconds.  Note that the
    double colons in these records are deliberate as the IP addresses
    are defined elsewhere by Bytemark.
<2> This creates an _A_ record pointing +my-brilliant-site.com+ to the
    IP address +89.16.174.65+, and a _PTR_ record for the reverse.
    Again, the TTL is 300 seconds.
<3> These three lines add _A_ records for expected aliases. Once again,
    the TTL for these records is 300 seconds.
<4> This line adds in an _A_ record for the _MX_ record defined below.
<5> From here the IPv6 equivalents of *2*, *3*, and *4* are specified,
    using _AAAA_ records is used instead of an _A_ record.  Note that
    IPv6 addresses are specified in full, without any colons.
<6> This last record creates an _MX_ record directing mail for
    +my-brilliant-site.com+ to +mx.my-brilliant-site.com+, with a
    distance of 15.  The double colon is deliberate since we defined
    the _A_ record for ++mx.my-brilliant-site.com+ in <4>, and an
    _AAAA_ record for the same name in <5>.


[[s-adding-hostname-wildcard]]
=== Adding a wild-card hostname record
(((DNS records, hostname wild-card)))

In addition to these records for each domain, a wild-card _A_ record is
needed for the hostname such that the +.testing.+ prefix works.  If
your machine is at Bytemark, this has already been setup for your
machine's Bytemark alias, for example _example.default.bytemark.uk0.bigv.io_.

If your machine is not hosted at Bytemark, or your hostname does not
end in +bytemark.co.uk+ then you will need to set this alias up.
Adding the following line to your DNS file will work, assuming the
domain is hosted at Bytemark.  This assumes that your machine is called
+host.example.com+ and that your machine's IP address is 1.2.3.4.

-------------------------------------------
+*.host.example.com:1.2.3.4
-------------------------------------------

[[s-adding-ttl-per-domain]]
=== Adding a custom TTL per domain

New to Jessie Symbiosis is adding a custom TTL to a domain. If you're unfamiliar,
you can read more about time to live (TTL) https://en.wikipedia.org/wiki/Time_to_live[here].
You can configure this by creating the file :

'/srv/my-brilliant-site.com/config/ttl'

The contents of the file should be a number, and it represents the time a
 name server can cache the record in seconds. A lower TTL is good for making frequent changes,
as clients won't cache for too long. A longer TTL is good for times when DNS is
unavailable for some reason.

[[s-adding-dmarc-per-domain]]
=== Adding a DMARC policy per domain

Also new to Jessie Symbiois is an easy way to add a DMARC poilcy on a per-domain
basis. If you're unfamiliar with DMARC, https://en.wikipedia.org/wiki/DMARC[Wikipedia has an article]
. It provides indication that emails are protected by SPF and/or DKIM. It can be
 configured by creating a file in the format :

'/srv/my-brilliant-site.com/config/dmarc' 

You may leave this as an empty file, and Symbiosis will use its defaults. If
you prefer, the file can contain your own DMARC string.


=== Moving domains between machines using the Bytemark content DNS service
(((Domains, moving between machines)))

If you wish to move your domains between two machines running
Symbiosis and using the Bytemark content DNS service, you must contact
Bytemark Support to arrange the domain to be moved between content DNS
accounts.

This results from the necessity for ensuring that only people with the proper
authorisation can change live DNS data. Once a domain has been hosted
on our network, a content DNS account will have sole authority for it.

If you purchase a second server and move some of your domains onto it, or
purchase a domain from another Bytemark customer you must contact us to move
authority for the domain into the correct account.

Until this is done, although the Symbiosis system will be creating and uploading
data it will not be to the account with the authority to make the data live.

[[s-spf-dkim]]
=== Configuring SPF and DKIM records
(((DNS records, SPF)))
(((DNS records, DKIM)))

glossaryterm:SPF[] and glossaryterm:DKIM[] are standards that help mail servers decide if email is legitimate, ensuring it is more likely to reach the intended recipient's inbox instead of being rejected or marked as spam.  Both these technologies require creation of one or more DNS records.

[[s-spf-configuration]]
==== Adding SPF records
(((SPF, adding records)))

Before adding any records, a policy needs to be decided.  The guide at http://www.openspf.org/SPF_Record_Syntax[OpenSPF] can help determine what the record should look like.  The default policy Symbiosis uses is `v=spf1 +a +mx ?all`.

(((config/, spf)))
To create SPF records simply create the file '/srv/my-brilliant-site.com/config/spf'.  Nothing more is required if the default policy is adequate.  If you have decided on a different policy, then you can just write it to this file.

A task is run hourly to generate the DNS data and upload it to the Bytemark DNS servers, at which point the domain will start benefiting from it.  If you wish to speed up this process, run `sudo symbiosis-dns-generate --verbose`.

[[s-dkim-configuration]]
==== Adding DKIM records
(((DKIM, setup)))

glossaryterm:DKIM[] is a way of cryptographically signing email headers to provide a level of confidence surrounding the origin of said email.  Configuring DKIM requires a private RSA key, and a DNS record specifying the public part of the key, along with a policy dictating how the key should be used.  For DKIM to work in Symbiosis two files are required, one contains the private key, and the second contains the selector (or nothing).

[[proc-dkim-setup]]
[procedure]
- To generate the private key, run `openssl genrsa -out /srv/my-brilliant-site.com/config/dkim.key 2048 -outform PEM` on your server.  This will generate a key that is 2048 bits long.  (((config/, dkim.key)))
(((config/, dkim)))
- Next create the file '/srv/my-brilliant-site.com/config/dkim',
  either as an empty file or with the selector in it.  If the file is
  empty, the selector is left as the first component of the machines
  hostnome, or "default" if this cannot be determined.  (((config/, dkim)))

Once both files are in place the hourly DNS task will update the DNS records for your domain and upload them as usual.  If you wish to speed up this process, run `sudo symbiosis-dns-generate --verbose`.


