mailinabox/management/templates/system-dns.html

<style>
#external_dns_settings .heading td {
  font-weight: bold;
  font-size: 120%;
  padding-top: 1.5em;
}
#external_dns_settings .heading.first td {
  border-top: none;
  padding-top: 0;
}
#external_dns_settings .values td {
  border: 0;
	padding-top: .75em;
	padding-bottom: 0;
	max-width: 50vw;
	word-wrap: break-word;
}
#external_dns_settings .explanation td {
	border: 0;
	padding-top: .5em;
	padding-bottom: .75em;
	font-style: italic;
  font-size: 95%;
	color: #777;
}
</style>

<h2>DNS (Advanced)</h2>

<p class="text-danger">Custom and external DNS are for advanced configurations.</p>

<h3>Custom DNS</h3>

<p>It is possible to set custom DNS records on domains hosted here. For instance, you can create your own dynamic DNS service. To do so, you will need to call your box&rsquo;s DNS API.</p>

<h4>The HTTP POST request</h4>

<p>Send a POST request like this:</p>

<pre>curl -d "" --user {email}:{password} https://{{hostname}}/admin/dns/set/<b>qname</b>[/<b>rtype</b>[/<b>value</b>]]</pre>

<table class="table">
<thead><th>Parameter</th> <th>Value</th></thead>
<tr><td>email</td> <td>The email address of any administrative user here.</td></tr>
<tr><td>password</td> <td>That user&rsquo;s password.</td></tr>
<tr><td>qname</td> <td>The fully qualified domain name for the record you are trying to set.</td></tr>
<tr><td>rtype</td> <td>The resource type. <code>A</code> if omitted. Possible values: <code>A</code> (an IPv4 address), <code>AAAA</code> (an IPv6 address), <code>TXT</code> (a text string), or <code>CNAME</code> (an alias, which is a fully qualified domain name).</td></tr>
<tr><td>value</td> <td>The new record&rsquo;s value. If omitted, the IPv4 address of the remote host is used. This is handy for dynamic DNS! To delete a record, use &ldquo;__delete__&rdquo;.</td></tr>
</table>

<p style="margin-top: 1em">Note that <code>-d ""</code> is merely to ensure curl sends a POST request. You do not need to put anything inside the quotes. You can also pass the value using typical form encoding in the POST body.</p>

<p>Strict <a href="http://tools.ietf.org/html/rfc4408">SPF</a> and <a href="https://datatracker.ietf.org/doc/draft-kucherawy-dmarc-base/?include_text=1">DMARC</a> records will be added to all custom domains unless you override them.</p>

<h4>Examples:</h4>

<pre># sets laptop.mydomain.com to point to the IP address of the machine you are executing curl on
curl -d "" --user me@mydomain.com:###### https://{{hostname}}/admin/dns/set/laptop.mydomain.com

# sets an alias
curl -d "" --user me@mydomain.com:###### https://{{hostname}}/admin/dns/set/foo.mydomain.com/cname/bar.mydomain.com

# clears the alias
curl -d "" --user me@mydomain.com:###### https://{{hostname}}/admin/dns/set/bar.mydomain.com/cname/__delete__

# sets a TXT record using the alternate value syntax
curl -d "value=something%20here" --user me@mydomain.com:###### https://{{hostname}}/admin/dns/set/foo.mydomain.com/txt
</pre>


<h3>External DNS</h3>

<p>Although your box is configured to serve its own DNS, it is possible to host your DNS elsewhere.</p>

<p>If you do so, you are responsible for keeping your DNS entries up to date! If you previously enabled DNSSEC on your domain name by setting a DS record at your registrar, you will likely have to turn it off before changing nameservers.</p>

<p>Enter the following DNS entries at your DNS provider:</p>

<table id="external_dns_settings" class="table">
	<thead>
		<tr>
			<th>QName</th>
			<th>Type</th>
			<th>Value</th>
		</tr>
	</thead>
	<tbody>
	</tbody>
</table>

<script>
function show_system_dns() {
  $('#external_dns_settings tbody').html("<tr><td colspan='2' class='text-muted'>Loading...</td></tr>")
  api(
    "/dns/dump",
    "GET",
    { },
    function(zones) {
      $('#external_dns_settings tbody').html("");
      for (var j = 0; j < zones.length; j++) {
        var h = $("<tr class='heading'><td colspan='3'></td></tr>");
        h.find("td").text(zones[j][0]);
        $('#external_dns_settings tbody').append(h);

        var r = zones[j][1];
        for (var i = 0; i < r.length; i++) {
          var n = $("<tr class='values'><td class='qname'/><td class='rtype'/><td class='value'/></tr>");
          n.find('.qname').text(r[i].qname);
          n.find('.rtype').text(r[i].rtype);
          n.find('.value').text(r[i].value);
          $('#external_dns_settings tbody').append(n);

          var n = $("<tr class='explanation'><td colspan='3'/></tr>");
          n.find('td').text(r[i].explanation);
          $('#external_dns_settings tbody').append(n);
        }
      }
    })
}
</script>