Man Linux: Main Page and Category List

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 auxilliary  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.

       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.

       dynamic
              Allows a  server/peer  to  be  configured  even  if  it  is  not
              reachable  at  configuration  time.   It is assumed that at some
              point in the future the network environment changes so that this
              server/peer  can be reached.  This option is useful to configure
              servers/peers on mobile systems with intermittent network access
              (e.g. wlan clients).

   Auxilliary 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).

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.