OpenBSD manual page server

Manual Page Search Parameters




NAMED(8)                                                 NAMED(8)


NAME
       named - Internet domain name server

SYNOPSIS
       named  [  -d  debuglevel ] [ -p port#[/localport#] ] [{-b}
       bootfile ] [ -q ] [ -r ] [ -u user ] [ -g  group  ]  [  -t
       chroot_dir ]

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 /var/named/named.boot, read any  initial
       data and listen for queries.

       Options are:

       -d     Print  debugging  information.   A number after the
              ``d'' determines the level of messages printed.

       -p     Use nonstandard port numbers.  The default  is  the
              standard  port  number  as  returned  by getservby-
              name(3) for service ``domain''.  The  argument  can
              specify  two  port  numbers  separated  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 com-
              piled with QRYLOG 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''.

       -u     Specifies the user the server should run  as  after
              it  initializes.  The value specified may be either
              a username or a numeric user ID.  If the -g flag is
              not  specified,  then the group ID used will be the
              primary group of the user  specified  (initgroups()
              is  called,  so  all  of  the user's groups will be
              available to the server).
              Note: normally, named will rescan the active Ether-
              net interfaces when it receives SIGHUP.  Use of the
              -u option makes this impossible since  the  default
              port  that named listens on is a reserved port that



                          June 20, 1995                         1





NAMED(8)                                                 NAMED(8)


              only the superuser may bind to.

       -g     Specifies the group the server should run as  after
              it  initializes.  The value specified may be either
              a groupname or a numeric group ID.

       -t     Specifies the directory the server should  chroot()
              into  as  soon as it is finished processing command
              line arguments.

       Any additional argument is taken as the name of  the  boot
       file.  If multiple 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
         stub        cc.Berkeley.EDU       128.32.137.8 128.32.137.3 cc.zone.stub
         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 directory 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 ``berke-
       ley.edu.zone''.  There can be more than one ``cache'' file



                          June 20, 1995                         2





NAMED(8)                                                 NAMED(8)


       specified.   The  ``root.cache''  file should be retrieved
       periodically from FTP.RS.INTERNIC.NET since it contains  a
       list  of root servers, and this list changes periodically.

       The first example ``primary'' line states  that  the  file
       ``berkeley.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 origin, in this
       case,  ``Berkeley.EDU''  (see  below  for  a more detailed
       description).  The second ``primary'' line states that the
       file  ``ucbhosts.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  try-
       ing  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  trans-
       ferred 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 success-
       ful zone transfer.  This is not recommended since it is  a
       needless  waste  of  bandwidth.  The second example ``sec-
       ondary'' 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  forwarder
       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 with-
       out 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.




                          June 20, 1995                         3





NAMED(8)                                                 NAMED(8)


       The ``stub'' line  specified  the  addresses  of  sitewide
       servers  that will accept recursive queries for the speci-
       fied zone.  Each server will be asked in turn for  queries
       for  the  specified  zone if it is not in the local cache.
       If specified, the zone data will be saved  in  the  backup
       file,  which  is the first non-dotted-quad address on this
       line.

       The ``slave'' line (deprecated) is  allowed  for  backward
       compatibility.  Its meaning is identical to ``options for-
       ward-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 primitive access control.  If this directive  is
       given,  then your name server will only answer zone trans-
       fer requests from hosts which are on  networks  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 pro-
       cess the contents  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 peo-
       ple.  The ``include'' directive takes one  argument,  that
       being  the  name  of  the  file  whose  contents are to be
       included.  No quotes are necessary 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 kilo-
       bytes,  megabytes, and gigabytes respectively.  datasize's
       argument sets the process data size enforced by  the  ker-
       nel.   Note:  not  all systems provide a call to implement
       this -- on such systems, the use of the datasize parameter
       of ``limit'' will result in a warning message.  transfers-



                          June 20, 1995                         4





NAMED(8)                                                 NAMED(8)


       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 parameter of ``limit'' will result in a warning mes-
       sage.

       The ``options'' directive introduces a  boolean  specifier
       that  changes the behaviour of BIND.  More than one option
       can be specified in a  single  directive.   The  currently
       defined  options  are as follows: no-recursion, which will
       cause BIND to answer with a referral  rather  than  actual
       data  whenever  it  receives  a query for a name it is not
       authoritative 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  con-
       structing  the  ``additional data'' section of a response;
       this can be used in conjunction with no-recursion to  pre-
       vent  BIND's  cache  from ever growing in size or becoming
       corrupted; query-log,  which  causes  all  queries  to  be
       logged  via syslog(8) -- 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 mes-
       sages  (``response'') received during recursion (for exam-
       ple, 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  compatibility;  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:




                          June 20, 1995                         5





NAMED(8)                                                 NAMED(8)


              $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 ending with ``.'' are
       unmodified.  The opt_domain field is  used  to  define  an
       origin for the data in an included file.  It is equivalent
       to placing a $ORIGIN statement before the  first  line  of
       the  included  file.   The field is optional.  Neither the
       opt_domain field nor $ORIGIN statements  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 prefer-
                ence value (0..32767), with lower numeric  values
                representing higher logical 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 (mail-
                box, TXT-referral)

       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 continued 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



                          June 20, 1995                         6





NAMED(8)                                                 NAMED(8)


       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  multiplication
       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.  Secondary 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 contacted 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 obsoleted by a more useful resolver-based implementa-
       tion  of  suffixing  for partially qualified domain names.
       The prior mechanisms could fail under a number  of  situa-
       tions,  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(1) 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 number on
              all  secondary  zones.  Normally the serial numbers
              are only checked at the SOA-specified intervals.




                          June 20, 1995                         7





NAMED(8)                                                 NAMED(8)


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

       SIGIOT Dumps  statistics  data into /var/named/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/named  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 without SIGUSR2)

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

FILES
       /var/named/named.boot      name server configuration boot file
       /var/run/named.pid         the process id
       /var/named/named.pid       the process id (if named is chroot'd)
       /var/named/named_dump.db   dump of the name server database
       /var/named/named.run       debug output
       /var/named/named.stats     nameserver statistics data

SEE ALSO
       kill(1),   gethostbyname(3),    signal(2),    resolver(3),
       resolver(5),  hostname(7),  RFC 882, RFC 883, RFC 973, RFC
       974, RFC 1033, RFC 1034, RFC 1035, RFC 1123,  Name  Server
       Operations Guide for BIND














                          June 20, 1995                         8