Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PDNSD.CONF(5)		      File Formats Manual		 PDNSD.CONF(5)

NAME
       pdnsd.conf - The	configuration file for pdnsd

DESCRIPTION
       This  manual  page  describes  the layout of the	pdnsd(8) configuration
       file and	the available configuration options.  The default location  of
       the  file  is ${prefix}/etc/pdnsd.conf. This may	be changed with	the -c
       command line option.  An	example	pdnsd.conf comes with the  pdnsd  dis-
       tribution    in	  the	 documentation	  directory   or   in	${pre-
       fix}/etc/pdnsd.conf.sample.

FILE FORMAT
       The configuration file is divided into sections.	Each section  is  pre-
       fixed  with  the	 section  name and opening curlies ({) and closed with
       closing curlies (}).  In	each section,  configuration  options  can  be
       given in	the form

       option_name=option_value;

       Option value may	be a string literal, a number, a time specification or
       a constant.  In previous	 versions of pdnsd strings had to be  enclosed
       in  quotes  ("),	 but since version 1.1.10 this is no longer necessary,
       unless a	string contains	a special character such as whitespace,	a  to-
       ken that	normally starts	a comment, or one of ",;{} Since version 1.2.9
       a backslash ( inside a string is	interpreted as an escape character, so
       it is possible to include special characters in strings (both quoted or
       unquoted) by preceding them with	a backslash. Some escape sequences are
       in  interpreted	as in the C programming	language, e.g.	becomes	a tab,
       becomes a new-line control char.
       A time specification consists a sequence	of digits followed by  a  one-
       letter  suffix.	 The following suffixes	are recognized:	s (seconds), m
       (minutes), h (hours), d (days) and w (weeks).  If the suffix  is	 miss-
       ing,  seconds are assumed.  If several time specifications are concate-
       nated, their values are added together; e.g. 2h30m  is  interpreted  as
       2*60*60 + 30*60 = 9000 seconds.
       Some  options  take  more  than one value; in this case,	the values are
       separated with commas.
       If you may supply one of	a set of possible values to an option, this is
       noted in	the documentation as (option1|option2|option3|...)
       The  constants  true|false  and yes|no are accepted as synonyms for the
       constants on|off.
       Comments	may be enclosed	in /* and */, nested comments are possible. If
       the # sign or two slashes (//) appear in	the configuration file,	every-
       thing from these	signs to the end of the	current	line is	regarded as  a
       comment and ignored.
       There are examples for nearly all options in the	sample config file.

   global Section
       The  global section specifies parameters	that affect the	overall	behav-
       iour of the server. If you specify multiple global sections,  the  set-
       tings  of those later in	the file will overwrite	the earlier given val-
       ues.
       These are the possible options:

       perm_cache=(number|off);
	      Switch the disk cache off	or supply a maximum cache size in  kB.
	      If the disk cache	is switched off, 8 bytes will still be written
	      to disk.	The memory cache is always 10kB	larger than  the  file
	      cache.  This value is 2048 (2 MB)	by default.

       cache_dir=string;
	      Set the directory	you want to keep the cache in.	The default is
	      "/var/db/pdnsd" (unless pdnsd was	compiled with a	different  de-
	      fault).

       server_port=number;
	      Set  the server port. This is especially useful when you want to
	      start the	server and are not root. Note that you	may  also  not
	      specify uptest=ping in the server	section	as non-root.
	      The  default  port  is  53,  the RFC-standard one. Note that you
	      should only use non-standard ports when you only need clients on
	      your  machine to communicate with	the server; others will	proba-
	      bly fail if the try to contact the server	on the basis of	an  NS
	      record,  since the A record that supplies	the address for	(among
	      others) name servers does	not have a port	number specification.

       server_ip=string;
	      or
       interface=string;
	      Set the IP address pdnsd listens on for requests.	 This  can  be
	      useful  when  the	host has several interfaces and	you want pdnsd
	      not to listen on all interfaces. For example, it is possible  to
	      bind  pdnsd  to  listen on 127.0.0.2 to allow pdnsd to be	a for-
	      warder for  BIND.	  The  default	setting	 for  this  option  is
	      server_ip=any, which means that pdnsd will listen	on all of your
	      local interfaces.	 Presently you can only	 specify  one  address
	      here; if you want	pdnsd to listen	on multiple interfaces but not
	      all you will have	to  specify  server_ip=any  and	 use  firewall
	      rules to restrict	access.
	      The IP address used to need quotation marks around it, but since
	      version 1.1.10 this is no	longer necessary.
	      If pdnsd has been	compiled with both IPv4	and IPv6 support,  and
	      you  want	to specify an IPv6 address here, then unless pdnsd was
	      compiled to start	up in IPv6 mode	by default, you	will  need  to
	      use  the	-6  command-line option	or set run_ipv4=off first (see
	      below) in	order to ensure	that the IPv6 address is  parsed  cor-
	      rectly.
	      If pdnsd is running in IPv6 mode and you specify an IPv4 address
	      here, it will automatically be mapped to an IPv6 address.
	      New in version 1.2: You may also give the	name of	 an  interface
	      such  as "lo" or "eth0" here, instead of an IP address (this has
	      been tested on Linux, and	may or may not	work  on  other	 plat-
	      forms).	pdnsd  will  not  bind to the interface	name, but will
	      look up the address of the interface at start-up and  listen  on
	      that  address.  If  the  address	of the interface changes while
	      pdnsd is running,	pdnsd will not notice that. You	will  need  to
	      restart pdnsd in that case.

       outgoing_ip=string;
	      or
       outside_interface=string;
	      New  in  version 1.2.9: Set the IP address of the	interface used
	      by pdnsd for outgoing queries.  This can be useful when the host
	      has  several  interfaces	and  you  want	pdnsd to send outgoing
	      queries via only one of them.  For example, if  pdnsd is running
	      on  a  host  with	one interface with IP address 192.168.1.1 con-
	      nected to	 the  local  network,  and  another  with  IP  address
	      123.xxx.yyy.zzz  connected  to  the  internet,  you  may specify
	      server_ip=192.168.1.1 and	outgoing_ip=123.xxx.yyy.zzz to enforce
	      that pdnsd only responds to queries received from	the local net-
	      work, and	only sends outgoing queries  via  the  interface  con-
	      nected to	the internet.
	      The default setting for this option is any, which	means that the
	      kernel is	free to	decide which interface to use.	Like with  the
	      server_ip	 option,  you  may  also give the name of an interface
	      here, instead of an IP address.

       linkdown_kluge=(on|off);
	      This option enables a kluge that some people  might  need:  when
	      all  servers  are	marked down, with this option set the cache is
	      not even used when a query is received, and a DNS	error  is  re-
	      turned  in  any case. The	only exception from this is that local
	      records (as specified in rr and source sections are still	served
	      normally.	  In  general, you probably want to get	cached entries
	      even when	the network is down, so	this defaults to off.

       max_ttl=timespec;
	      This option sets the maximum time	a record is held in cache. All
	      dns  resource  records  have  a time to live field that says for
	      what period of time the record may be cached before it needs  to
	      be requeried. If this is more than the value given with max_ttl,
	      this time	to live	value is set to	max_ttl.  This is done to pre-
	      vent  records  from being	cached an inappropriate	long period of
	      time, because that is almost never a good	thing to  do.  Default
	      is 604800s (one week).

       min_ttl=timespec;
	      This option sets the minimum time	a record is held in cache. All
	      dns resource records have	a time to live	field  that  says  for
	      what  period of time the record may be cached before it needs to
	      be requeried. If this is less than the value given with min_ttl,
	      this  time to live value is set to min_ttl.  Default is 120 sec-
	      onds.

       neg_ttl=timespec;
	      This option sets the time	that negatively	 cached	 records  will
	      remain  valid in the cache if no time to live can	be determined.
	      This is always the case when whole domains are being cached neg-
	      atively,	and  additionally  when	 record	types are cached nega-
	      tively for a domain for which no SOA record is known  to	pdnsd.
	      If a SOA is present, the ttl of the SOA is taken.

       neg_rrs_pol=(on|off|auth|default);
	      This  sets  the  RR  set policy for negative caching; this tells
	      pdnsd under which	circumstances it should	cache  a  record  type
	      negatively  for  a  certain  domain.  off	will turn the negative
	      caching of record	types off, on will always add a	negative cache
	      entry  when  a name server did not return	a record type we asked
	      it for, and auth will only add such entries if the  answer  came
	      from an authoritative name server	for that domain.
	      New  in version 1.2.8: The default setting will add a negatively
	      cached record if either the answer was authoritive or the	answer
	      indicated	 the  name  server had "recursion available" while the
	      query explicitly requested such recursion.
	      The preset is "default" (used to be auth).

       neg_domain_pol=(on|off|auth);
	      This is  analogue	 to  neg_rrs_pol  for  whole  domain  negative
	      caching.	It  should  be safe to set this	on, because I have not
	      seen a caching server that will falsely claim that a domain does
	      not exist.
	      The default is auth.

       run_as=string;
	      This option allows you to	let pdnsd change its user and group id
	      after operations that needed privileges  have  been  done.  This
	      helps  minimize security risks and is therefore recommended. The
	      supplied string gives a user name	 whose	user  id  and  primary
	      group id are taken.
	      A	little more details: after reading the config file, becoming a
	      daemon (if specified) and	starting the server status thread, the
	      main  thread  changes  its  gid and uid, as do all newly created
	      threads thereafter. By taking another uid	and gid, those threads
	      run  with	the privileges of the specified	user.  Under Linux and
	      FreeBSD, the server status thread	runs with the original	privi-
	      leges  only when the strict_setuid option	is set to off (see be-
	      low, on by default), because these may be	needed	for  exec  up-
	      tests.  The  manager thread also retains its original privileges
	      in this case.  You should	take care that the  user  you  specify
	      has write	permissions on your cache file and status pipe (if you
	      need a status pipe). You should look out for error messages like
	      "permission  denied"  and	 "operation not	permitted" to discover
	      permission problems.

       strict_setuid=(on|off);
	      When used	together with the run_as option, this option lets  you
	      specify that all threads of the program will run with the	privi-
	      leges of the run_as user.	This provides higher security than the
	      normal run_as option, but	is not always possible.	See the	run_as
	      option for further discussion.
	      This option is on	by default.
	      Note that	this option has	no effect on Non-Linux systems.

       paranoid=(on|off);
	      Normally,	pdnsd queries all servers in recursive mode (i.e.  in-
	      structs  servers	to query other servers themselves if possible,
	      and to give back answers for domains that	may not	be in its  au-
	      thority),	 and  accepts  additional records with information for
	      servers that are not in the authority  of	 the  queried  server.
	      This opens the possibility of so-called cache poisoning: a mali-
	      cious attacker might set up a dns	server that, when queried, re-
	      turns  forged  additional	 records.  This	 way, he might replace
	      trusted servers with his own ones	by making your dns server  re-
	      turn  bad	IP addresses. This option protects you from cache poi-
	      soning by	rejecting additional records that do not describe  do-
	      mains  in	 the queried servers authority space and not doing re-
	      cursive queries any more.	 An exception to  this	rule  are  the
	      servers you specify in your config file, which are trusted.
	      The  penalty  is a possible performance decrease,	in particular,
	      more queries might be necessary for the same operation.
	      You should also notice that there	may be other similar  security
	      problems,	 which	are essentially	problems of the	DNS, i.e.  any
	      "traditional" server has them (the DNS security extensions solve
	      these problems, but are not widely supported).  One of this vul-
	      nerabilities is that an attacker may bombard you with forged an-
	      swers  in	hopes that one may match a query you have done.	If you
	      have done	such a query, one in 65536 forged packets will be suc-
	      cesful (i.e. an average packet count of 32768 is needed for that
	      attack). pdnsd can use TCP for queries,  which  has  a  slightly
	      higher  overhead,	but is much less vulnerable to such attacks on
	      sane operating systems. Also, pdnsd chooses random query ids, so
	      that an attacker cannot take a shortcut. If the attacker is able
	      to listen	to your	network	traffic,  this	attack	is  relatively
	      easy, though.
	      This  vulnerability  is not pdnsd's fault, and is	possible using
	      any conventional name server (pdnsd is perhaps a little more se-
	      cured against this type of attacks if you	make it	use TCP).
	      The paranoid option is off by default.

       ignore_cd=(on|off);
	      New  in  version 1.2.8: This option lets you specify that	the CD
	      bit of a DNS query will be ignored.  Otherwise pdnsd will	 reply
	      FORMERR  to clients that set this	bit in a query.	 It is safe to
	      enable this option, as the CD bit	refers to 'Checking  Disabled'
	      which means that the client will accept non-authenticated	data.
	      This  option  is	on by default. Turn it off if you want the old
	      behaviour	(before	version	1.2.8).

       scheme_file=string;
	      In addition to normal uptests, you may specify that some servers
	      shall  only be queried when a certain pcmcia-cs scheme is	active
	      (only under linux). For that, pdnsd needs	to know	where the file
	      resides that holds the pcmcia scheme information.	Normally, this
	      is either	/var/lib/pcmcia/scheme or /var/state/pcmcia/scheme.

       status_ctl=(on|off);
	      This has the same	effect as the -s command line option: the sta-
	      tus control is enabled when on is	specified.
	      Added by Paul Rombouts: Note that	pdnsd-ctl allows run-time con-
	      figuration of pdnsd, even	the IP addesses	of  the	 name  servers
	      can be changed. If you're	not using pdnsd-ctl and	you want maxi-
	      mum security, you	should not enable this option. It is  disabled
	      by default.

       daemon=(on|off);
	      This has the same	effect as the -d command line option: the dae-
	      mon mode is enabled when on is specified.
	      Default is off.

       tcp_server=(on|off);
	      tcp_server=on has	the same effect	as the -t  or  --tcp  command-
	      line  option: it enables TCP serving.  Similarly,	tcp_server=off
	      is like the --notcp command-line option.
	      Default is on.

       pid_file=string;
	      This has the same	effect as the -p command line option: you  can
	      specify a	file that pdnsd	will write its pid into	when it	starts
	      in daemon	mode.

       verbosity=number;
	      This has the same	effect as the -v command line option: you  can
	      set the verbosity	of pdnsd's messages with it. The argument is a
	      number between 0 (few messages) to 3 (most messages).

       query_method=(tcp_only|udp_only|tcp_udp|udp_tcp);
	      This has the same	effect as the -m command  line	option.	  Read
	      the documentation	for the	command	line option on this.  tcp_only
	      corresponds to the to, udp_only to the uo, tcp_udp to the	tu and
	      udp_tcp to the ut	argument of the	command	line option.
	      If you use query_method=tcp_udp, it is recommended that you also
	      set the global timeout option to	at  least  twice  the  longest
	      server timeout.

       run_ipv4=(on|off);
	      This has the same	effect as the -4 or -6 command line option: if
	      on is specified, IPv4 support is enabled,	and  IPv6  support  is
	      disabled (if available).	If off is specified, IPv4 will be dis-
	      abled and	IPv6 will be enabled.  For this	option to be  meaning-
	      ful,  pdnsd  needs  to be	compiled with support for the protocol
	      you choose.  If pdnsd was	compiled with both IPv4	and IPv6  sup-
	      port,  and  you want to include IPv6 addresses in	the configura-
	      tion file, you will probably need	to specify run_ipv4=off	 first
	      to ensure	that the IPv6 addresses	are parsed correctly.

       debug=(on|off);
	      This  has	the same effect	as the -g command line option: the de-
	      bugging messages are enabled when	on is specified.

       ctl_perms=number;
	      This option allows you to	set  the  file	permissions  that  the
	      pdnsd  status  control  socket  will have. These are the same as
	      file permissions.	The owner of the file will be the run_as user,
	      or,  if  none  is	 specified, the	user who started pdnsd.	If you
	      want to specify the permissions in octal (as usual), don't  for-
	      get  the	leading	zero (0600 instead of 600!). To	use the	status
	      control, write access is needed. The default is 0600  (only  the
	      owner may	read or	write).
	      Please  note that	the socket is kept in the cache	directory, and
	      that the cache directory permissions might also need to  be  ad-
	      justed.  Please ensure that the cache directory is not writeable
	      for untrusted users.

       proc_limit=number;
	      With this	option,	you can	set a limit on the pdnsd threads  that
	      will  be	active	simultaneously.	 If  this  number is exceeded,
	      queries are queued and may be delayed some time.	See  also  the
	      procq_limit option.
	      The default for this option is 40.

       procq_limit=number;
	      When  the	 query thread limit proc_limit is exceeded, connection
	      attempts to pdnsd	will be	queued.	 With this option, you can set
	      the  maximum queue length.  If this length is also exceeded, the
	      incoming queries will be dropped.	 That means that  tcp  connec-
	      tions will be closed and udp queries will	just be	dropped, which
	      will probably cause the querying resolver	to wait	for an	answer
	      until it times out.
	      See    also    the    proc_limit	  option.    A	  maximum   of
	      proc_limit+procq_limit query threads will	exist at any one  time
	      (plus  3	to  6 threads that will	always be present depending on
	      your configuration).
	      The default for this option is 60.

       tcp_qtimeout=timespec;
	      This option sets a timeout for tcp queries. If no	full query has
	      been  received  on  a tcp	connection after that time has passed,
	      the connection will be closed. The  default  is  set  using  the
	      --with-tcp-qtimeout option to configure.

       par_queries=number;
	      This  option  used  to  set the maximum number of	remote servers
	      that would be queried simultaneously, for	every query that pdnsd
	      receives.
	      Since  version  1.1.11,  the  meaning of this option has changed
	      slightly.	 It is now the increment with which the	number of par-
	      allel  queries is	increased when the previous set	of servers has
	      timed out.  For example, if we have  a  list  server1,  server2,
	      server3, etc. of available servers and par_queries=2, then pdnsd
	      will first send queries to server1 and server2, and  listen  for
	      responses	from these servers.
	      If  these	 servers  do not send a	reply within their timeout pe-
	      riod, pdnsd will send additional queries to server3 and server4,
	      and  listen  for	responses  from	 server1, server2, server3 and
	      server4, and so on until a useful	reply is received or the  list
	      is exhausted.
	      In  the  worst  case  there  will	 be pending queries to all the
	      servers in the list of available servers.	 We may	be using  more
	      system  resources	this way (but only if the first	servers	in the
	      list are slow or unresponsive), but the  advantage  is  that  we
	      have  a  greater	chance	of catching a reply.  After all, if we
	      wait longer anyway, why not for more servers.
	      See also the explanation of the global timeout option below.
	      1	or 2 are good values for this option.  The default is  set  at
	      compile time using the --with-par-queries	option to configure.

       timeout=timespec;
	      This  is	the  global  timeout  parameter	for dns	queries.  This
	      specifies	the minimum period of time pdnsd will wait after send-
	      ing  the first query to a	remote server before giving up without
	      having received a	reply. The timeout options in  the  configura-
	      tion  file  are  now only	minimum	timeout	intervals. Setting the
	      global timeout option makes it possible to specify  quite	 short
	      timeout  intervals in the	server sections	(see below). This will
	      have the	effect	that  pdnsd  will  start  querying  additional
	      servers  fairly quickly if the first servers are slow to respond
	      (but will	still continue to listen for responses from the	 first
	      ones).  This  may	 allow	pdnsd to get an	answer more quickly in
	      certain situations.
	      If you use query_method=tcp_udp it is recommended	that you  make
	      the global timeout at least twice	as large as the	largest	server
	      timeout, otherwise pdnsd may not have time to try	a UDP query if
	      a	TCP connection times out.
	      Default value is 0.

       randomize_recs=(on|off);
	      If  this	option	is  turned on, pdnsd will randomly reorder the
	      cached records of	one type when creating an  answer.  This  sup-
	      ports  round-robin  DNS  schemes	and  increases fail safety for
	      hosts with multiple IP addresses,	so  this  is  usually  a  good
	      idea.
	      On by default.

       query_port_start=(number|none);
	      If  a  number is given, this defines the start of	the port range
	      used for queries of pdnsd. The value given must be >= 1024.  The
	      purpose of this option is	to aid certain firewall	configurations
	      that are based on	the source port. Please	keep in	mind that  an-
	      other  application  may bind a port in that range, so a stateful
	      firewall using target port and/or	process	uid may	be more	effec-
	      tive.  In	 case a	query start port is given pdnsd	uses this port
	      as the first port	of a specified port range (see query_port_end)
	      used for queries.	 pdnsd will try	to randomly select a free port
	      from this	range as local port for	the query.
	      To ensure	that there are enough ports  for  pdnsd	 to  use,  the
	      range  between query_port_start and query_port_end should	be ad-
	      justed to	at least (par_queries *	proc_limit).  A	 larger	 range
	      is  highly  recommended  for  security reasons, and also because
	      other applications may allocate ports in that range.  If	possi-
	      ble,  this  range	should be kept out of the space	that other ap-
	      plications usually use.
	      The default for this option is 1024. Together with  the  default
	      value  of	 query_port_end,  this makes it	the hardest for	an at-
	      tacker to	guess the source port used by the pdnsd	resolver.   If
	      you  specify  none  here,	 pdnsd	will let the kernel choose the
	      source port, but this may	leave pdnsd more vulnerable to an  at-
	      tack.

       query_port_end=number;
	      Used  if	query_port_start is not	none. Defines the last port of
	      the range	started	by query_port_start used for querys by	pdnsd.
	      The  default is 65535, which is also the maximum legal value for
	      this   option.	For   details	see   the    description    of
	      query_port_start.

       delegation_only=string;
	      Added  by	 Paul  Rombouts:  This option specifies	a "delegation-
	      only" zone.  This	means that if pdnsd receives  a	 query	for  a
	      name  that is in a subdomain of a	"delegation-only" zone but the
	      remote name server returns an answer with	an  authority  section
	      lacking  any  NS RRs for subdomains of that zone,	pdnsd will an-
	      swer NXDOMAIN (unknown domain).  This feature can	 be  used  for
	      undoing the undesired effects of DNS "wildcards".	Several	"dele-
	      gation-only" zones may be	specified together.   If  you  specify
	      root  servers  in	 a server section it is	important that you set
	      root_server=on in	such a section.
	      Example:

	      delegation_only="com","net";

	      This feature is off by default. It is recommended	that you  only
	      use  this	 feature  if  you actually need	it, because there is a
	      risk that	some legitimate	names will be blocked,	especially  if
	      the  remote  name	 servers  queried by pdnsd return answers with
	      empty authority sections.

       ipv4_6_prefix=string;
	      This option has the same effect as the -i	 command-line  option.
	      When  pdnsd  runs	in IPv6	mode, this option specifies the	prefix
	      pdnsd uses to convert IPv4 addresses in the  configuration  file
	      (or  addresses  specified	 with  pdnsd-ctl)  to  IPv6-mapped ad-
	      dresses.	The string must	be a  valid  IPv6  address.  Only  the
	      first 96 bits are	used.  Note that this only effects the parsing
	      of IPv4 addresses	listed after this option.
	      The default is "::ffff.0.0.0.0".

       use_nss=(on|off);
	      If this option is	turned on, pdnsd will call initgroups()	to set
	      up  the  group  access list, whenever pdnsd changes its user and
	      group id (see run_as option).  There is a	possible snag, though,
	      if  initgroups()	uses NSS (Name Service Switch) and NSS in turn
	      uses DNS.	In such	a case you may experience lengthy timeouts and
	      stalls.	By  setting  use_nss=off,  you	can  disable the init-
	      groups() call (only possible in versions 1.2.5 and later).
	      This option was contributed by Jan-Marek Glogowski.
	      On by default.

       udpbufsize=number;
	      New in version 1.2.9: This option	sets the upper	limit  on  the
	      size of UDP DNS messages.	The default is 1024.
	      See also the edns_query server option below.

   server Section
       Each  server  section specifies a set of	name servers that pdnsd	should
       try to get resource records or authoritative  name  server  information
       from. The servers are queried in	the order of their appearance (or par-
       allel to	a limited extend).  If one fails, the next one is taken	and so
       on.
       You  probably  want to specify  the dns server in your LAN, the caching
       dns servers of your internet provider or	even a list of root servers in
       one or more server sections.
       The supported options in	this section are:

       label=string;
	      Specify  a label for the server section. This can	be used	to re-
	      fer to this section when	using  pdnsd-ctl,  the	pdnsd  control
	      utility.
	      You  can give several server sections the	same label, but	if you
	      want to change the addresses of a	server section (see ip	option
	      below)	 during	    run-time	 with	 "pdnsd-ctl server la-
	      bel up dns1,dns2,...", the label must be unique.

       ip=string;
	      Give the IP (the address,	not the	host name) of the server.
	      Multiple IP addresses can	be given per server section.  This can
	      be  done	by entering multiple lines of the form ip=string; or a
	      single line like this:

	      ip=string,string,string;

	      IP addresses do not have to be specified	in  the	 configuration
	      file.   A	 server	section	without	IP addresses will remain inac-
	      tive until it is assigned	one or more addresses with  pdnsd-ctl,
	      the pdnsd	control	utility.
	      If  pdnsd	has been compiled with both IPv4 and IPv6 support, any
	      IPv6 addresses you specify here will be skipped with  a  warning
	      message,	unless	pdnsd  is  running in IPv6 mode.  Thus,	unless
	      pdnsd was	compiled to startup in IPv6 mode by default, you  need
	      to use the command-line option -6	or set run_ipv4=off first (see
	      global section) in order	to  ensure  that  IPv6	addresses  are
	      parsed correctly.
	      If pdnsd is running in IPv6 mode and you specify an IPv4 address
	      here, it will automatically be mapped to an IPv6 address.

       file=string;
	      New in version 1.2: This option allows you to give the name of a
	      resolv.conf-style	 file.	 Of the	lines beginning	with the name-
	      server keyword, the second field will be parsed  as  an  IP  ad-
	      dress,  as if it were specified with the ip= option. The remain-
	      ing lines	will be	ignored.  If the contents of the file  changes
	      while  pdnsd is running, you can make pdnsd aware	of the changes
	      through the use of pdnsd-ctl, the	pdnsd control  utility.	  This
	      is  usually  most	 conveniently  done  by	 placing  the  command
	      "pdnsd-ctl config" in a script that is automatically  run	 when-
	      ever the DNS configuration changes.
	      For  example,  suppose you have a	ppp client that	writes the DNS
	      configuration for	your ISP to the	file /etc/ppp/resolv.conf  and
	      runs  the	 script	/etc/ppp/ip-up when a new connection is	estab-
	      lished. One way of ensuring that pdnsd is	 automatically	recon-
	      figured  is  to  add  a  server  section in the config file with
	      file=/etc/ppp/resolv.conf	   and	  to	add    the     command
	      "pdnsd-ctl config" to /etc/ppp/ip-up.

       port=number;
	      Give  the	 port the remote name server listens on. Default is 53
	      (the official dns	port)

       uptest=(ping|none|if|dev|diald|exec|query);
	      Determine	the method to check whether the	server	is  available.
	      Currently	defined	methods	are:

	      o	 ping:	Send an	ICMP_ECHO request to the server. If it doesn't
	      respond within the timeout, it is	regarded to be unavailable un-
	      til the next probe.

	      o	 none:	The  availability status is not	changed, only the time
	      stamp is updated.

	      o	if: Check whether the interface	(specified in  the  interface=
	      option)  is  existent,  up and running. This currently works for
	      all "ordinary" network  interfaces,  interfaces  that  disappear
	      when  down  (e.g.	 ppp?),	and additionally for Linux isdn	inter-
	      faces (as	of kernel 2.2).	Note that you need a /dev/isdninfo de-
	      vice  file (major#45, minor#255),	or the isdn uptest will	always
	      fail.

	      o	dev and	diald: Perform an if uptest, and, if that was  succes-
	      ful,  additionally  check	 whether a program is running that has
	      locked a given (modem-) device. The needed parameters are	an in-
	      terface  (specified as for the if	uptest,	e.g. "ppp0") and a de-
	      vice relative to /dev (e.g.  "modem"  for	 /dev/modem  specified
	      using  the  device= option.  pdnsd will then look	for a pid file
	      for the given interface in /var/lock  (e.g.   /var/run/ppp0.pid)
	      and for a	lockfile for the given device (e.g. /var/lock/LCK..mo-
	      dem), and	then test whether the locking process is  the  process
	      that  created  the  pid file and this process is still alive. If
	      this is the case,	the normal if uptest is	executed for the given
	      interface.
	      The dev option is	for pppd dial-on-demand, diald is the same for
	      diald users.

	      o	exec: Executes a  given	 command  in  the  /bin/sh  shell  (as
	      /bin/sh  -c <command>) and evaluates the result (the return code
	      of the last command) in  the  shell's  way  of  handling	return
	      codes, i.e. 0 indicates success, all other indicate failure. The
	      shell's process name will	be uptest_sh.  The  command  is	 given
	      with  the	 uptest_cmd  option  (see below).  For secuity issues,
	      also see that entry.

	      o	query: New in version 1.2: This	works like the ping test,  ex-
	      cept it sends an (empty) DNS query to the	remote server.	If the
	      server sends a well-formed response back within the timeout  pe-
	      riod  (except SERVFAIL), it will be regarded as available.  This
	      test is useful if	a remote server	does not respond to  ICMP_ECHO
	      requests at all, which unfortunately is quite common these days.
	      It can also happen that a	remote server is  online  but  ignores
	      empty   DNS   queries.	Then   you   will  need	 the  set  the
	      query_test_name option (see below).  In  many  cases  this  test
	      will  be a more reliable indicator of availability than the ones
	      mentioned	before.

	      The default value	is none.

	      NOTE: If you use on-demand dialing, use none, if,	dev, diald  or
	      exec, since ping or query	will send packets in the specified in-
	      terval and the interface will thus frequently dial!

       ping_timeout=number;
	      Sets the timeout for the ping test in tenths  of	seconds	 (this
	      unit  is used for	legacy reasons;	actually the current implemen-
	      tation is	only accurate to a second).
	      The default is 600 (one minute).

       ping_ip=string;
	      The IP address for the ping test.	The default is the IP  of  the
	      name server.

       query_test_name=string;
	      New in version 1.2.9: Sets the name to be	queried	when using up-
	      test=query availability test.  If	the  string  is	 the  unquoted
	      constant none, an	empty query is used (this the default),	other-
	      wise a query of type A will be sent for the domain  name	speci-
	      fied  here.  It is not necessary for the domain name to exist or
	      have a record of type A in order for the uptest to succeed.
	      If the the remote	server ignores empty queries, you will	proba-
	      bly want to set query_test_name="." (the root domain).

       uptest_cmd=string,string;
	      or
       uptest_cmd=string;
	      Sets  the	 command  for  the  uptest=exec	 function to the first
	      string.  If the second string is given, it specifies a user with
	      whose user id and	primary	group id the command is	executed.
	      This  is	especially  useful  if you are executing the server as
	      root, but	do not want the	uptest to be performed with root priv-
	      ileges.  In fact,	you should never execute the uptest as root if
	      you can help it.
	      If the server is running setuid or setgid, the  privileges  thus
	      gained are attempted to be dropped even before changing identity
	      to the specified user to prevent setuid/gid security holes (oth-
	      erwise,  any  user  might	execute	commands as root if you	setuid
	      the executable).
	      Note that	this is	not always possible,  and  that	 pdnsd	should
	      never be installed as setuid or setgid.  The command is executed
	      using /bin/sh, so	you should be able to use shell	 builtin  com-
	      mands.

       interval=(timespec|onquery|ontimeout);
	      Sets  the	 interval  for	the server up-test. The	default	is 900
	      seconds; however,	a test is forced when a	query  times  out  and
	      the timestamp is reset then.
	      If  you specify onquery instead of a timeout, the	interface will
	      be tested	before every query. This is to	prevent	 automatically
	      dialing  interfaces (diald/pppd or ippp) to dial on dns queries.
	      It is intended to	be used	in connection with an  interface-test-
	      ing uptest ;-)
	      Note  that  using	 uptest=exec,  you  might run into performance
	      problems on slow machines	when you use that option.   DON'T  use
	      onquery with uptest=ping or uptest=query,	as it may cause	delays
	      if the server does not answer (btw, it doesn't make  sense  any-
	      way).  Note also that using onquery is no	guarantee that the in-
	      terface will not be used.	When another  (reachable)  dns	server
	      tells  pdnsd to query a third dns	server for data, pdnsd will do
	      that and has no means of checking	whether	this will dial up  the
	      interface	or not.	 This however should be	a rare situation.
	      New  in  version 1.2.3: A	third possibility is to	specify	inter-
	      val=ontimeout.  In  this	case  the  server  is  not  tested  at
	      startup/reconfiguration,	nor at regular intervals, but only af-
	      ter a DNS	query to a server times	out. Certain types of  network
	      problems such as a refused connection will also cause the	server
	      to be considered unavailable.  However, once  a  server  is  de-
	      clared  dead  it	is never considered again unless it is revived
	      using a pdnsd-ctl	config or server  command.   The  idea	behind
	      this  option  is to minimize uptests by assuming all servers are
	      available	until there is reason to believe otherwise.

       interface=string;
	      The network interface (or	network	device,	e.g. "eth0")  for  the
	      uptest=if	option.	 Must be specified if uptest=if	is given.

       device=string;
	      The  (modem-) device that	is used	for the	dev uptest. If you use
	      this for a dial-on-demand	ppp uptest (together with uptest=dev),
	      you  need	 to enter the device you are using for your pppd here,
	      e.g. modem for /dev/modem.
	      Must be specified	if uptest=dev is given.

       timeout=timespec;
	      Set the timeout for the dns query. The default is	 120  seconds.
	      You probably want	to set this lower.
	      Timeouts specified in the	configuration file are only treated as
	      the minimum period of time to wait for a reply. A	queries	 to  a
	      remote server are	not canceled until a useful reply has been re-
	      ceived, or all the other queries have timed out or failed.
	      If you have also set the global timeout option, you may consider
	      setting  a  fairly small value here.  See	the explanation	of the
	      timeout option in	the global section for what that means.

       purge_cache=(on|off);
	      In every fetched dns record, there is  a	cache  timeout	given,
	      which specifies how long the fetched data	may be cached until it
	      needs to be reloaded. If purge_cache is set to  off,  the	 stale
	      records are not purged (unless the cache size would be exceeded,
	      in this case the oldest records are purged).  Instead, they  are
	      still served if they cannot succesfully be updated (e.g. because
	      all servers are down).
	      Default is off.

       caching=(on|off);
	      Specifies	if caching shall be performed for this server at  all.
	      Default is on.

       lean_query=(on|off);
	      Specifies	 whether  to  use the "lean" query mode. In this mode,
	      only the information actually queried from pdnsd is resolved and
	      cached.  This has	the advantage that usually less	cache space is
	      used and the query is usually faster. In 90% of the cases,  only
	      address  (A)  records  are needed	anyway.	If switched off, pdnsd
	      will always cache	all data about a host it  can  find  and  will
	      specifically ask for all available records (well,	at least it is
	      a	good approximation for what it really does ;-)	This  will  of
	      course increase the answer packet	sizes.
	      Some  buggy  name	servers	may not	deliver	CNAME records when not
	      asked for	all records. I do not know if such servers are around,
	      but  if you have trouble resolving certain host names, try turn-
	      ing this option off.
	      A	last note: If you use multiple pdnsd's that access each	other,
	      turning this option on is	probably a big win.
	      This on by default.

       edns_query=(on|off);
	      New  in  version 1.2.9: Specifies	whether	to use EDNS (Extension
	      mechanisms for DNS) for outgoing	queries.   Currently  this  is
	      only  useful  for	 allowing  UDP	message	 sizes larger than 512
	      bytes.  Note that	setting	this option on can  give  problems  in
	      combination with some legacy systems or software,	including, em-
	      barrassingly enough, previous versions of	pdnsd.
	      The default is off, but if your network can handle UDP  payloads
	      significantly  larger  than  512 bytes, the recommended value is
	      on.
	      Note that	this option only effects outgoing  queries.  If	 pdnsd
	      receives a query using EDNS, it will reply using EDNS regardless
	      of the value of this option.

	      See also the udpbufsize option above.

       scheme=string;
	      You can specify a	pcmcia-cs scheme that is used in  addition  to
	      the  uptests. If you specify a scheme here, the server this sec-
	      tion is for will only be queries if the given scheme is  active.
	      Shell  wildcards (* and ?) are allowed in	the string under their
	      special meanings.	You need to use	the scheme_file	option on  the
	      global section to	make this option work.

       preset=(on|off);
	      This  allows you to specify the initial state of a server	before
	      any uptest is performed.	on specifies that the  server  is  re-
	      garded  available. The default is	on.  This is especially	useful
	      when you set uptest=none;	and want to change  the	 status	 of  a
	      server only via pdnsd-ctl.

       proxy_only=(on|off);
	      When  this option	is set to on, answers given by the servers are
	      always accepted, and no other servers (as, for  example,	speci-
	      fied  in the NS records of the query domain) are queried.	If you
	      do not turn this option on, pdnsd	will do	such queries  in  some
	      cases (in	particular when	processing ANY queries).
	      This option is useful when you do	not want pdnsd to make connec-
	      tions to outside servers for some	reasons	(e.g. when a  firewall
	      is blocking such queries).
	      I	recommend that you turn	on lean_query when using this option.
	      Default is off.

       root_server=(on|off|discover);
	      Set  this	option to on if	the servers specified in a section are
	      root servers.  A root server will	typically only give  the  name
	      servers	for  the  top-level  domain  in	 its  reply.   Setting
	      root_server=on will cause	pdnsd to try to	use cached information
	      about  top-level	domains	to reduce to number of queries to root
	      servers, making the resolving of new names more efficient.   You
	      can  get a list of available root	servers	by running the command
	      "dig . ns".
	      This option is also necessary if you use the delegation_only op-
	      tion.
	      New in version 1.2.8: This option	may also be set	to "discover".
	      This will	cause pdnsd to query the servers provided with the ip=
	      option  to obtain	the full list of root servers. The root-server
	      addresses	will replace the addresses specified with the ip=  op-
	      tion.   This  will  only	be  done  once	on startup, or after a
	      "pdnsd-ctl config" command.  In this case	the name servers spec-
	      ified  with  the	ip= option don't have to be root servers, they
	      just have	to know	the names and addresses	of the	root  servers.
	      After  root-server  discovery  pdnsd  will  behave  just	as  if
	      root_server=on had been specified.
	      Default is off.

       randomize_servers=(on|off);
	      New in version 1.2.6: Set	this option to on to  give  each  name
	      server in	this section an	equal chance of	being queried. If this
	      option is	off, the name servers are always queried starting with
	      the first	one specified. Even with this option on, the query or-
	      der is not truly random. Only the	first server is	selected  ran-
	      domly;  the  following  ones  are	 queried in consecutive	order,
	      wrapping around to the beginning of the list  when  the  end  is
	      reached.	 Note that this	option only effects the	order within a
	      section. The servers in the first	(active)  section  are	always
	      queried before those in the second one, etc.
	       The  default is off, but	if you are resolving from root servers
	      setting this option on is	highly recommended. If	root_server=on
	      this option also effects the query order of the name servers for
	      the top-level domains.

       reject=string;
	      New in version 1.2.6: This option	can be used to make pdnsd  re-
	      ject replies that	contain	certain	IP addresses.  You can specify
	      a	single IP address, which will be matched exactly, or  a	 range
	      of addresses using an address/mask pair.	The mask can be	speci-
	      fied as a	simple integer,	indicating the	number	of  initial  1
	      bits  in	the  mask, or in the usual IP address notation.	IP ad-
	      dresses may be either IPv4 or IPv6 (provided there is sufficient
	      support  in the C	libraries and support for AAAA records was not
	      disabled).  When addresses in the	reject list are	compared  with
	      those  in	 a  reply, only	the bits corresponding to those	set in
	      the netmask are significant, the rest are	ignored.
	      Multiple addresses or address/mask pairs may be specified;  this
	      can  be  done  by	 entering  multiple  lines  of	the  form  re-
	      ject=string; or a	single line like this:

	      reject=string,string,string;

	      How pdnsd	reacts when an address in the reply matches one	in the
	      reject list, depends on the reject_policy	option,	see below.

       reject_policy=(fail|negate);
	      New  in  version	1.2.6:	This option determines what pdnsd does
	      when an address in the reply from	a name server matches the  re-
	      ject list	(see above). If	this option is set to fail, pdnsd will
	      try another server, or, if there no more servers to try,	return
	      the answer SERVFAIL. If this option is set to negate, pdnsd will
	      immediately return the answer NXDOMAIN (unknown domain)  without
	      querying	additional  servers. The fail setting is useful	if you
	      don't always trust the servers in	this section, but do trust the
	      servers in the following section.	The negate setting can be used
	      to completely censor certain IP  addresses.  In  this  case  you
	      should  put  the	same  reject list in every server section, and
	      also set the reject_recursively option (see below) to true.
	      The default is fail.

       reject_recursively=(on|off);
	      New in version 1.2.6: Normally pdnsd checks for addresses	in the
	      reject  list (see	above) only when the reply comes directly from
	      a	name server listed in the configuration	file.  With  this  op-
	      tion  set	 to on,	pdnsd will also	do this	check for name servers
	      that where obtained from NS records in the authority section  of
	      a	previous reply (which was incomplete and non-authoritative).
	      Default is off.

       policy=(included|excluded|simple_only|fqdn_only);
	      pdnsd  supports  inclusion/exclusion  lists for server sections:
	      with include= and	exclude= (see below) you  can  specify	domain
	      names  for  which	 this server will be used or will not be used.
	      The first	match counts (i.e., the	first include or exclude  rule
	      in  a  server section that matches a domain name is applied, and
	      the search for other rules is terminated). If no rule matched  a
	      given  domain  name,  the	policy=	option determines whether this
	      server is	used for the lookup for	that  domain  name;  when  in-
	      cluded  is given,	the server will	be asked, and when excluded is
	      given, it	will not.  If simple_only is given the server will  be
	      used  if	the  name  to lookup is	a simple (single-label)	domain
	      name, on the other hand if fqdn_only is given the	server will be
	      used  only  for names consisting of two or more labels (i.e. the
	      name has at least	one dot	in-between).
	      If no server is available	for a queried domain, pdnsd  will  re-
	      turn  an	error message to the client that usually will stop the
	      client's attempts	to resolve a specific domain from this	server
	      (the  libc resolver will e.g. return an error to the application
	      that tried to resolve the	domain if no other servers are	avail-
	      able in the resolv.conf).	 This may be of	use sometimes.
	      Note: the	simple_only and	fqdn_only constants were added by Paul
	      Rombouts.	 They are useful for controlling  which	 name  servers
	      (if  any)	will be	used by	pdnsd for resolving simple (single-la-
	      bel) host	names.	fqdn_only used to stand	for  "fully  qualified
	      domain name only", but this is actually a	misnomer. The names in
	      queries received by pdnsd	are  always  considered	 to  be	 fully
	      qualified.  If  you  do  not exactly understand what the options
	      simple_only and fqdn_only	are good for, you are probably	better
	      off not using them.
	      The default for this option is included.

       include=string;
	      This  option adds	an entry to the	exclusion/inclusion list. If a
	      domain matches the name given as string, the server  is  queried
	      if this was the first matching rule (see also the	entry for pol-
	      icy).
	      If the given name	starts with a dot, the whole subdomain of  the
	      given  name  including  the  one	of  that name is matched, e.g.
	      ".foo.bar."    will   match   the	  domain   names   a.foo.bar.,
	      a.b.c.foo.bar. and foo.bar.
	      If  it does not start in a dot, only exactly the given name (ig-
	      noring the case, of course) will be matched (hint: if  you  want
	      to  include all subdomains, but not the domain of	the given name
	      itself, place an exact-match exclude  rule  before  the  include
	      rule, e.g: exclude="foo.bar."; include=".foo.bar.";
	      Previous	versions  of pdnsd required that names given with this
	      and  the	next  option  ended  in	 a  dot,  but  since   version
	      1.1.8b1-par8, pdnsd automatically	adds a dot at the end if it is
	      missing.
	      pdnsd now	also accepts a more compact notation for  adding  sev-
	      eral "include" entries in	one line, e.g.:

	      include=".foo",".bar",".my.dom";

       exclude=string;
	      This  option adds	an entry to the	exclusion/inclusion list. If a
	      domain matches the name given  as	 string,  the  server  is  not
	      queried  if this was the first matching rule (see	also the entry
	      for policy).
	      If the given name	starts with a dot, the whole subdomain of  the
	      given  name  including  the  one	of  that name is matched, e.g.
	      ".foo.bar."    will   match   the	  domain   names   a.foo.bar.,
	      a.b.c.foo.bar. and foo.bar.
	      If  it does not start in a dot, only exactly the given name (ig-
	      noring the case, of course) will be matched (hint: if  you  want
	      to  exclude all subdomains, but not the domain of	the given name
	      itself, place an exact-match include  rule  before  the  exclude
	      rule, e.g: include="foo.bar."; exclude=".foo.bar.";
	      pdnsd  now  also accepts a more compact notation for adding sev-
	      eral "exclude" entries in	one line, e.g.:

	      exclude=".foo",".bar",".my.dom";

   rr Section
       Every rr	section	specifies a dns	resource record	 that  is  stored  lo-
       cally.  It  allows  you	to  specify own	dns records that are served by
       pdnsd in	a limited way.	Only A,	PTR, CNAME, MX,	NS and SOA records are
       implemented.
       This  option  is	 intended to allow you to define RRs for 1.0.0.127.in-
       addr.arpa.  and localhost. (and perhaps even one	or two hosts)  without
       having to start an extra	named if your cached name servers do not serve
       those records.  It is NOT intended and not capable to work as  a	 full-
       featured	name server.

       name=string;
	      Specifies	the name of the	resource records, i.e. the domain name
	      of the resource the record describes. This option	must be	speci-
	      fied before any a, ptr, cname, mx, ns or soa records.  Names are
	      interpreted as absolute domain names (i.e.  pdnsd	 assumes  they
	      end  in  the root	domain).  For this and all following arguments
	      that take	domain names, you need to specify domain names in dot-
	      ted notation (example venera.isi.edu.).
	      Previous	versions  of pdnsd required that domain	names given in
	      the configuration	 file  ended  in  a  dot,  but	since  version
	      1.1.8b1-par8, pdnsd automatically	assumes	a dot at the end if it
	      is missing.
	      New in version 1.2: It is	also possible to specify a name	start-
	      ing with the label *. Such a name	is called a wildcard. The * in
	      a	wildcard can match one or more labels in a queried  name,  but
	      only  whole labels.  Any other * characters in a wildcard, apart
	      from the leading one, will only match a literal *.
	      For example, *.mydomain will match a.mydomain or www.a.mydomain,
	      but  not mydomain. *.a*.mydomain will match www.a*.mydomain, but
	      not www.ab.mydomain.  *a.mydomain	will only match	itself.
	      Before you can specify an	rr section  with  name=*.mydomain  you
	      must  define  some records for mydomain, typically NS and/or SOA
	      records.	Example:

		  rr {
		      name = mydomain;
		      ns = localhost;
		      soa = localhost, root.localhost, 42, 86400, 900,	86400,
	      86400;
		  }
		  rr {
		      name = *.mydomain;
		      a	= 192.168.1.10;
		  }

	      In  this	example, www.mydomain and ftp.mydomain will resolve to
	      the numeric address 192.168.1.10 (unless you add rr sections ex-
	      plicitly	specifying  different  addresses  for  www.mydomain or
	      ftp.mydomain).  If you want mydomain also	to resolve  to	a  nu-
	      meric address, add an A record to	the first rr section.

       ttl=timespec;
	      Specifies	 the  ttl  (time  to live) for all resource records in
	      this section after this entry.  This may be redefined.  The  de-
	      fault is 86400 seconds (=1 day).

       authrec=(on|off);
	      If  this	is  turned  on,	 pdnsd will create authoritative local
	      records for this rr section.  This means that  pdnsd  flags  the
	      domain  record  so  that	records	 of  this  domain that are not
	      present in the cache are treated as non-existent,	i.e. no	 other
	      servers  are  queried for	that record type, and an response con-
	      taining none of those records is returned.  This	is  most  time
	      what  people want: if you	add an A record	for a host, and	it has
	      no AAAA record (thus no IPv6 address), you normally  don't  want
	      other name servers to be queried for it.
	      This is on by default.
	      Please note that this only has an	effect if it precedes the name
	      option!

       reverse=(on|off);
	      New in version 1.2: If you want a	locally	defined	 name  to  re-
	      solve  to	a numeric address and vice versa, you can achieve this
	      by setting reverse=on before defining the	A record (see  below).
	      The alternative is to define a separate PTR record, but you will
	      probably find this option	much more convenient.
	      The default is off.

       a=string;
	      Defines an A (host address) record. The argument is an IPv4  ad-
	      dress in dotted notation.	 pdnsd will serve this address for the
	      host name	given in the name option.
	      Provided there is	sufficient support in the C libraries and sup-
	      port  for	AAAA records was not disabled, the argument string may
	      also be an IPv6 address, in which	case an	AAAA  record  will  be
	      defined.
	      This  option  be	may  used multiple times within	an rr section,
	      causing multiple addresses to be defined for the name.  However,
	      if  you put the different	addresses in different rr sections for
	      the same name, the definition in the last	rr section will	cancel
	      the definitions in the previous ones.

       ptr=string;
	      Defines  a  PTR  (domain name pointer) record. The argument is a
	      host name	in dotted notation (see	name). The ptr record  is  for
	      resolving	 adresses  into	 names.	 For  example, if you want the
	      adress 127.0.0.1 to resolve into localhost, and  localhost  into
	      127.0.0.1, you need something like the following sections:

		  rr {
		      name = localhost;
		      a	= 127.0.0.1;
		      owner = localhost;
		      soa  = localhost,	root.localhost,	42, 86400, 900,	86400,
	      86400;
		  }
		  rr {
		      name = 1.0.0.127.in-addr.arpa;
		      ptr = localhost;
		      owner = localhost;
		      soa = localhost, root.localhost, 42, 86400, 900,	86400,
	      86400;
		  }

	      The second section is for	reverse	resolving and uses the ptr op-
	      tion.  Note that you can get the same effect by specifying  only
	      the first	rr section with	reverse=on.
	      There is something special about the name	in the second section:
	      when a resolver wants to get a host name from  an	 internet  ad-
	      dress, it	composes an address that is built of the IP address in
	      reverse byte order (1.0.0.127 instead of 127.0.0.1)  where  each
	      byte  of	the  adress written as number constitutes a sub-domain
	      under the	domain in-addr.arpa.
	      So, if you want to compose an adress for reverse resolving, take
	      your  ip in dotted notation (e.g.	1.2.3.4), reverse the byte or-
	      der (4.3.2.1) and	append	in-addr.arpa.  (4.3.2.1.in-addr.arpa.)
	      Then,  define  an	rr section giving this address as name and the
	      domain name corresponding	to that	ip in the ptr option.

       cname=string;
	      Defines a	CNAME (canonical name) record.	The argument should be
	      a	 fully-qualified  host	name in	dotted notation	(see name).  A
	      CNAME is the DNS equivalent of an	alias or symbolic link.
	      A	useful application for CNAMEs is giving	short, easy to	remem-
	      ber nicknames to hosts with complicated names.  For example, you
	      might want the name "news" to refer to your  ISP's  news	server
	      "nntp2.myisp.com".   Instead  of	adding	an A record for	"news"
	      with the same address as "nntp2.myisp.com", you could put	 in  a
	      CNAME  pointing  to "nntp2.myisp.com", so	that if	the IP address
	      of the news server changes, there	 is  no	 need  to  update  the
	      record for "news".
	      To  implement  this with pdnsd, you could	add the	following sec-
	      tion to your configuration file:

		  rr {
		      name = news;
		      cname = nntp2.myisp.com;
		      owner = localhost;
		  }

       mx=string,number;
	      Defines an MX (mail exchange) record. The	 string	 is  the  host
	      name of the mail server in dotted	notation (see name).  The num-
	      ber specifies the	preference level.
	      When you send mail to someone, your  mail	 typically  goes  from
	      your  E-mail  client  to	an  SMTP server.  The SMTP server then
	      checks for the MX	record of the domain in	 the  E-mail  address.
	      For  example,  with  joe@example.com,  it	 would look for	the MX
	      record for example.com and find that the name of mail server for
	      that  domain  is,	 say,  mail.example.com.  The SMTP server then
	      gets the A record	for mail.example.com, and connects to the mail
	      server.
	      If  there	are multiple MX	records, the SMTP server will pick one
	      based on the preference level (starting with the lowest  prefer-
	      ence number, working its way up).
	      Don't  define  MX	records	with pdnsd unless you know what	you're
	      doing.

       owner=string;
	      or
       ns=string;
	      Defines an NS (name server) record. Specifies the	 name  of  the
	      host  which  should be authoritative for the records you defined
	      in the rr	section. This is typically the host pdnsd runs on.
	      Note: In previous	versions of pdnsd this option had to be	speci-
	      fied  before  any	 a, ptr, cname,	mx or soa entries.  In version
	      1.2, the restrictions on this option are	same  as  the  options
	      just mentioned, and it must listed after the name= option.  This
	      can be a pain if you want	to use an old config file which	speci-
	      fies owner= before name= (sorry about that).  Apart from greater
	      consistency, the advantage is that you can now specify  as  many
	      NS records as you	like (including	zero).

       soa=string,string,number,timespec,timespec,timespec,timespec;
	      This defines a soa (start	of authority) record. The first	string
	      is the domain name of the	server and should be equal to the name
	      you specified as owner.
	      The  second string specifies the email address of	the maintainer
	      of the name server. It is	also specified as a  domain  name,  so
	      you  will	 have to replace the @ sign in the name	with a dot (.)
	      to get the name you have to specify here.	  The  next  parameter
	      (the  first  number)  is	the  serial  number of the record. You
	      should increment this number if you change the record.
	      The 4th parameter	is the refresh	timeout.  It  specifies	 after
	      what  amount  of time a caching server should attempt to refresh
	      the cached record.
	      The 5th parameter	specifies a time after which a caching	server
	      should attempt to	refresh	the record after a refresh failure.
	      The  6th	parameter  defines  the	 timeout  after	which a	cached
	      record expires if	it has not been	refreshed.
	      The 7th parameter	is the ttl that	is specified in	every  rr  and
	      should  be  the same as given with the ttl option	(if you	do not
	      specify a	ttl, use the default 86400).

       txt=string,...,string;
	      New in version 1.2.9: Defines an TXT record. You can specify one
	      or more strings here.

   neg Section
       Every  neg section specifies a dns resource record or a dns domain that
       should be cached	negatively  locally.  Queries  for  negatively	cached
       records	are  always answered immediatley with an error or an empty an-
       swer without querying other hosts as long as the	record is  valid.  The
       records	defined	 with  neg  sections  remain  valid until they are ex-
       plicitely invalidated or	deleted	by the user using pdnsd-ctl.
       This is useful if a certain application asks periodically for nonexist-
       ing  hosts or RR	types and you do not want a query to go	out every time
       the cached record has timed out.	Example:  Netscape  Communicator  will
       ask  for	 the servers  news and mail on startup if unconfigured.	If you
       do not have a dns search	list for your network, you can inhibit	outgo-
       ing queries for these by	specifying

	   neg {
	       name = news;
	       types = domain;
	   }
	   neg {
	       name = mail;
	       types = domain;
	   }

       in your config file. If you have	a search list, you have	to repeat that
       for any entry in	your search list in  addition  to  the	entries	 given
       above!
       In versions 1.1.11 and later, if	you negate whole domains this way, all
       subdomains will be negated as well. Thus	if you specify
       neg {name=example.com; types=domain;} in	the  config  file,  this  will
       also negate www.example.com, xxx.adserver.example.com, etc.

       name=string;
	      Specifies	 the  name  of the domain for which negative cache en-
	      tries are	created.  This option must  be	specified  before  the
	      types  option.   Names  are interpreted as absolute domain names
	      (i.e. pdnsd assumes they end in the root domain).	 You  need  to
	      specify	domain	 names	 in   dotted  notation	(example  ven-
	      era.isi.edu.).
	      Previous versions	of pdnsd required that domain names  given  in
	      the  configuration  file	ended  in  a  dot,  but	 since version
	      1.1.8b1-par8, pdnsd automatically	assumes	a dot at the end if it
	      is missing.

       ttl=timespec;
	      Specifies	 the  ttl  (time  to live) for all resource records in
	      this section after this entry.  This may be redefined.  The  de-
	      fault is 86400 seconds (=1 day).

       types=(domain|rr_type[,rr_type[,rr_type[,...]]]);
	      Specifies	what is	to be cached negatively: domain	will cache the
	      whole domain negatively; alternatively, you can specify a	comma-
	      separated	 list  of  RR types which are to be cached negatively.
	      You may specify multiple types options, but domain  and  the  RR
	      types are	mutually exclusive.
	      The  RR  types are specified using their official	names from the
	      RFC's in capitals, e.g. A, CNAME,	NS, PTR, MX, AAAA, ...
	      The command pdnsd-ctl list-rrtypes will give you a complete list
	      of  those	types. pdnsd-ctl is built along	with pdnsd and will be
	      installed	in the same directory as the pdnsd binary during  make
	      install.

   source Section
       Every  source  section  allows you to let pdnsd read the	records	from a
       file in an /etc/hosts-like format. pdnsd	will generate records  to  re-
       solve  the  entries address from	its host name and vice versa for every
       entry in	the file. This is normally easier than defining	an rr for  ev-
       ery  of	your  addresses, since localhost and your other	FQDNs are nor-
       mally given in /etc/hosts.
       The accepted format is as follows: The #-sign initiates a comment,  the
       rest  of	 the line from the first occurence of this character on	is ig-
       nored. Empty lines are tolerated.
       The first entry on a line (predeceded by	an arbitrary  number  of  tabs
       and  spaces) is the IP in dotted	notation, the second entry on one line
       (separated by the first by an arbitrary number of tabs and  spaces)  is
       the  FQDN  (fully  qualified  domain name) for that ip. The rest	of the
       line is ignored by default (in the original /etc/hosts, it may  contain
       information not needed by pdnsd).

       owner=string;
	      Specifies	the name of the	host pdnsd runs	on and that are	speci-
	      fied in dns answers (specifically, nameserver records).  Must be
	      specified	before any file	entries.
	      Names  are  interpreted as absolute domain names (i.e. pdnsd as-
	      sumes they end in	the root domain).  You need to specify	domain
	      names in dotted notation (example	venera.isi.edu.).
	      Previous	versions  of pdnsd required that domain	names given in
	      the configuration	 file  ended  in  a  dot,  but	since  version
	      1.1.8b1-par8, pdnsd automatically	assumes	a dot at the end if it
	      is missing.

       ttl=timespec;
	      Specifies	the ttl	(time to live) for  all	 resource  records  in
	      this  section  after  this entry.	This may be redefined. The de-
	      fault is 86400 seconds (=1 day).

       file=string;
	      The string specifies a file name.	For  every  file  entry	 in  a
	      source  section,	pdnsd  will  try to load the given file	as de-
	      scribed above. Failure is	indicated only when the	file cannot be
	      opened, malformed	entries	will be	ignored.

       serve_aliases=(on|off);
	      If  this	is  turned  on pdnsd will serve	the aliases given in a
	      hosts-style file.	 These are the third entry  in	a  line	 of  a
	      hosts-style  file,  which	 usually  give	a "short name" for the
	      host.  This may be used to  support  broken  clients  without  a
	      proper  domain-search option.  If	no aliases are given in	a line
	      of the file, pdnsd behaves as without this option	for this line.
	      This feature was suggested by Bert Frederiks.
	      It is off	by default.

       authrec=(on|off);
	      If this is turned	on,  pdnsd  will  create  authoritative	 local
	      records  with  the data from the hosts file.  Please see the de-
	      scription	of the option of the same name in the rr section for a
	      closer  description  of  what  this means. Please	note that this
	      only has an effect for files sourced with	 file  options	subse-
	      quent to this option.
	      This is on by default.

   include Section
       A  configuration	 file may include other	configuration files.  However,
       only the	top-level configuration	file may  contain  global  and	server
       sections,  thus	include	files are effectively limited to sections that
       add local definitions to	the cache.
       Include sections	currently only have one	type of	option,	which  may  be
       given multiple times within a single section.

       file=string;
	      The  string  specifies  a	file name. For every file option in an
	      include section, pdnsd will parse	the given  file	 as  described
	      above.  The  file	 may contain include sections itself, but as a
	      precaution pdnsd checks that a certain maximum depth is not  ex-
	      ceeded to	guard against the possibility of infinite recursion.

VERSION
       This man	page is	correct	for version 1.2.9a-par of pdnsd.

SEE ALSO
       pdnsd(8), pdnsd-ctl(8)

       More documentation is available in the doc/ subdirectory	of the source,
       or in /usr/share/doc/pdnsd/ if you are using a binary package.

AUTHORS
       pdnsd was originally written by Thomas Moestl <tmoestl@gmx.net> <>  and
       was  extensively	 revised by Paul A. Rombouts <p.a.rombouts@home.nl> <>
       (for versions 1.1.8b1-par and later).

       Several others have contributed to pdnsd; see files in  the  source  or
       /usr/share/doc/pdnsd/ directory.

       This  man  page was automatically generated from	the html documentation
       for pdnsd, using	a customized Perl script written by Paul A. Rombouts.

       Last revised: 27	February 2012 by Paul A. Rombouts

pdnsd 1.2.9a-par		   Mar 2012			 PDNSD.CONF(5)

NAME | DESCRIPTION | FILE FORMAT | VERSION | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pdnsd.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help