DESCRIPTION
This is the main configuration file of the Posadis Domain Name Server.
It contains both the configuration directives used by Posadis and a
list of the zones hosted by the DNS server.
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 con-
figuration 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
LOADING MODULES
Posadis has a modular structure for the authoritative zones, so if you
intend to use any functionality that is not in the Posadis core itself,
for example, to use "revmap", "formap" or "localhost" zone types, you
will need to load the appropriate module first. This can be done by
using the "loadmodule" statement in your posadisrc:
LoadModule "revmap"
LoadModule "localhost"
Modules can also supply other functionality, for example, the "monitor"
module can automagically load all master files in a specified direc-
tory. 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 --ver-
sion". 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 Moni-
tor).
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 "local-
host" zone type.
G.ROOT-SERVERS.NET.@192.112.36.4
H.ROOT-SERVERS.NET.@128.63.2.53
I.ROOT-SERVERS.NET.@192.36.148.17
J.ROOT-SERVERS.NET.@192.58.128.30
K.ROOT-SERVERS.NET.@193.0.14.129
L.ROOT-SERVERS.NET.@198.32.64.12
M.ROOT-SERVERS.NET.@202.12.27.33
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.
OPTIONS
Libraries:
libdir - Specify an additional directory to look in for libraries.
Posadis looks by default in the "lib/posadis" subdirectory of your pre-
fix, 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 num-
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 recur-
sion. 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.
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
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 direc-
tory, 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 configura-
tion directory with zone files in them: each file corresponds to a zone
you want to configure. These files have special names: db.<zone> or
<zone>.prm for primary zones, and zn.<zone> and <zone>.znf for non-pri-
mary zones.
You can set the configuration directory by means of the Configdir set-
ting. 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 <type>
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 <file1>, <file2>, ..." to load specific zone files.
Notice that the command lines are indented.
PRIMARY ZONE TYPE
The "primary" zone type is used by Posadis for normal primary authori-
tative DNS operation. A primary DNS server for a zone is a DNS server
that has the zone data on disk itself.
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 @server
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 trans-
fers 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" mes-
sages to the slaves to notify them when the zone changes.
or, if you want to edit your master file manually, use the ";set " pre-
fix:
;set slaves 212.142.29.65, 212.142.29.69
;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, mak-
ing 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
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 sys-
tem: 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 - <other>
Well-known services. Rarely used anymore today, this RR gives informa-
tion 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 proto-
col, usually "TCP" or "UDP", and after that, any services you're run-
ning on it, for example "http", "ftp", "smtp", and so on. Alterna-
tively, 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.
This record is used to specify a mail server for a domain name. For
example, if you send an email message to meilof@acdam.net, 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"
"meilof@acdam.net" )
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 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.
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 experi-
mental 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 con-
nect, 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
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:
<domainname> <ttl> <rrtype> <rrdata>
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:
<domainname> <ttl> <rrtype> (
<rrdata>
)
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 com-
ment. 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 con-
sidered 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 char-
zones that retrieve the zone data using a "zone transfer" from a master
server. It has the following configuration options:
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.
REVMAP MODULE DOCUMENTATION
The revmap module offers a convenient way to automatically do reverse
and forward mapping of domain names for large IP namespaces. It can
algorithmically generate answers to "in-addr.arpa" reverse-mapping
queries by giving back a domain name generated from the IP number. On
the other hand, it also offers a forward-mapping zone companion to con-
vert these domain names back to IP numbers. This is really useful when
you maintain a large site: some programs require any connnecting host
to have valid reverse-mapping information, which can sometimes be quite
a pain.
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:
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.
LOCALHOST MODULE DOCUMENTATION
The localhost module automagically sends back the address of the client
that sent the query to the DNS server. If you send a query to the
server directly, it will thus send back your own IP number (so that you
can find out which IP number you use for internet connectivity), but if
you send a query to a recursive DNS server which will query for the
information, it will find the IP number of the recursive DNS server.
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 name-
servers for these "localhost" domains will also need to use this mod-
ule, or use similar functionality, if any, in other DNS servers. Fur-
thermore, 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
LoadModule "fam"
For a discussion on how to use the Monitor module in your configura-
tion, 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.
FILES
/etc/posadisrc
SEE ALSO
posadis(1), posadis-getroots(1), fam(1)
Meilof Veeningen 0.60.5 posadisrc(5)
Man(1) output converted with
man2html