BIND4 doc

named.8.txt

@INDOT_U@NAMED(@SYS_OPS_EXT_U@) 	       @INDOT_U@NAMED(@SYS_OPS_EXT_U@)



NAME
       @INDOT@named − Internet domain name server

SYNOPSIS
       @INDOT@named [ −d debuglevel ] [ −p port#[/localport#] ] [{−b} bootfile
       ] [ −q ] [ −r ]

DESCRIPTION
       Named is the Internet domain name server.  See RFC’s  1033,  1034,  and
       1035  for more information on the Internet name‐domain system.  Without
       any arguments, named will read the default boot	file  /etc/named.boot,
       read any initial data and listen for queries.

       Options are:

       −d     Print  debugging	information.   A number after the ‘‘d’’ deter‐
	      mines the level of messages printed.

       −p     Use nonstandard port numbers.  The default is the standard  port
	      number  as returned by getservbyname(@LIB_NETWORK_EXT@) for ser‐
	      vice ‘‘domain’’.	The argument can specify two port numbers sep‐
	      arated  by  a slash (‘‘/’’) in which case the first port is that
	      used when contacting remote servers, and the second one  is  the
	      service port bound by the local instance of named.  This is used
	      mostly for debugging purposes.

       −b     Use an alternate boot file.  This is optional and allows you  to
	      specify a file with a leading dash.

       −q     Trace  all incoming queries if named has been compiled with QRY‐
	      LOG defined.  NOTE: this option is deprecated in favour  of  the
	      boot file directive ‘‘options query‐log’’.

       −r     Turns  recursion	off in the server.  Answers can come only from
	      local (primary or secondary) zones.  This can be	used  on  root
	      servers.	 NOTE: this option is deprecated in favour of the boot
	      file directive ‘‘options no‐recursion’’.

       Any additional argument is taken as the name of the boot file.  If mul‐
       tiple boot files are specified, only the last is used.

       The  boot  file	contains information about where the name server is to
       get its initial data.  Lines in the boot file cannot  be  continued  on
       subsequent lines.  The following is a small example:

	 ;
	 ;    boot file for name server
	 ;
	 directory /usr/local/adm/named

	 ; type      domain		   source host/file	     backup file

	 cache	     .			   root.cache
	 primary     Berkeley.EDU	   berkeley.edu.zone
	 primary     32.128.IN‐ADDR.ARPA   ucbhosts.rev
	 secondary   CC.Berkeley.EDU	   128.32.137.8 128.32.137.3 cc.zone.bak
	 secondary   6.32.128.IN‐ADDR.ARPA 128.32.137.8 128.32.137.3 cc.rev.bak
	 primary     0.0.127.IN‐ADDR.ARPA  localhost.rev
	 forwarders  10.0.0.78 10.2.0.78
	 limit	     transfers‐in 10
	 limit	     datasize 64M
	 limit	     files 256
	 options     forward‐only query‐log fake‐iquery
	 check‐names primary fail
	 check‐names secondary warn
	 check‐names response ignore

       The  ‘‘directory’’  line causes the server to change its working direc‐
       tory to the directory specified.  This can be important for the correct
       processing of $INCLUDE files in primary zone files.

       The  ‘‘cache’’  line  specifies	that  data  in ‘‘root.cache’’ is to be
       placed in the backup cache.  Its main use is to specify	data  such  as
       locations of root domain servers.  This cache is not used during normal
       operation, but is used as ‘‘hints’’ to find the current	root  servers.
       The file ‘‘root.cache’’ is in the same format as ‘‘berkeley.edu.zone’’.
       There  can  be  more  than   one   ‘‘cache’’   file   specified.    The
       ‘‘root.cache’’ file should be retrieved periodically from FTP.RS.INTER‐
       NIC.NET since it contains a list of root servers, and this list changes
       periodically.

       The  first  example  ‘‘primary’’  line  states  that  the file ‘‘berke‐
       ley.edu.zone’’ contains authoritative  data  for  the  ‘‘Berkeley.EDU’’
       zone.   The file ‘‘berkeley.edu.zone’’ contains data in the master file
       format described in RFC 883.  All domain names are relative to the ori‐
       gin,  in  this  case,  ‘‘Berkeley.EDU’’	(see below for a more detailed
       description).  The second ‘‘primary’’ line states that the file	‘‘ucb‐
       hosts.rev’’  contains  authoritative  data  for the domain ‘‘32.128.IN‐
       ADDR.ARPA,’’ which is used to translate addresses in network 128.32  to
       hostnames.   Each  master  file should begin with an SOA record for the
       zone (see below).

       The first example ‘‘secondary’’ line specifies that  all  authoritative
       data  under  ‘‘CC.Berkeley.EDU’’  is  to  be  transferred from the name
       server at 128.32.137.8.	If the transfer fails it will try 128.32.137.3
       and  continue trying the addresses, up to 10, listed on this line.  The
       secondary copy is also authoritative for  the  specified  domain.   The
       first  non‐dotted‐quad address on this line will be taken as a filename
       in which to backup the transferred zone.  The name server will load the
       zone from this backup file if it exists when it boots, providing a com‐
       plete copy even if the master servers are unreachable.  Whenever a  new
       copy  of  the domain is received by automatic zone transfer from one of
       the master servers, this file will be updated.	If  no	file  name  is
       given,  a  temporary  file will be used, and will be deleted after each
       successful zone transfer.  This is not recommended since it is a  need‐
       less  waste of bandwidth.  The second example ‘‘secondary’’ line states
       that the address‐to‐hostname mapping for the subnet  128.32.136	should
       be  obtained from the same list of master servers as the previous zone.

       The ‘‘forwarders’’ line specifies the  addresses  of  sitewide  servers
       that  will  accept  recursive  queries from other servers.  If the boot
       file specifies one or more forwarders, then the server  will  send  all
       queries	for  data not in the cache to the forwarders first.  Each for‐
       warder will be asked in turn until an answer is returned or the list is
       exhausted.   If	no  answer is forthcoming from a forwarder, the server
       will continue as it would have without the forwarders line unless it is
       in ‘‘forward‐only’’ mode.  The forwarding facility is useful to cause a
       large sitewide cache to be generated on a master, and to reduce traffic
       over links to outside servers.  It can also be used to allow servers to
       run that do not have direct access to the Internet, but wish to look up
       exterior names anyway.

       The  ‘‘slave’’ line (deprecated) is allowed for backward compatibility.
       Its meaning is identical to ‘‘options forward‐only’’.

       The ‘‘sortlist’’ line can be used to indicate networks that are	to  be
       preferred  over	other networks.  Queries for host addresses from hosts
       on the same network as the server will  receive	responses  with  local
       network	addresses  listed first, then addresses on the sort list, then
       other addresses.

       The ‘‘xfrnets’’ directive (not shown) can be used to  implement	primi‐
       tive access control.  If this directive is given, then your name server
       will only answer zone transfer requests from hosts which  are  on  net‐
       works  listed  in your ‘‘xfrnets’’ directives.  This directive may also
       be given as ‘‘tcplist’’ for compatibility with older, interim  servers.

       The  ‘‘include’’  directive (not shown) can be used to process the con‐
       tents of some other file as  though  they  appeared  in	place  of  the
       ‘‘include’’ directive.  This is useful if you have a lot of zones or if
       you have logical groupings of zones which are maintained  by  different
       people.	 The  ‘‘include’’ directive takes one argument, that being the
       name of the file whose contents are to be included.  No quotes are nec‐
       essary around the file name.

       The ‘‘bogusns’’ directive (not shown) tells BIND that no queries are to
       be sent to the specified name server addresses (which are specified  as
       dotted  quads, not as domain names).  This is useful when you know that
       some popular server has bad data in a zone or cache, and  you  want  to
       avoid contamination while the problem is being fixed.

       The  ‘‘limit’’  directive can be used to change BIND’s internal limits,
       some of which (datasize, for example) are implemented by the system and
       others  (like  transfers‐in)  by BIND itself.  The number following the
       limit name can be scaled by postfixing a ‘‘k,’’	‘‘m,’’	or  ‘‘g’’  for
       kilobytes,  megabytes, and gigabytes respectively.  datasize’s argument
       sets the process data size enforced by the kernel.  Note: not all  sys‐
       tems  provide  a  call to implement this ‐‐ on such systems, the use of
       the datasize parameter of ‘‘limit’’ will result in a  warning  message.
       transfers‐in’s  argument is the number of named‐xfer subprocesses which
       BIND will spawn at any one time.  transfers‐per‐ns’s  argument  is  the
       maximum	number of zone transfers to be simultaneously initiated to any
       given remote name server.  files’s argument sets  the  number  of  file
       descriptors  available  to the process. Note: not all systems provide a
       call to implement this ‐‐ on such systems, the use of the files parame‐
       ter of ‘‘limit’’ will result in a warning message.

       The  ‘‘options’’  directive introduces a boolean specifier that changes
       the behaviour of BIND.  More than one option can be specified in a sin‐
       gle directive.  The currently defined options are as follows: no‐recur‐
       sion, which will cause BIND to  answer  with  a	referral  rather  than
       actual  data whenever it receives a query for a name it is not authori‐
       tative for ‐‐ don’t set this on a server that is listed in  any	host’s
       resolv.conf file; no‐fetch‐glue, which keeps BIND from fetching missing
       glue when constructing the ‘‘additional data’’ section of  a  response;
       this  can  be  used  in conjunction with no‐recursion to prevent BIND’s
       cache from ever growing in size or becoming corrupted; query‐log, which
       causes  all queries to be logged via syslog(@SYS_OPS_EXT@) ‐‐ this is a
       lot of data, don’t turn it on lightly; forward‐only, which  causes  the
       server  to query only its forwarders ‐‐ this option is normally used on
       machine that wishes to run a server but for physical or	administrative
       reasons	cannot be given access to the Internet; and fake‐iquery, which
       tells BIND to  send  back  a  useless  and  bogus  reply  to  ‘‘inverse
       queries’’  rather  than	responding with an error ‐‐ this is helpful if
       you have a lot of microcomputers or SunOS hosts or both.

       The ‘‘check‐names’’ directive tells  BIND  to  check  names  in	either
       ‘‘primary’’  or ‘‘secondary’’ zone files, or in messages (‘‘response’’)
       received during recursion (for example, those which would be  forwarded
       back  to  a  firewalled requestor).  For each type of name, BIND can be
       told to ‘‘fail’’, such that a zone would not be loaded  or  a  response
       would  not be cached or forwarded, or merely ‘‘warn’’ which would cause
       a message to be emitted in the system operations logs, or to ‘‘ignore’’
       the badness of a name and process it in the traditional fashion.  Names
       are considered good if they match RFC 952’s expectations (if  they  are
       host  names), or if they consist only of printable ASCII characters (if
       they are not host names).

       The ‘‘max‐fetch’’ directive (not shown) is allowed for backward compat‐
       ibility; its meaning is identical to ‘‘limit transfers‐in’’.

       The  master file consists of control information and a list of resource
       records for objects in the zone of the forms:

	      $INCLUDE <filename> <opt_domain>
	      $ORIGIN <domain>
	      <domain> <opt_ttl> <opt_class> <type> <resource_record_data>

       where domain is "." for root, "@" for the current origin, or a standard
       domain name. If domain is a standard domain name that does not end with
       ‘‘.’’, the current origin is appended to the domain. Domain names  end‐
       ing  with ‘‘.’’ are unmodified.	The opt_domain field is used to define
       an origin for the data in an included file.  It is equivalent to  plac‐
       ing  a  $ORIGIN	statement  before the first line of the included file.
       The field is optional.  Neither the opt_domain field nor $ORIGIN state‐
       ments  in  the  included  file modify the current origin for this file.
       The opt_ttl field is an optional integer number	for  the  time‐to‐live
       field.  It defaults to zero, meaning the minimum value specified in the
       SOA record for the zone.  The opt_class field  is  the  object  address
       type;  currently  only one type is supported, IN, for objects connected
       to the DARPA Internet.  The type field contains one  of	the  following
       tokens;	the  data  expected  in  the  resource_record_data field is in
       parentheses.

       A	a host address (dotted quad)

       NS	an authoritative name server (domain)

       MX	a mail exchanger (domain),  preceded  by  a  preference  value
		(0..32767), with lower numeric values representing higher log‐
		ical preferences.

       CNAME	the canonical name for an alias (domain)

       SOA	marks the start of a zone of authority (domain of  originating
		host,  domain  address	of maintainer, a serial number and the
		following parameters in seconds: refresh,  retry,  expire  and
		minimum TTL (see RFC 883)).

       NULL	a null resource record (no format or data)

       RP	a Responsible Person for some domain name (mailbox, TXT‐refer‐
		ral)

       PTR	a domain name pointer (domain)

       HINFO	host information (cpu_type OS_type)

       Resource records normally end at the end of a line, but may be  contin‐
       ued across lines between opening and closing parentheses.  Comments are
       introduced by semicolons and continue to the end of the line.

       Note that there are other resource record types, not shown  here.   You
       should  consult	the  BIND  Operations Guide (‘‘BOG’’) for the complete
       list.  Some resource record types may have been standardized  in  newer
       RFC’s but not yet implemented in this version of BIND.

       Each master zone file should begin with an SOA record for the zone.  An
       example SOA record is as follows:

       @ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. (
		1989020501 ; serial
		10800	   ; refresh
		3600	   ; retry
		3600000    ; expire
		86400 )    ; minimum

       The SOA specifies a serial number, which should be  changed  each  time
       the  master  file is changed.  Note that the serial number can be given
       as a dotted number, but this is a very unwise thing  to	do  since  the
       translation  to normal integers is via concatenation rather than multi‐
       plication and addition.	You can spell out  the	year,  month,  day  of
       month,  and  0..99  version  number  and  still fit inside the unsigned
       32‐bit size of this field.  It’s true that we will have to rethink this
       strategy in the year 4294 (Greg.) but we’re not worried about it.  Sec‐
       ondary servers check the serial number at intervals  specified  by  the
       refresh	time in seconds; if the serial number changes, a zone transfer
       will be done to load the new data.  If a master server cannot  be  con‐
       tacted  when a refresh is due, the retry time specifies the interval at
       which refreshes should be attempted.  If a master server cannot be con‐
       tacted  within the interval given by the expire time, all data from the
       zone is discarded by secondary servers.	The minimum value is the time‐
       to‐live (‘‘TTL’’) used by records in the file with no explicit time‐to‐
       live value.

NOTES
       The boot file directives ‘‘domain’’ and ‘‘suffixes’’  have  been  obso‐
       leted  by  a more useful resolver‐based implementation of suffixing for
       partially qualified domain names.   The	prior  mechanisms  could  fail
       under a number of situations, especially when then local nameserver did
       not have complete information.

       The following signals have the specified effect when sent to the server
       process using the kill(@CMD_EXT@) command.

       SIGHUP Causes  server  to  read named.boot and reload the database.  If
	      the server is built with the FORCED_RELOAD compile‐time  option,
	      then  SIGHUP will also cause the server to check the serial num‐
	      ber on all secondary zones.  Normally  the  serial  numbers  are
	      only checked at the SOA‐specified intervals.

       SIGINT Dumps the current data base and cache to /var/tmp/named_dump.db

       SIGIOT Dumps statistics data into /var/tmp/named.stats if the server is
	      compiled with ‐DSTATS.  Statistics data is appended to the file.
	      Some systems use SIGABRT rather than SIGIOT for this.

       SIGSYS Dumps  the  profiling data in /var/tmp if the server is compiled
	      with profiling (server forks, chdirs and exits).

       SIGTERM
	      Dumps the primary and secondary database files.	Used  to  save
	      modified data on shutdown if the server is compiled with dynamic
	      updating enabled.

       SIGUSR1
	      Turns  on  debugging;  each  SIGUSR1  increments	debug	level.
	      (SIGEMT on older systems without SIGUSR1)

       SIGUSR2
	      Turns  off debugging completely.	(SIGFPE on older systems with‐
	      out SIGUSR2)

       SIGWINCH
	      Toggles	logging   of   all   incoming	queries    via	  sys‐
	      log(@SYS_OPS_EXT@)  (requires server to have been built with the
	      QRYLOG option).

FILES
       /etc/named.boot		name server configuration boot file
       /etc/named.pid		the process id (on older systems)
       /var/run/named.pid	the process id (on newer systems)
       /var/tmp/named_dump.db	dump of the name server database
       /var/tmp/named.run	debug output
       /var/tmp/named.stats	nameserver statistics data

SEE ALSO
       kill(@CMD_EXT@), 	gethostbyname(@LIB_NETWORK_EXT@),	  sig‐
       nal(@SYSCALL_EXT@),     resolver(@LIB_NETWORK_EXT@),	resolver(@FOR‐
       MAT_EXT@), hostname(@DESC_EXT@), RFC 882, RFC 883, RFC  973,  RFC  974,
       RFC  1033,  RFC	1034, RFC 1035, RFC 1123, Name Server Operations Guide
       for BIND



4th Berkeley Distribution	 June 20, 1995 @INDOT_U@NAMED(@SYS_OPS_EXT_U@)