posadisrc - Configuration file for Posadis
The default Posadis configuration file is called /etc/posadisrc. You can specify a custom configuration file using the "-c" command-line option.
The configuration file is basically just a plain text file. Each configuration option is on a separate, unindented line, followed by its configuration value. Everything after a ';' is ignored, so you can thus embed comments in your configuration files.
For example, you can specify configuration options/commands like this:
Listen tcp/3000 ; listen to port 3000 for tcp
Listen ::1 ; listen to ipv6 port 53 for tcp/udp
LoadModule "revmap"
LoadModule "localhost"
Modules can also supply other functionality, for example, the "monitor" module can automagically load all master files in a specified directory. The default location for libraries is "/prefix/lib/posadis/", where prefix is your installation prefix, /usr by default. You can add directories to the library search path using the following:
; add this to library search path
Libdir "/home/meilof/mymodule-1.0/lib/"
If you want to know the default module location, run "posadis --version". Creating Posadis documents is covered later.
The following modules are included in the core Posadis distribution:
monitor - Loads all master files in a specified directory, and monitors them for changes (for Unix, this requires the SGI File Alteration Monitor).
revmap - Provides a convenient way for automated IPv4 reverse mapping (.in-addr.arpa.). Provides "formap" and "revmap" zone types.
localhost - Returns back the IP number of the querier. Provides "localhost" zone type.
cache-ns .
You can specify initial nameserver lists for other domains as well though that is not nessecary. Also, Posadis features a tool called "posadis-getroots" which can get the latest root nameservers for you, in the format described above. Use the program without arguments to get the latest root nameservers of ICANN, or use "posadis-getroots orsc" to get the latest root nameservers of the Open Root Server Confederation. Alternatively, enter IP numbers for other alternative roots to get the complete list for that.
Allright, now for the cache configuration. Basically, there are two ways of caching: forwarding and resolving. If you just want resolving, you should be done by now because Posadis has now enough information. If you want to do forwarding instead of caching, which is a good idea if you have a slow internet connection, you can configure forwarding for a zone like this:
cache-forward .
192.168.1.1 ; nameserver to forward to
192.168.1.2 ; another nameserver
This will apply to all subdomains of "." that are not part of an authoritative zone (they may be subzones of authoritative zones though). If you would want to disable forwarding for a given subdomain, use:
cache-forward acdam.net
For all subdomains of acdam.net, Posadis will try to resolve the domain name instead of forwarding queries.
libdir - Specify an additional directory to look in for libraries. Posadis looks by default in the "lib/posadis" subdirectory of your prefix, so this would usually be "/usr/lib/posadis/".
loadmodule - Load a Posadis module. Modules can introduce new zone types and configuration settings, and thus provide new functionality to Posadis.
General:
listen - Specify an interface to listen to. You can specify an IP number (both IPv4 and IPv6), a port number (to listen on any IPv4 interface), or both (separated by a '#'). You can prefix this by "udp/" or "tcp/" to listen to only UDP or TCP, respectively.
configdir - The directory to look in for zone data and master files.
update_ttl - Interval after which to re-check zone files for changes when using the "zonefile" and "allzonefiles" statements. Defaults to 10m (10 minutes).
datadir - Directory to store temporary files in (nessecary both for serving and retrieving zone transfers).
user (Unix only) - User name to switch to after opening configuration files and binding to sockets. Note that master files should be readable by this user as well as root.
group (Unix only) - Group name to switch to after opening configuration files and binding to sockets.
Logging:
logfile - File to log messages in. By default, nothing is logged. Posadis for Unix will also log to syslog.
logfile_per_day - If set to true, Posadis will create a new logfile each day at midnight (named according to the value of 'logfile', but with the data appended). Defaults to false though.
do_query_logging - If set to true, Posadis will log each query (normal queries, zone transfers and NOTIFY messages) it receives. Useful for debugging purposes; defaults to false.
Resolving:
max_cache_items - The maximum number of domain names stored in the cache. If new domain names are added, older ones will be removed to prevent breaking this limit. Defaults to 1000.
resolv_patience - The number of operations taken at most to complete one recursive query. Applies to zones for which we do resolving for, only, and defaults to 15.
allow_recursion - If given, only these hosts are allowed to do recursion. Can be an address or a range.
refuse_recursion - If given, hosts on this list are not allowed to do recursive queries, even if they are in the allow_recursion list as well.
cache_statistics - If this is set to true, Posadis will periodically (that is, every 60 seconds) display statics about the cache: the number of domain names and records stored, and the number of cache hits/misses. Defaults to false.
initial_cache_files - Specifies master files to initially populate the cache with. These files are looked for in the Posadis configuration directory. Initial cache files are not periodically reloaded.
cache_to_file - If set to true, Posadis will keep the contents of its cache over reboots by saving the cache to disk when it quits, and reloading it when it boots.
Resources:
max_threads - Maximum number of simultaneous threads. Defaults to 50.
max_tcp_connections - Maximum number of simultaneous TCP connections. By default set to -1, which means no limit. Of course, the max_threads limit applies to tcp connections as well.
tcp_priority - Hosts to always allow a TCP connection from. Can be a host name or an address range such as 192.168.*.
max_cname_recursion - Maximum number of recursive aliases (CNAMEs) to follow. Defaults to ten, which should really be enough for any sane configuration.
Using the "monitor" module: each zone is a file in your configuration directory, and changed, edited and added zone files will be detected by Posadis. On Unix, this requires FAM to be installed.
Using zone files: each zone is in a file in your configuration directory, and Posadis will poll the files for changed, though it isn't able to add or remove zones.
Using the "zone" statement: zones can be defined directly in the Posadisrc.
Using the "monitor" module
This is the recommended method. In this set-up, you have a configuration directory with zone files in them: each file corresponds to a zone you want to configure. These files have special names: db.
You can set the configuration directory by means of the Configdir setting. By default, this is "/etc/posadis" for Unix, and the "Config" subdirectory of your Posadis install for Windows. Look for a line with the text "Configdir" in your Posadisrc to change this.
As soon as you add, change or remove a zone file in your configuration directory, Posadis will automagically re-load zone. For primary zones, this zone file is just a master file in which configuration commands can be embedded (see the "Master files and RR types" section). For non-primary zones, this file has the following syntax:
zone
command1 value11, value12
command2 value2
...
The command lines can be indented, but that's not nessecary. You can also embed semicolon comments in the zone file.
Using zone files
Basically the same as using the "monitor" module, except that instead of monitoring, this method uses a polling strategy (that is, it checks every n seconds for changes in the zone files, where n is the value of the update_ttl configuration setting). New zone files won't be detected in this way though. It is mainly there for platforms on which the FAM server, on which this depends, is not available, or if you don't want to use FAM.
The Configdir setting determines where the zone files are found; use "Allzonefiles yes" to load all zone files in that directory, or use "Zonefile
Using the "zone" statement
This is the traditional method other DNS servers use as well. The advantage of this is that you have all the configuration in one file, so it is easily transferable or publishable. For primary zones, you will always need a master file so in that case this isn't really true.
Either way, the "zone" statement in your Posadisrc looks like this:
zone
command1 value11, value12
command2 value2
...
Notice that the command lines are indented.
Normally, you use primary zones implicitly by loading a master file and embedding the settings for the zone in it. In the Posadis Master File Editor, you can edit the settings for the zone by opening the "Zone configuration" dialog. This will be discussed in greater detail in the next section.
If you want to define a primary zone directly in the Posadisrc, you'll need the File setting, that determines the master file (relative to the Configdir) for the zone, for example:
zone primary acdam.net
file db.acdam.net
is the same as
zonefile db.acdam.net
Zone transfers
Zone transfers are used by secondary nameservers to get a complete copy of the zone. You can also use a query program like posask to show the complete contents of a zone by doing something like poshost acdam.net axfr.
By default, Posadis will provide a zone transfer to slaves for the zone only. You can either decide to allow zone transfers to anybody (which might take up significant resources) or tell Posadis who your slaves are (if you have any, anyway):
slaves - List of slaves (secondaries that will use you as the primary source for their zone data) for the domain name.
allow_xfr_to - List of additional clients to always allow zone transfers to. This is an address match list, so you can for example say "192.168.1.*".
allow_xfr - Can be either "any" (the default value) to allow zone transfers to anybody, "slaves" to allow only to slaves and those listed in allow_xfr_to, or "none" to only allow those on the allow_xfr_to list.
Note that clients in the slaves list differ from those in the allow_xfr_to list in that Posadis will send so-called "DNS Notify" messages to the slaves to notify them when the zone changes.
Embedding configuration settings into master files
To specify configuration settings (for example the list of slaves; see the "Primary zone type" section), you can place them in your master files. Using the Master File Editor, edit the "Zone configuration" button, and enter, for example
slaves ,
allow_xfr_to 127.0.0.1
or, if you want to edit your master file manually, use the ";set " prefix:
;set slaves ,
;set allow_xfr_to 127.0.0.1
Resource Records
A master file is basically just a list of Resource Records (RRs). Each RR has a so-called Time-To-Live, which is the time the record may be stored in cache by resolvers. For example, if you surf to a domain name with an address record with a TTL of "1h" (1 hour), this means that if you visit the domain name again within one hour, you don't need to ask the server about the address again: you can consider your old data recent enough. If your records change often, you'll want a low TTL, whereas if your records are relatively static, you should make the TTL value higher.
The first RR of the zone should always be a SOA (Start of Authority) record, which contains basic zone information. Other RRs may follow. For a discussion on what records you need in your zone, I refer to the Posadis manual.
Resource Records supported by Posadis
Next comes a list of all Resource Records supported by Posadis. Key for the "syntax" column: "d" for a domain name, "i" for an IPv4 number, "s" for a 16-bit number, "l" for a 32-bit number, "c" for a character string, and "6" for an IPv6 address, and "m" for an e-mail address:
Record type - Syntax
Explanation
SOA - dmlllll
The SOA record, which is always the first record of your zone, contains general zone information used mainly by secondaries to determine their update policies. As you can see, the SOA record has six elements, making it the most difficult RR out there. Here are the entries:
MNAME - The domain name of the primary DNS server for the domain. Note that secondaries don't use this, so it has no practical use.
RNAME - E-mail address of the maintainer of the zone.
SERIAL - Serial number of the zone. You should increase this every time you change the zone. One common numbering scheme is to use the date for this, for example "2003042301" for the first change on 23 May 2003.
REFRESH - The time (in seconds, or in hours or weeks or something with a postfix: "2h" is two hours), after which a secondary will try to re-load the zone.
RETRY - If a zone transfer fails for some reason (e.g. the master was down), the secondary will retry after this interval.
EXPIRE - If, after this time, a secondary still hasn't succeeded in doing a new zone transfer, it will stop answering queries for the zone.
NTTL - TTL for negative caching: for example, the information that "wwww.acdam.net" doesn't exists, may be kept for this long.
An example might be something like:
@ 2h SOA ( ns1 2002052301
2h 1h 1d 2h )
A - i
The A record is used to specify an IP address for a domain name. This is the traditional way of looking up an address for a specific service. An example could be as simple as:
www.acdam.net. A 192.168.1.1
NS - d
This record lists DNS servers for your zone. Each DNS server should be listed by its domain name by means of a NS record. For example:
acdam.net. NS ns1.acdam.net.
CNAME - d
The CNAME record can be used to create an alias in the domain name system: the domain name the record is attached to is defined as an alias to the given target. For example, if we want www.acdam.net. to be an alias to athlon.acdam.net., we'd do something like:
www.acdam.net. CNAME athlon.acdam.net.
If for example an address query is received for www.acdam.net., the client will now receive the addresses for athlon.acdam.net. instead. Note that this also implies that no other records may be available for www.acdam.net., because those might be ambiguous with the data from athlon.acdam.net..
WKS -
Well-known services. Rarely used anymore today, this RR gives information about the services running on a specific server. First, give the IP address the WKS RR applies to (this is nessecary because a domain name can have more than one IP number). After that, specify the protocol, usually "TCP" or "UDP", and after that, any services you're running on it, for example "http", "ftp", "smtp", and so on. Alternatively, you can give the port on which is being listened. For example:
www.acdam.net. WKS 192.168.1.1 tcp dns http ftp 8080
PTR - d
Used for reverse-mapping. Specifies the domain name this domain points to. See the reverse-mapping chapters in the reference section for more information. An example could be something like:
1.0.0.127.in-addr.arpa. PTR localhost.
HINFO - cc
This record is rarely used nowadays, but it can be used to give information about the system running for a given domain name. If you maintain a network, this might come in handy to keep track of your running operating systems. The record consists of two pieces of free-form text: at first one describing your hardware, followed by one describing your operating system. If the description contains spaces, you'll need to enquote it. For example:
athlon.acdam.net. HINFO "AMD Athlon XP" "Debian GNU/Linux 3.0"
MX - sd
This record is used to specify a mail server for a domain name. For example, if you send an email message to , your mail delivery software will send an MX query for acdam.net to find out where to deliver mail. Apart from the domain name of the mail server, this record also contains a priority value. If there are multiple mail servers for a domain, the server(s) with the lowest priority will be tried first, and if they all fail, server with a higher priority will be tried. This can be used to specify backup mail servers:
acdam.net. MX 10 mail.acdam.net. ; primary
MX 10 mail2.acdam.net. ; primary
MX 50 fallback.acdam.net. ; fallback
Note that MX records are not used to lookup the pop3 or smtp servers of your ISP: normal A-type queries are used for these.
TXT - c[c...]
Can be used to put free-form text into your zone. Do with it whatever you like; these records aren't used in normal DNS operation. You can specify an arbitrary number of text strings here. For example:
meilof.acdam.net. TXT ( "Meilof Veeningen"
"Software developer"
"" )
RP - md
Using the RP record, you can list someone who is responsible for the domain the record is attached to. It isn't really used often; you should only used it it you think you'll need it yourself some time. It has two arguments, namely the e-mail address of the person in charge, and a domain name which has TXT records attached to it, that can for example contain the telephone number of the person, or something like that. If you don't have such a TXT domain, use "." instead. An example might go thus:
www.acdam.net. RP meilof.acdam.net.
AFSDB - sd
To be quite honest, I don't really know what this record does, but according to its documentation, it can be used to provide a distributed service under the domain name. This can either be an AFS cell database server or a DCE authenticated name server (whatever these two things might be). Either way, you can give the type of service (1 for the AFS server, and 2 for the DCE server), followed by the domain name of the server running the service. An example might be:
acdam.net. AFSDB 1 afs.acdam.net.
AFSDB 2 dce.acdam.net.
PX - sdd
Again, I haven't got a clue what this is, and quite frankly, I don't care much. This record is meant as a "pointer to X.400/RFC 822 mapping information", a name which by itself makes me not want to know more. Either way, Posadis supports it if you need it. The first value is a preference value, like for the MX record, the second is a RFC 822 domain, and the third is a the value of the X.400 data.
AAAA - 6
Similar to the A record, this record is used to specify an IPv6 address for a domain name. IPv6 is the successor of IPv4 which is expected to be the main internet protocol in about ten years. The representation of an IPv6 address is beyond the scope of this manual.
www.acdam.net. AAAA dead:beef::1
It is worth noting that there have been other proposals to specify IPv6 address in the DNS as well, most notably using the A6 RR type, which is not supported by Posadis (yet), and which is currently marked experimental by the Internet Engineering Task Force. As a result, AAAA might be replaced by a newer technology in the future.
SRV - sssd
This also is a relatively new Resource Record. It is used as a generic way to attach services to a domain. Whereas we usually use subdomains to describe the service for a domain name ("www.acdam.net" in practice really means we want the www server for acdam.net), this method isn't really powerful: it doesn't have load distribution, and it doesn't have the ability to redirect the client to a nonstandard port. For these goals, the SRV record was invented, that does have these features. The SRV record has the following syntax:
_service._protocol.domain SRV pri load port domain
As you can see, the domain name the SRV record is connected to is a bit odd. It does make sense when you think about it though: if you want to know where to locate the smtp service (which uses the tcp protocol) of acdam.net, you'd just do a SRV-type query for "_smtp._tcp.acdam.net", and you'd get back records describing the service. The SRV record has the following fiels
pri - Same as the MX record priority value. If a client wants to connect, it will at first try all servers with the lowest priority, and if they all fail, it will go to a higher level.
load - Determines load distribution within records of the same level. For example, if one server has a value of "20" and another has a value "80", the second server will receive 4 out of 5 queries.
port - The port the client should connect to.
domain - The domain name the client should connect to. The client will need to look up the addresses for this domain before it can connect.
We might thus set up our acdam.net domain like this:
_http._tcp.acdam.net. SRV 0 80 80 www
SRV 0 20 80 slow-server
SRV 1 100 8080 backup
_smtp._tcp.acdam.net. SRV 0 100 25 mail
_imap2._tcp.acdam.net. SRV 0 100 143 mail
Given how useful this SRV record could be, it is really a pity no-one seems to go into great trouble implementing it. I know no major servers that have SRV records, and I don't think there's much client software using it either, which poses kind of a chicken-and-egg problem. So I'd say: even if no-one uses SRV today, help the world and create SRV records anyway!
NAPTR - sscccdd
This record is used for something called "DNS ENUM" which has to do with mapping domain names to "E. 164" numbers. I don't know or seem to really care what this record does, but if you need it, it's there.
You can edit Resource Records by hand, or, more conveniently, using the Posadis master file editor. This editor has a built-in syntax check that can scan your zone for common configuration errors.
Master file syntax
This section will discuss the syntax of master files, would you want to edit them manually yourself rather than letting Mfedit do the dirty work.
Master files contain Resource Records in the following form:
The entries in the syntax above are separated by one or more spaces or tabs. You can span a RR over multiple lines using a syntax like:
)
Note that you can also place other entries of the syntax on multiple lines; just as long as the first line contains a free-standing "(", and the last line contains a free-standing ")".
The following can for example be used to define an A record:
www.acdam.net. 2h A 192.168.1.1
Lines that begin with ";" are ignored, and can thus be used as a comment. Also, text after ";' on a RR line is ignored. For example:
; next is the A record for www.acdam.net
www 2h A 192.168.1.1 ; this is it!
Shorter syntax
All domain names in master files should contain a trailing dot like in the previous example. If they don't have a trailing dot, they're considered relative. The origin they're considered relative to, is, by default, the zone root, so the domain name "www" in the acdam.net zone would be interpreted as "www.acdam.net.". You can change the origin by using the "$origin" directive, like this:
$origin google.nl.
The domain name specified in the $origin directive, itself, is always considered relative to the zone root. If you want to refer to the zone root, you can use "@" instead of the zone root name.
If you give multiple records for the same domain after each other, you don't need to give the domain name for each record. If the first character of a line is a space or a tab, the domain name of the previous record is used, for example:
www 2h 192.168.1.1
2h 192.168.1.2
If no TTL is specified, the TTL of the first record in the master file is used. The first record should thus always have a TTL. Unless, that is, you use the "$ttl" directive to set the default TTL, for example:
masters - List of DNS servers the server will attempt to get a zone transfer from. These servers will be tried in order. Also, the zone accepts notify messages, that tell the server to re-load the zone, from these masters.
allow_notify_from - Lists alternate sources (in address match list form) from which we trust NOTIFY messages. If zone data changes on a master, it sends out NOTIFY messages to its slaves to, well eh, notify them that something changed1. The slaves then know they should update the zone. Changing allow_notify_from is useful if the master is a multi-homed host. You can list only one IP number in the "masters" list for the zone, and list the others in the allow_notify_from list, so that the master is not tried twice for zone transfers, but its notify messages are always accepted by the secondary regardless of what IP address of the master they happened to come from.
Because secondary servers can also serve zone transfers themselves (this configuration is referred to as a "slave-master configuration"), the zone transfer-related configuration settings of the primary zone type (see the "Primary zone type" section) also apply to secondary DNS servers.
The "revmap" and "formap" zone types defined in this module support standard queries only. They do NOT support zone transfers, so secondary nameservers for these reverse-mapping domains will either also need to use this module, or be set up using a master file or other static data. Also, this module is for IPv4 only. Quite possibly, A "revmap6" module might be added in the future.
For example, a query for 1.1.168.192.in-addr.arpa might return a pointer to c0a80101.dyn.acdam.net., where a query for c0a80101.dyn.acdam.net. would return the address 192.168.1.1.
The "revmap" zone type
Maps back domain names in the "in-addr.arpa" namespace to domain names. Configuration options:
prefix - The domain name to append to the generated label. In our example, this was "dyn.acdam.net". This domain name should be a zone of the "formap" type to make forward queries work as well.
nslist - List of nameservers for the zone. Note that these nameservers may not be in the reverse-mapping zone itself, since the zone cannot give addresses for the nameservers.
ttl - Time To Live value for the records sent back.
The "formap" zone type
Companion to the "revmap" zone type. Configuration options:
nslist - See the "revmap" zone documentation.
ttl - See the "revmap" zone documentation.
Algorithm
The 8-byte domain label is the hexadecimal representation of the four bytes in the IP number, with all lowercase characters.
Known bugs and limitations
The forward mapping zone will answer any A query as long as it is a subitem of the zone root with exactly 8 bytes, even if it is not a valid hexadecimal value. In such cases, the returned address will be garbage.
The zones have only one, non-customizable algorithm for generating domain names. This might cause interoperability problems with other DNS servers offering similar capabilities but with a different algorithm.
So what's this good for, you ask? Well, I don't know really myself either. If you're in an identity crisis and you want to know who you are, this might help. Or, if you want to know whether your ISP's DNS server forwards it questions instead of answering them itself, this is just the tool. As you can see, this module is actually not quite useful at all. I got the idea at one point and decided I should give it a try, just because I was so excited with the modular design of Posadis. And after that, I just decided not to remove it, but rather to let it serve as an example of how to write a module that disciminates against clients (e.g. gives some clients back other answers than others).
The "localhost" zone type defined in this module supports standard queries only. It does NOT support zone transfers, so secondary nameservers for these "localhost" domains will also need to use this module, or use similar functionality, if any, in other DNS servers. Furthermore, the DNS server will answer queries for the root domain of the zone only. For other items, it will return NXDOMAIN. The module also supports IPv6.
The "localhost" zone type
Sends back the querier's address. Configuration options:
nslist - List of nameservers for the zone. Note that these nameservers may not be in the reverse-mapping zone itself, since the zone cannot give addresses for the nameservers.
ttl - Time To Live value for the records sent back.
To use the Monitor functionality, add the following to your Posadisrc:
LoadModule "fam"
For a discussion on how to use the Monitor module in your configuration, refer to the "Adding zones".
On Unix, the Monitor module depends on the availability of the File Alteration Monitor program by SGI. For more information, visit:
http://oss.sgi.com/projects/fam/
If you install Posadis from binary packages, you might need to install the Monitor module separately.
/etc/posadisrc
posadis(1), posadis-getroots(1), fam(1)