--- /dev/null
+Before continuing with this page, you probably want to read DomainTool to learn the basics of how we handle shared daemon configuration.\r
+\r
+A {{{.dns}}} file in a domain's directory controls its DNS settings. Such files consist of a sequence of lines of the following types:\r
+\r
+ * {{{Master <ip>}}}: Designates a master DNS server from which we should fetch all data for this domain. Any DNS configuration in a {{{.dns}}} file after any {{{Master}}} directive is ignored, except for {{{Mail}}} lines which determine the behavior of our SMTP server. You can use multiple {{{Master}}} directives, but the later IP addresses will only be used if the earlier servers are not contactable. The DNS data is queried using the standard zone transfer protocol.\r
+ * {{{Slave <slave>}}}: Usually appears at top of file. Discussed in the next section.\r
+ * {{{TTL <seconds>}}}: {{{seconds}}} is an integer specifying the lifetime in seconds of the DNS records coming after this directive and before the next {{{TTL}}} directive, if any. DNS caches around the 'net will feel free to assume that these mappings remain valid for that long without consulting our DNS servers to verify that this is really the case. This is valuable behavior, since it saves wear and tear on our servers. You should only use this directive if you have a particular, compelling reason, such as that a particular DNS mapping is updated regularly by a program. {{{domtool}}} enforces that the TTL that you enter is at least some minimum value. The current minimum is 120 seconds, which we can change if someone has a good reason.\r
+ * {{{TTL default}}}: Switch back to using default TTLs after using the directive described in the last entry. Different kinds of entries have different default TTLs that will be used, based on what the author of djbdns thought makes sense in the general case.\r
+ * {{{Primary <host> <ip>}}}: Sets the primary DNS server for the domain to IP address {{{ip}}}, naming it {{{host.domain}}}\r
+ * {{{Primary <full_hostname>}}}: Use this to set your primary DNS server to a hostname from another domain. For example, you should use this if you want to use our default {{{ns.hcoop.net}}}/{{{ns2.hcoop.net}}} DNS configuration and your registrar complains that your DNS servers report different hostnames for nameservers than you gave to the registrar. We've only yet encountered one case where this was necessary. The set of allowed hostnames is specified in root-administered {{{.nses}}} files, which are handled in the same way as {{{.slaves}}} files. {{{ns.hcoop.net}}} and {{{ns2.hcoop.net}}} will both always be available.\r
+ * {{{Secondary <host> <ip>}}}: Adds a secondary DNS server for the domain with IP address {{{ip}}}, naming it {{{host.domain}}}\r
+ * {{{Secondary <full_hostname>}}}: Analagous to the {{{Primary}}} form above for full hostnames.\r
+ * {{{Mail <host> <ip>}}}: Add a server to process e-mail for the domain with IP address {{{ip}}}, naming it {{{host.domain}}}. Mail servers will attempt to deliver mail to the servers you list following the order in which you list them, starting from the first.\r
+ * {{{BackupMail <host> <ip>}}}: This like like {{{Mail}}}, but, instead of declaring that mail for a domain is accepted locally, it declares that our mail server should accept mail for this domain and forward it on to one of that domain's "real" mail servers. This is useful in case that domain's primary mail server goes down, in which case our mail queue can hold messages meant for it.\r
+ * {{{Mail <full.host>}}}: Add an external server {{{full.host}}} to process e-mail for this domain. This form doesn't add an A record, so you will only want to use it for non-HCoop mail servers that already have A records elsewhere.\r
+ * Mail creates a DNS __MX__ record.\r
+ * {{{Default <ip>}}}: Sets the IP address for {{{domain}}} to {{{ip}}}\r
+ * {{{Host <host> <ip>}}}: Sets the IP address for {{{host.domain}}} to {{{ip}}}\r
+ * {{{Alias <host> <ip>}}}: Sets the IP address for {{{host.domain}}} to {{{ip}}}; use this when this IP address has already been assigned a name in this domain with {{{Default}}} or {{{Host}}}\r
+ * Alias creates a DNS __A__ record.\r
+ * {{{Redir <host1> <host2>}}}: Sets {{{host1.domain}}} to have the same IP address as {{{host2}}}. This should almost never be used, as it requires every client resolution of this hostname to follow the chain of redirections, possibly across different servers. You should usually define a variable for a commonly used host IP address and use it with {{{Host}}} and {{{Alias}}} directives.\r
+ * Redir creates a __CNAME__ record. CNAME is usefull when you want to resolve to a server on a different DNS server / hosting provider.\r
+''Note'': The entries for Primary and Secondary DNS servers are required for the other entries to have any useful effect. (If you don't specify that our servers are in charge of your domain, no one will know to ask them about it.) See the {{{.dns}}} files for other working domains to get an idea of how this file should look.\r
+\r
+= Subdomains =\r
+Creating subdomains is easy. For instance, to create a subdomain {{{a.me.com}}} of domain {{{me.com}}} that you control in domtool, create the directory {{{/etc/domains/com/me/a}}}. You can then configure your subdomain like any other domain, by editing files in its directory and running {{{domtool}}}.\r
+\r
+Copying all the files in your domain directory into a subdomain directory is a bad idea. At least delete your {{{.users}}}, {{{.groups}}}, and {{{.paths}}} files if you do so, since domtool will generate error messages for everyone as long as you have any files with those names that are owned by your UNIX user.\r
+\r
+= Slave servers =\r
+It's also true that your Secondary servers need to agree with us on which host names go where. One way to accomplish this is to use whatever ad-hoc mechanisms you like on these secondary servers. Another way is to use the "slave server" mechanisms built into domtool.\r
+\r
+Domain directories can have root-maintained {{{.slaves}}} files that specify allowable slave servers for those domains and their subdomains, in the style of {{{.paths}}}. These files map short server names into strings that are suitable parameters to rsync, specifying where to drop off updates to DNS data.\r
+\r
+As an example, we can look at this system-wide slave server, declared in {{{/etc/domains/.slaves}}}:\r
+\r
+{{{abu newdns@63.246.10.45:data/;newdns@63.246.10.45:/service/autoaxfr/root/slaves/}}}\r
+\r
+This is the slave server that you're most likely to use, if you don't want to worry about figuring out your own DNS infrastructure. You can use it to replicate your DNS mappings on our secondary DNS server, Abulafia. This slave is named {{{abu}}}, and data meant for it should be put in the {{{data}}} subdirectory of user {{{newdns}}}'s home directory on the server at IP address 63.246.10.45. There is an additional rsync path, separated from the first by a semicolon, that specifies the path for "sub-slaves," which are cases where this domain's data is queried from a remote host via {{{Master,}}} but you still want to instruct further servers to serve that same data.\r
+\r
+You can use this slave in your own {{{.dns}}} files by beginning them with the line:\r
+\r
+{{{Slave abu}}}\r
+\r
+Data lines are only shared with slaves declared ''before'' those data lines. This means that you could do something like dividing your DNS data into layers, where some slaves only receive data up to a specific layer. However, it's not clear why you'd want to do that, and domtool mostly supports this "feature" because it made implementation easier. :)\r
+\r
+For our example to work out, we had to set up the password-less ssh login described in SshConfiguration between {{{root}}} on our server and {{{newdns}}} on Abulafia. Abulafia's DNS build process takes into account the data files that our main server hands to it. If you want to hand data to your own slave servers, you will need to do similar work to make your servers put the data to good use.\r
+\r
+Currently, we only support slaves based on [http://http://cr.yp.to/djbdns.html djbdns], as that is the data format we send to remote slaves. If there is demand, we may add support for more conventional BIND transfers.\r
+\r
+You can implement "sub-slaves" by following a sequence of {{{Slave}}} directives with a sequence of {{{Master}}} directives. In this case, {{{fyodor}}} and all slaves that you specify will get their data for your domain from the masters that you specify.\r
HCoop / hcoop / zz_old / ikiwiki / blobdiff