SackConfig
From SackWiki
Contents |
Abstract
This page gives an overview of the SackConfig distributed DNS configuration software, as used to configure nameserver.net name servers. The content is split in to two sections; a technical overview of the software and its component parts, and a configuration reference guide for the SackConfig-specific components.
Installation of the SackConfig software and integration with an existing BIND installation are covered separately on another page.
Executive Summary
SackConfig is a meta-configuration tool for name servers. It simplifies the task of adding and removing domains from a network of name servers by:
- Establishing a trust relationship between name servers
- Allowing each server in the network to specify a list of domain names and on which servers they are to be hosted
- Building the name server configuration file based on the consolidated input of all servers within the network
Once SackConfig is installed the incremental effort required to host a new domain name is reduced to: (i) adding a zone file to the master server and (ii) updating the published list of domain names to include the list of slave servers. This requires significantly less effort than logging in to each of the slave servers to modify the name server configuration files by hand and is much quicker than e-mailing update requests to a remote domain name administrators, especially for top level domains that require name server configuration to be complete before domain name registration can be completed.
Technical Overview
SackConfig is made up of three components, as shown in the following diagram.
Fig. 1: Overview of SackConfig Processes
1. sackfigurator
Sackfigurator is the heart of the SackConfig system; it is a Perl script whose task is to produce the local name server configuration based on the local SackConfig configuration and the remote configurations from other servers within the network.
Sackfigurator has two local input files on each SackConfig-enabled name server:
- sack.conf: defines values that are specific to this installation of SackConfig; such as the locations of master and slave zone files on disk, the location of temporary files on disk and the name of this name server.
- xyz.conf: by convention, this file is named according to the three-letter airport code of the name server although any name is valid. This configuration specifies two things: (i) the list of name servers within the SackConfig network and the trust status for each and (ii) the list of domains hosted on this name server and the list of slave servers for each.
In addition to its local configuration files, sackfigurator will download the ???.conf file from each name server within the SackConfig network (as specified in the local xyz.conf). Having done this, the remote configs are processed as follows:
- The remote config from any host tagged as trusted in the local xyz.conf will be parsed to identify any servers not already listed in the local xyz.conf. The remote configuration for any such servers is then downloaded.
- Every remote configuration is then read to identify the list of domains that should be hosted by the local name server.
Be aware that the “trusted” tag is only valid in the context of the local configuration file. Even if xyz.nameserver.net trusts abc.nameserver.net, the trusted tags specified in the abc.conf file are ignored by xyz.nameserver.net. Trust cannot be inherited.
Configuration files downloaded from remote SackConfig-enabled servers are stored in the temporary directory specified in the sack.conf file. For more details on the mechanism used to publish the local xyz.conf and by which the remote SackConfig configuration files are downloaded refer to 2. httpd.
The output of sackfigurator is a local configuration file – sackdns.conf (this can be changed by updating the local sack.conf configuration) – which contains the consolidated list of domains to be hosted on the local name server. SackConfig produces configuration files for the BIND name server. It is known to work with BIND versions 8 and 9 running in a Un*x environment; compatibility with other name server implementations / operating system environments is unknown – although anything which parses BIND configuration files accurately should work.
For more detail on how the sackdns.conf file is used by the local name server process refer to 3. named.
The sackfigurator process is run on a timed basis – usually from root’s crontab. The frequency with which sackfigurator runs is up to the local system administrator; since the maximum time to propagate a new domain is twice the execution-frequency of sackfigurator on the master server, the process is usually run on a fairly regular basis (30 minutes).
2. httpd
httpd is not an integral part of SackConfig in the same way that sackfigurator and named are; HTTP is simply used as a convenient way of distributing the local configuration file (xyz.conf) to remote servers.
The only requirement placed on the local http daemon by SackConfig is that the local xyz.conf file must be available by means of an unauthenticated HTTP GET request. This implies that httpd must be able to read the local configuration; if the local httpd is running in a chroot jail then xyz.conf must be readable from within that jail (i.e. hard linked), and if the local httpd runs as a non-root UID then the unprivileged UID must have permission to read xyz.conf.
3. named
SackConfig does not change the basic function of named; BIND is used to host domain information and synchronise updates between master and slave servers, sackfigurator simply supplies the list of domains based on input from servers within the network.
The primary BIND configuration file – named.conf – is retained in its normal location. This configuration file contains all the local named customisations – such as the options stanza, any local ACL definitions and any local domains that are not shared over the SackConfig network (e.g. 0.0.127.in-addr.arpa).
In addition, named.conf refers to the sackfigurator output file – sackdns.conf – by means of an include directive. The sackdns.conf file must be readable by the named process; if named is running in a chroot jail then sackdns.conf must be readable from within that jail (either hard linked or written directly to the appropriate directory by sackfigurator, as specified in sack.conf), and if the local named runs as a non-root UID then the unprivileged UID must have permission to read sackdns.conf.
Note that sackfigurator configures BIND so that only authoritative name servers can zone transfer (AXFR/IXFR) any domain hosted within the SackConfig network. This should not cause any problems for the majority of domains; however, the behaviour is hard coded and is not easily bypassed on a per-domain basis.
If a domain needs to be transferrable by a small number of identifiable servers that are not part of the SackConfig network, “phantom” slave entries can be added for each server in the dns stanza of the xyz.conf file. This will cause sackfigurator to include the phantom servers in the zone transfer ACL for the zone. Any domain which needs to be globally transferrable should be added to named.conf on each of the authoritative name servers as for any non SackConfig-enabled name server installation.
SackConfig does not modify the standard BIND zone file structure or content in any way. Zone file maintenance on a SackConfig-enabled name server is the same as for any BIND installation.
Configuration Reference
This section covers the configuration of the two sackfigurator configuration files – sack.conf and xyz.conf. It does not cover the configuration of the Apache HTTP server or the BIND name server software; see the Apache Project documentation and the BIND 9 Administrator’s Reference Manual respectively.
sack.conf
This is the local configuration file that defines values which are specific to this installation of SackConfig; such as the locations of master and slave zone files on disk, the location of temporary files on disk and the name of this name server.
The module keyword is a directive to the Perl interpreter to load and interpret the specified module (whose location can be specified absolutely or relative to the current directory) and associate it with the named keyword when parsing configuration files.
module <name> </path/to/source>
<name> specifies a configuration keyword that sackfigurator must parse and act upon.
</path/to/source> specifies the path to the Perl module responsible for parsing the keyword. The path is specified relative to the location from which sackfigurator is executed.
As a general rule, the module definitions in the default, supplied configuration file do not need to be modified.
Example:
module dns BindConfig.pm
The defaultmodules keyword specifies the name of a module that will be loaded by default when sackfigurator starts. As a rule, there must be one defaultmodules statement for each module definition (see above).
defaultmodules <name>
Note – despite being defined in the plural, the defaultmodules keyword accepts a single argument. Additional modules are loaded by having multiple defaultmodules directives, each on its own line in the configuration.
It is not usually necessary, and never a good idea, to play with the module or defaultmodules definitions in the default sack.conf supplied with SackConfig.
Example:
defaultmodules dns
The remotedir keyword specifies the location in which sackfigurator will store local configuration files retrieved from remote servers within the SackConfig network. The path can be specified either absolutely or relative to the current directory, more usually the former.
remotedir </path/to/dir>
Example:
remotedir /tmp/sackfigurator/
The localname directive specifies the fully qualified domain name of the local SackConfig-enabled name server.
localname <fqdn>
Example:
localname sou.nameserver.net
The local keyword passes variable/value pairs to the module specified by module_name. As with the similarly named Perl keyword, variable definitions and associated values defined by the local keyword in sack.conf will only be valid in the context of the specified module.
local <module_name> <variable> <value>
The SackDNS module requires four definitions in order to build the sackdns.conf output file. The required configuration is as follows:
local dns rootdir </absolute/path/> local dns primarydir <relative_path/> local dns secondarydir <relative_path/> local dns configfile <file_name>
rootdir defines the base directory in which all BIND configuration files are written. This is equivalent to the BIND directory keyword (part of the options stanza in named.conf). The value is almost always defined absolutely.
primarydir defines the directory in which master zone files are stored (primary being the deprecated, BIND 4, term for a master zone). This value is specified relatively with respect to the value of rootdir.
secondarydir defines the directory in which slave zone files are written by BIND (secondary being the deprecated, BIND 4, term for a slave zone). This value is specified relatively with respect to the value of rootdir.
configfile defines the output file name to which sackfigurator writes the consolidated list of master and slave zones on the local name server. The value is specified relatively with respect to the value of rootdir. The common (and default) value of this variable is “sackdns.conf”.
xyz.conf
This is the local configuration file for a SackConfig-enabled name server. The file contains details of hosts from which remote configurtions are to be retrieved and a list of domains hosted within the SackConfig network (typically the ones whose master copy resides locally). Commentary can be added in typical unix style – by prefixing any comment with a hash mark (#). All comments continue until the next new line character is reached.
The host stanza specifies a remote SackConfig-enabled name server from which sackfigurator will retrieve a configuration file, as specified by the cfg directive. An optional trust directive specifies that sackfigurator should retrieve configuration files from any host server(s) in <fqdn>’s configuration file.
host <fqdn> {
cfg <http_URL>
[trust]
}
<fqdn> specifies a fully qualified domain name – the host name of the remote name server from which a sackfigurator configuration file should be retrieved.
<http_URL> specifies an Internet URL from which <fqdn>’s configuration file can be downloaded using unauthenticated HTTP.
Example:
host sou.nameserver.net {
cfg http://joshua.sackheads.org/~jpayne/sou.conf
trust
}
The dns stanza specifies an Internet domain which is hosted on a number of name servers. Typically a dns stanza will be specified once, in the master server’s local configuration and will contain a list of one or more slave servers on which the domain should be hosted; however, there is no technical reason why this has to be the case.
dns <domain_name> {
master (<fqdn>|<IP_address>)
[slave (<fqdn>|<IP_address>)
…]
}
<domain_name> specifies the Internet domain name that is to be hosted on the sackfigurator network.
<fqdn> specifies a fully qualified domain name – of the master or slave name server hosting this domain, as appropriate.
<IP_address> specifies the IP version 4 address - in dotted quad notation – of the master or slave name server, as appropriate.
Example:
dns sackheads.org {
master sjc.nameserver.net
slave sou.nameserver.net
slave phl.nameserver.net
slave iad.nameserver.net
slave bos.nameserver.net
slave rdu.nameserver.net
slave iad.nameserver.net
slave yul.nameserver.net
slave forbidden.dough.net
}
