Provided by: ntp_4.2.6.p3+dfsg-1ubuntu3_i386 bug

NAME

       ntp.conf - NTP server configuration file

SYNOPSIS

       ntp.conf

DESCRIPTION

       Ordinarily,  ntpd reads the ntp.conf configuration file at startup time
       in order to determine the synchronization sources and operating  modes.
       It   is   also   possible  to  specify  a  working,  although  limited,
       configuration entirely on the command line, obviating the  need  for  a
       configuration  file.   This  may  be particularly useful when the local
       host is to be configured as  a  broadcast/multicast  client,  with  all
       peers being determined by listening to broadcasts at run time.

       Usually, the configuration file is installed in the /etc directory, but
       could be installed elsewhere (see the -c conffile command line option).
       The file format is similar to other Unix configuration files - comments
       begin with a # character and extend to the end of the line; blank lines
       are ignored.

       Configuration commands consist of an initial keyword followed by a list
       of arguments, some of which may be optional, separated  by  whitespace.
       Commands  may  not  be  continued over multiple lines. Arguments may be
       host names,  host  addresses  written  in  numeric,  dotted-quad  form,
       integers, floating point numbers (when specifying times in seconds) and
       text strings.  Optional arguments are delimited by [ ] in the following
       descriptions,  while  alternatives  are separated by |.  The notation [
       ... ] means an optional, indefinite repetition of the last item  before
       the [ ... ].

       Following  is  a  description  of  the configuration commands in NTPv4.
       There  are  two  classes  of  commands,  configuration  commands   that
       configure an association with a remote server, peer or reference clock,
       and  auxiliary  commands  that  specify  environmental  variables  that
       control various related operations.

   Configuration Commands
       The  various  modes  are  determined  by  the  command  keyword and the
       required IP address.  Addresses are classed by type  as  (s)  a  remote
       server  or peer (IPv4 class A, B and C), (b) the broadcast address of a
       local interface, (m) a multicast address  (IPv4  class  D),  or  (r)  a
       reference  clock  address  (127.127.x.x).  The options that can be used
       with these commands are listed below.

       If the  Basic  Socket  Interface  Extensions  for  IPv6  (RFC-2553)  is
       detected,  support for the IPv6 address family is generated in addition
       to the default support of the IPv4 address family.  IPv6 addresses  can
       be identified by the presence of colons ":" in the address field.  IPv6
       addresses can be used almost everywhere where  IPv4  addresses  can  be
       used, with the exception of reference clock addresses, which are always
       IPv4.  Note that in contexts where  a  host  name  is  expected,  a  -4
       qualifier  preceding  the  host  name forces DNS resolution to the IPv4
       namespace, while a -6 qualifier  forces  DNS  resolution  to  the  IPv6
       namespace.

       There  are  three  types  of  associations: persistent, preemptable and
       ephemeral.  Persistent associations are mobilized  by  a  configuration
       command and never demobilized.  Preemptable associations, which are new
       to NTPv4, are mobilized by a configuration command which  includes  the
       prempt  flag  and  are  demobilized  by  timeout  or  error.  Ephemeral
       associations are mobilized upon  arrival  of  designated  messages  and
       demobilized by timeout or error.

       server address [options ...]

       peer address [options ...]

       broadcast address [options ...]

       manycastclient address [options ...]
              These  four  commands specify the time server name or address to
              be used and the mode in which to operate.  The  address  can  be
              either  a  DNS  name  or  a  IP address in dotted-quad notation.
              Additional information on association behavior can be  found  in
              the Association Management page.

              server For  type s and r addresses (only), this command normally
                     mobilizes a persistent client mode association  with  the
                     specified  remote server or local reference clock. If the
                     preempt flag is specified, a preemptable  association  is
                     mobilized  instead.  In  client mode the client clock can
                     synchronize to  the  remote  server  or  local  reference
                     clock, but the remote server can never be synchronized to
                     the client clock. This command should  NOT  be  used  for
                     type b or m addresses.

              peer   For  type  s  addresses  (only), this command mobilizes a
                     persistent symmetric-active  mode  association  with  the
                     specified  remote  peer. In this mode the local clock can
                     be synchronized to the remote peer or the remote peer can
                     be  synchronized  to the local clock. This is useful in a
                     network of servers where, depending  on  various  failure
                     scenarios,  either  the  local  or remote peer may be the
                     better source of time. This command should  NOT  be  used
                     for type b, m or r addresses.

              broadcast
                     For type b and m addresses (only), this command mobilizes
                     a  persistent  broadcast   mode   association.   Multiple
                     commands  can be used to specify multiple local broadcast
                     interfaces (subnets) and/or  multiple  multicast  groups.
                     Note  that  local  broadcast  messages  go  only  to  the
                     interface  associated  with  the  subnet  specified,  but
                     multicast messages go to all interfaces.

                     In   broadcast  mode  the  local  server  sends  periodic
                     broadcast messages to a client population at the  address
                     specified, which is usually the broadcast address on (one
                     of) the local network(s) or a multicast address  assigned
                     to NTP. The IANA has assigned the multicast group address
                     IPv4  224.0.1.1   and   IPv6   ff05::101   (site   local)
                     exclusively  to  NTP,  but other nonconflicting addresses
                     can be used to contain the messages within administrative
                     boundaries.  Ordinarily,  this specification applies only
                     to the local server operating as a sender; for  operation
                     as   a  broadcast  client,  see  the  broadcastclient  or
                     multicastclient commands below.

              manycastclient
                     For type m addresses (only),  this  command  mobilizes  a
                     preemptable  manycast  client  mode  association  for the
                     multicast  group  address  specified.  In  this  mode   a
                     specific  address  must  be  supplied  which  matches the
                     address  used  on  the  manycastserver  command  for  the
                     designated  manycast  servers.  The NTP multicast address
                     224.0.1.1 assigned by the IANA should NOT be used, unless
                     specific means are taken to avoid spraying large areas of
                     the Internet with these messages and causing  a  possibly
                     massive implosion of replies at the sender.

                     The  manycastclient command specifies that the host is to
                     operate in client mode with the remote servers  that  are
                     discovered as the result of broadcast/multicast messages.
                     The client broadcasts a  request  message  to  the  group
                     address   associated   with  the  specified  address  and
                     specifically enabled servers respond to  these  messages.
                     The  client  selects  the servers providing the best time
                     and continues as with the server command.  The  remaining
                     servers are discarded as if never heard.

   Command Options
       autokey
              All  packets sent to and received from the server or peer are to
              include authentication fields encrypted using the autokey scheme
              described  in  the  Authentication Options page.  This option is
              valid with all commands.

       burst  When the server is reachable, send  a  burst  of  eight  packets
              instead  of  the usual one.  The packet spacing is normally 2 s;
              however, the spacing between the first and second packets can be
              changed  with the calldelay command to allow additional time for
              a modem or ISDN call to complete.  This  option  is  valid  with
              only  the  server  command and is a recommended option with this
              command when the maxpoll option is 11 or greater.

       iburst When the server is unreachable, send a burst  of  eight  packets
              instead  of  the usual one.  The packet spacing is normally 2 s;
              however, the spacing between the first and second packets can be
              changed  with the calldelay command to allow additional time for
              a modem or ISDN call to complete.  This  option  is  valid  with
              only  the  server  command and is a recommended option with this
              command.

       key key
              All packets sent to and received from the server or peer are  to
              include  authentication fields encrypted using the specified key
              identifier with values from 1 to 65534, inclusive.  The  default
              is  to  include  no encryption field.  This option is valid with
              all commands.

       minpoll minpoll, maxpoll maxpoll
              These options specify the minimum and maximum poll intervals for
              NTP  messages,  in  seconds as a power of two.  The maximum poll
              interval defaults to 10 (1,024 s), but can be increased  by  the
              maxpoll  option  to  an upper limit of 17 (36.4 h).  The minimum
              poll interval defaults to 6 (64 s), but can be decreased by  the
              minpoll  option  to a lower limit of 4 (16 s).  These option are
              valid only with the server and peer commands.

       mode option
              Pass the option to a reference clock driver, where option is  an
              integer  in  the  range from 0 to 255, inclusive. This option is
              valid only with type r addresses.

       noselect
              Marks the server as unused, except for  display  purposes.   The
              server  is discarded by the selection algorithm.  This option is
              valid only with the server and peer commands.

       preempt
              Specifies the association as preemptable rather than the default
              persistent.  This option is valied only with the server command.

       prefer Marks  the  server  as preferred.  All other things being equal,
              this host will be chosen for  synchronization  among  a  set  of
              correctly  operating  hosts.   See  the Mitigation Rules and the
              prefer Keyword page for further  information.   This  option  is
              valid only with the server and peer commands.

       true   Force  the  association  to  assume  truechimer status; that is,
              always survive the selection and  clustering  algorithms.   This
              option  can be used with any association, but is most useful for
              reference clocks with  large  jitter  on  the  serial  port  and
              precision  pulse-per-second (PPS) signals.  Caution: this option
              defeats the algorithms designed to cast out falsetickers and can
              allow  these  sources  to  set the system clock.  This option is
              valid only with the server and peer commands.

       ttl ttl
              This option is used only  with  broadcast  server  and  manycast
              client  modes.   It  specifies  the  time-to-live  ttl to use on
              broadcast server and multicast server and the  maximum  ttl  for
              the   expanding   ring  search  with  manycast  client  packets.
              Selection of  the  proper  value,  which  defaults  to  127,  is
              something  of  a  black  art  and should be coordinated with the
              network administrator.

       version version
              Specifies the  version  number  to  be  used  for  outgoing  NTP
              packets.   Versions  1-4  are  the  choices,  with version 4 the
              default.  This option is valid only with the  server,  peer  and
              broadcast commands.

       xleave Operate  in  interleaved  mode  (symmetric  and  broadcast modes
              only). (see NTP Interleaved Modes)

   Auxiliary Commands
       broadcastclient [novolley]
              This command enables reception of broadcast server  messages  to
              any   local   interface  (type  b)  address.   Ordinarily,  upon
              receiving a message for the first  time,  the  broadcast  client
              measures  the  nominal  server  propagation  delay using a brief
              client/server exchange with the server, after which it continues
              in  listen-only  mode.   If the novolley keyword is present, the
              exchange  is  not  used  and  the   value   specified   in   the
              broadcastdelay command is used or, if the broadcastdelay command
              is not used, the default 4.0 ms.  Note that, in order  to  avoid
              accidental or malicious disruption in this mode, both the server
              and client should operate using  symmetric  key  or  public  key
              authentication  as described in the Authentication Options page.
              Note that the novolley keyword is incompatible with  public  key
              authentication.

       manycastserver address [...]
              This  command  enables  reception of manycast client messages to
              the multicast group address(es) (type m)  specified.   At  least
              one  address  is  required.  The NTP multicast address 224.0.1.1
              assigned by the IANA should NOT be used, unless  specific  means
              are  taken  to  limit the span of the reply and avoid a possibly
              massive implosion at the original sender.  Note that,  in  order
              to  avoid  accidental or malicious disruption in this mode, both
              the server and client should  operate  using  symmetric  key  or
              public  key  authentication  as  described in the Authentication
              Options page.

       multicastclient address [...]
              This command enables reception of multicast server  messages  to
              the  multicast  group  address(es)  (type  m)  specified.   Upon
              receiving a message for the first  time,  the  multicast  client
              measures  the  nominal  server  propagation  delay using a brief
              client/server  exchange  with  the  server,  then   enters   the
              broadcast  client  mode,  in which it synchronizes to succeeding
              multicast messages.  Note that, in order to avoid accidental  or
              malicious  disruption  in  this mode, both the server and client
              should operate using symmetric key or public key  authentication
              as described in the Authentication Options page.

   Authentication Commands
       autokey [logsec]
              Specifies  the interval between regenerations of the session key
              list used with the autokey feature.  Note that the size  of  the
              key  list  for each association depends on this interval and the
              current poll interval.  The default value is 12 (4096 s or about
              1.1  hours).  For poll intervals above the specified interval, a
              session key list with a single entry  will  be  regenerated  for
              every message sent.

       revoke [logsec]
              Specifies  the  interval  between  recomputations of the private
              value used with the autokey feature, which  ordinarily  requires
              an  expensive  public- key computation.  The default value is 12
              (65,536 s or about 18 hours).   For  poll  intervals  above  the
              specified  interval,  a new private value will be recomputed for
              every message sent.

   Miscellaneous Options
       driftfile driftfile
              This command specifies the name of the file use  to  record  the
              frequency  offset  of  the  local clock oscillator.  If the file
              exists, it is read at  startup  in  order  to  set  the  initial
              frequency offset and then updated once per hour with the current
              frequency offset computed by the daemon.  If the file  does  not
              exist or this command is not given, the initial frequency offset
              is assumed to be zero.  In this case, it may take some hours for
              the  frequency  to  stabilize  and the residual timing errors to
              subside.

              The file format consists of a single line  containing  a  single
              floating  point  number,  which  records  the  frequency  offset
              measured in parts-per-million (PPM).  The  file  is  updated  by
              first  writing the current drift value into a temporary file and
              then renaming this  file  to  replace  the  old  version.   This
              implies  that  ntpd must have write permission for the directory
              the drift file is  located  in,  and  that  file  system  links,
              symbolic or otherwise, should be avoided.

       enable  [auth  |  bclient  | calibrate | kernel | monitor | ntp | pps |
       stats]

       disable [auth | bclient | calibrate | kernel | monitor | ntp  |  pps  |
       stats]
              Provides  a  way  to  enable  or disable various server options.
              Flags not mentioned are unaffected.   Note  that  all  of  these
              flags  can  be  controlled  remotely  using  the  ntpdc  utility
              program.

              auth   Enables the server to synchronize with unconfigured peers
                     only  if  the peer has been correctly authenticated using
                     either public  key  or  private  key  cryptography.   The
                     default for this flag is enable.

              bclient
                     Enables  the  server  to  listen  for  a  message  from a
                     broadcast or multicast server, as in the  multicastclient
                     command  with default address.  The default for this flag
                     is disable.

              calibrate
                     Enables the calibrate feature for reference clocks.   The
                     default for this flag is disable.

              kernel Enables  the  kernel  time discipline, if available.  The
                     default for this flag is enable if support is  available,
                     otherwise disable.

              monitor
                     Enables  the  monitoring facility.  See the ntpdc program
                     and the monlist  command  or  further  information.   The
                     default for this flag is enable.

              ntp    Enables  time  and frequency discipline.  In effect, this
                     switch opens and  closes  the  feedback  loop,  which  is
                     useful for testing.  The default for this flag is enable.

              pps    Enables  the pulse-per-second (PPS) signal when frequency
                     and time is disciplined  by  the  precision  time  kernel
                     modifications.   See  the  A  Kernel  Model for Precision
                     Timekeeping page for further  information.   The  default
                     for this flag is disable.

              stats  Enables  the  statistics  facility.   See  the Monitoring
                     Options page for further information.   The  default  for
                     this flag is disable.

       includefile includefile
              This  command  allows  additional  configuration  commands to be
              included from a separate file.  Include files may be nested to a
              depth  of  five;  upon  reaching  the  end  of any include file,
              command processing resumes in the previous  configuration  file.
              This option is useful for sites that run ntpd on multiple hosts,
              with (mostly) common options (e.g., a restriction list).

       interface [listen | ignore | drop] [all | ipv4 | ipv6 | wildcard | name
       | address[/prefixlen]]
              This  command  controls  which network addresses ntpd opens, and
              whether input is dropped without processing. The first parameter
              determines  the  action  for  addresses  which  match the second
              parameter. That parameter specifies a class of addresses,  or  a
              specific  interface  name,  or  an address. In the address case,
              prefixlen determines how many bits must match for this  rule  to
              apply.  ignore  prevents opening matching addresses, drop causes
              ntpd to open the address and drop all received  packets  without
              examination.  Multiple  interface commands can be used. The last
              rule which matches a particular address  determines  the  action
              for  it. interface commands are disabled if any -I, --interface,
              -L, or --novirtualips command-line options are used. If none  of
              those options are used and no interface actions are specified in
              the configuration file,  all  available  network  addresses  are
              opened. The nic command is an alias for interface.

FILES

       /etc/ntp.conf

NOTES

       Note  that this manual page shows only the most important configuration
       commands.  The full documentation (see below) contains more details.

BUGS

       The syntax checking is not picky; some combinations of  ridiculous  and
       even hilarious options and modes may not be detected.

SEE ALSO

       ntpd(8)

       The      complete      documentation      can      be      found     at
       /usr/share/doc/ntp-doc/html/ntpd.html#cfg in the package ntp-doc.