Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

ntpd (8)

Name

ntpd - Network Time Protocol daemon Version 4

Synopsis

/usr/lib/inet/ntpd [-46aAbdDgLmnNqvx] [-c conffile]
[-f driftfile] [-k keyfile] [-l logfile] [-p pidfile]
[-P priority] [-r broadcastdelay] [-s statsdir]
[-t trustedkey] [-U interface_update_time]

Description

System Administration Commands                                         ntpd(8)



NAME
       ntpd - Network Time Protocol daemon Version 4

SYNOPSIS
       /usr/lib/inet/ntpd [-46aAbdDgLmnNqvx] [-c conffile]
           [-f driftfile] [-k keyfile] [-l logfile] [-p pidfile]
           [-P priority] [-r broadcastdelay] [-s statsdir]
           [-t trustedkey] [-U interface_update_time]


DESCRIPTION
       The  ntpd  program  is an operating system daemon that synchronises the
       system clock with remote NTP time servers or local reference clocks. It
       is a complete implementation of the Network Time Protocol (NTP) version
       4, but also retains compatibility with version 3,  as  defined  by  RFC
       1305,  and  versions  1  and  2,  as  defined by RFC 1059 and RFC 1119,
       respectively.

   How NTP Operates
       The ntpd program operates by exchanging messages with one or more  con-
       figured  servers  at designated intervals ranging from about one minute
       to about  17  minutes.  When  started,  the  program  requires  several
       exchanges  while  the  algorithms  accumulate and groom the data before
       setting the clock. The initial delay to set the clock  can  be  reduced
       using   options   as   described   in   the  server  options  page   at
       file:///usr/share/doc/ntp/confopt.html.

       When the machine is booted, the hardware time of day (TOD) chip is used
       to initialize the operating system time. After the machine has synchro-
       nized to a NTP server, the operating system corrects the chip from time
       to  time.  During the course of operation if for some reason the system
       time is more than 1000s offset from the server time, ntpd assumes some-
       thing must be terribly wrong and exits with a panic message to the sys-
       tem log. If it was started via SMF, the  ntp  service  is  placed  into
       maintenance  mode and must be cleared manually. The -g option overrides
       this check at startup and allows ntpd to set the clock  to  the  server
       time regardless of the chip time, but only once.

       Under  ordinary  conditions,  ntpd  slews the clock so that the time is
       effectively continuous and never runs backwards. If due to extreme net-
       work  congestion  an  error  spike exceeds the step threshold (128ms by
       default), the spike is discarded. However, if the  error  persists  for
       more  than  the stepout threshold (900s by default) the system clock is
       stepped to the correct value. In  practice  the  need  for  a  step  is
       extremely rare and almost always the result of a hardware failure. With
       the -x option the step threshold is increased to  600s.  Other  options
       are  available  using  the tinker command as described in the miscella-
       neous options page at file:///usr/share/doc/ntp/miscopt.html.

       The issues should be carefully considered before using  these  options.
       The  maximum  slew  rate  possible  is limited to 500 parts-per-million
       (PPM) by the Unix kernel. As a result, the clock  can  take  2000s  for
       each  second  the  clock  is  outside the acceptable range. During this
       interval the clock will not be consistent with any other network  clock
       and the system cannot be used for distributed applications that require
       correctly synchronized network time.

   Frequency Discipline
       The frequency file, usually called ntp.drift, contains the latest esti-
       mate  of  clock  frequency.  If  this  file does not exist when ntpd is
       started, it enters a special mode designed to  measure  the  particular
       frequency  directly.  The measurement takes 15 minutes, after which the
       frequency is set and ntpd resumes normal mode where the time  and  fre-
       quency  are  continuously  adjusted.  The  frequency file is updated at
       intervals of an hour or more depending on the measured clock stability.

   Operating Modes
       The ntpd daemon can operate in any of several modes, including  symmet-
       ric  active/passive, client/server broadcast/multicast and manycast, as
       described     in     the     Association     Management     page     at
       file:///usr/share/doc/ntp/assoc.html. It normally operates continuously
       while monitoring for small changes in frequency and trimming the  clock
       for  the ultimate precision. However, it can operate in a one-time mode
       where the time is set from an external server and frequency is set from
       a previously recorded frequency file. A broadcast/multicast or manycast
       client can discover remote servers, compute  server-client  propagation
       delay correction factors and configure itself automatically. This makes
       it possible to deploy a fleet of workstations without  specifying  con-
       figuration details specific to the local environment.

       By default, ntpd runs in continuous mode where each of possibly several
       external servers is polled at  intervals  determined  by  an  intricate
       phase/frequency-lock  feedback  loop.  The  feedback  loop measures the
       incidental roundtrip delay jitter and oscillator frequency  wander  and
       determines the best poll interval using a heuristic algorithm. Ordinar-
       ily, and in most operating environments, the state machine  will  start
       with  64s  intervals and eventually increase in steps to 1024s. A small
       amount of random variation is introduced in order to avoid bunching  at
       the  servers.  In addition, should a server become unreachable for some
       time, the poll interval is increased in steps  to  1024s  in  order  to
       reduce network overhead. In general it is best not to force ntpd to use
       specific poll intervals, allowing it to choose the best intervals based
       its  current  needs  and  the  quality of the available servers and the
       clock.

       In some cases it may not be practical for ntpd to run continuously.  In
       the past a common workaround has been to run the ntpdate program from a
       cron job at designated  times.  However,  ntpdate  does  not  have  the
       crafted  signal processing, error checking and mitigation algorithms of
       ntpd. The ntpd daemon with -q option is  intended  to  replace  ntpdate
       when  used  in this manner. Setting this option will cause ntpd to exit
       just after setting the clock for the first time. The procedure for ini-
       tially setting the clock is the same as in continuous mode; most appli-
       cations will probably want to  specify  the  iburst  keyword  with  the
       server  configuration  command.  With this keyword a volley of messages
       are exchanged to groom the data and the clock is set in about  10s.  If
       nothing  is  heard  after a couple of minutes, the daemon times out and
       exits. Eventually the ntpdate program may be retired.

   Kernel Clock Discipline
       The kernel supports a method specific to ntpd to discipline  the  clock
       frequency.  First, ntpd is run in continuous mode with selected servers
       in order to measure and record the intrinsic clock frequency offset  in
       the frequency file. It may take some hours for the frequency and offset
       to settle down. Then ntpd is run in normal mode as  required.  At  each
       startup, the frequency is read from the file and initializes the kernel
       frequency, thus avoiding the settling period.  When the  kernel  disci-
       pline is in use, the system's clock is adjusted at each system tick and
       thus the system clock is always as accurate as possible. When the  ker-
       nel  discipline  is not used the clock is adjusted once each second. It
       is important to delete the ntp.drift file before starting ntpd  if  the
       intrinsic frequency might have changed, such as by a motherboard swap.

   Poll Interval Control
       The  ntpd  program includes an intricate clock discipline to reduce the
       network load while maintaining a quality of synchronization  consistent
       with the observed jitter and wander. There are a number of ways to tai-
       lor the operation in order to enhance accuracy by reducing the interval
       or  to  reduce  network overhead by increasing it. However, the user is
       advised to carefully consider the consequences  of  changing  the  poll
       adjustment range from the default. It is not the case that shorter poll
       intervals will necessarily lead to more accuracy. Most  device  drivers
       will  not  operate  properly if the poll interval is less than 64 s and
       that the broadcast server and manycast client  associations  will  also
       use  the default, unless overridden. In general, it is best to let ntpd
       determine the best polling interval.

       In some cases involving dial up or toll services, it may be  useful  to
       increase  the  minimum  interval  to  a few tens of minutes and maximum
       interval to a day or so. Under normal operation  conditions,  once  the
       clock  discipline loop has stabilized the interval will be increased in
       steps from the minimum  to  the  maximum.  However,  this  assumes  the
       intrinsic clock frequency error is small enough for the discipline loop
       correct it. The capture range of the loop is 500 PPM at an interval  of
       64s  decreasing  by a factor of two for each doubling of interval. At a
       minimum of 1,024 s, for example, the capture range is only 31 PPM.

   The Huff-n'-Puff Filter
       In scenarios where a considerable amount of data are to  be  downloaded
       or  uploaded  over  bandwidth limited links, timekeeping quality can be
       seriously degraded due to the different delays in the  two  directions.
       In  many  cases  the apparent time errors are so large as to exceed the
       step threshold and a step correction can occur  during  and  after  the
       data transfer is in progress.

       The huff-n'-puff filter is designed to correct the apparent time offset
       in these cases. It depends on knowledge of the propagation  delay  when
       no other traffic is present. The filter maintains a shift register that
       remembers the minimum delay over the most recent interval measured usu-
       ally  in  hours.  Under conditions of severe delay, the filter corrects
       the apparent offset using the sign of the  offset  and  the  difference
       between  the  apparent  delay and minimum delay. The name of the filter
       reflects the negative (huff)  and  positive  (puff)  correction,  which
       depends on the sign of the offset.

       The  filter is activated by the tinker command and huffpuff keyword, as
       described     in     the     Miscellaneous     Options     page      at
       file:///usr/share/doc/ntp/miscopt.html.

   Leap Second Processing
       As  provided  by  international agreement, an extra second is sometimes
       inserted in Coordinated Universal Time (UTC) at the end of  a  selected
       month,  usually  June or December. The National Institutes of Standards
       and  Technology  (NIST)  provides  an  historic  leapseconds  file   at
       time.nist.gov  for  retrieval  via  FTP. This file, usually called ntp-
       leapseconds.list, is copied into the /etc/inet directory and the  leap-
       file  configuration  command  then  specifies the path to this file. At
       startup, ntpd reads it and initializes three leapsecond values: the NTP
       seconds  at the next leap event, the offset of UTC relative to Interna-
       tional Atomic Time (TAI) after the leap and the NTP  seconds  when  the
       leapseconds file expires and should be retrieved again.

       If  a  host  does  not have the leapsecond values, they can be obtained
       over the net using  the  Autokey  security  protocol.  Ordinarily,  the
       leapseconds  file  is  installed  on the primary servers and the values
       flow from them via secondary servers  to  the  clients.  When  multiple
       servers  are  involved,  the values with the latest expiration time are
       used.

       If the latest leap is in the past, nothing further is done  other  than
       to  install  the  TAI offset. If the leap is in the future less than 28
       days, the leap warning bits are set. If in  the  future  less  than  23
       hours,  the kernel is armed to insert one second at the end of the cur-
       rent day. Additional details are in The NTP Timescale and Leap  Seconds
       white paper at http://www.eecis.udel.edu/~mills/leap.html.

       If  none  of the above provisions are available, dsependent servers and
       clients tally the leap warning bits of surviving servers and  reference
       clocks.  When  a majority of the survivors show warning, a leap is pro-
       grammed at the end of the current month. During the month  and  day  of
       insertion, they operate as above. In this way the leap is is propagated
       at all dependent servers and clients.

OPTIONS
       -4, --ipv4
              Force DNS resolution of following host names on the command line
              to the IPv4 namespace. Cannot be used with the --ipv6 option.

       -6, --ipv6
              Force DNS resolution of following host names on the command line
              to the IPv6 namespace. Cannot be used with the --ipv6 option.

       -a, --authreq
              Require cryptographic authentication for broadcast client,  mul-
              ticast  client  and symmetric passive associations.  This is the
              default.  This option must not appear with authnoreq option.

       -A, --authnoreq
              Do  not  require  cryptographic  authentication  for   broadcast
              client,  multicast  client  and  symmetric passive associations.
              This is almost never a good idea. This option  must  not  appear
              with the authreq option.

       -b, --bcastsync
              Enable the client to sync to broadcast servers.


       -c string, --configfile=string
              The  name and path of the configuration file, /etc/inet/ntp.conf
              by default. This file must be readable by the user "daemon".  If
              the file does not exist the NTP service will not start.

       -d, --debug-level
              Increase  output debug message level.  This option may appear an
              unlimited number of times.

       -D string, --set-debug-level=string
              Set the output debugging level.  Can be supplied multiple times,
              but each overrides the previous value(s).

       -f string, --driftfile=string
              The  name  and path of the frequency file, /var/ntp/ntp.drift by
              default.

       -g, --panicgate
              Allow the first adjustment to exceed the panic limit.

              Normally, ntpd exits with a message to the  system  log  if  the
              offset  exceeds  the panic threshold, which is 1000s by default.
              This option allows the time to  be  set  to  any  value  without
              restriction;  however, this can happen only once. If the thresh-
              old is exceeded after that, ntpd will exit with a message to the
              system  log. This option can be used with the -q and -x options.
              See the tinker configuration file directive for other options.

       -k string, --keyfile=string
              Specify  the  name  and  path  of  the   symmetric   key   file.
              /etc/inet/ntp.keys is the default.

       -l string, --logfile=string
              Specify  the  name and path of the log file.  The default is the
              system log file. If logging is enabled to the logfile, the  log-
              file  must  be in a directory that is writable by the user "dae-
              mon" and if the file already exists, it also must  be  writeable
              by the user "daemon".

       -L, --novirtualips
              Do not listen to virtual IPs. The default is to listen.

       -m, --mdns
              Register  as a NTP server with mDNS system. Implies that you are
              willing to serve time to others.

       -n, --nofork
              Do not fork.


       -N, --nice
              To the extent permitted by the operating system, run ntpd at the
              highest priority.

       -p string, --pidfile=string
              Specify  the  name  and  path  of the file used to record ntpd's
              process ID.

       -P number, --priority=number
              To the extent permitted by the operating system, run ntpd at the
              specified sched_setscheduler(SCHED_FIFO) priority.

       -q, --quit
              Set the time and quit.  ntpd will exit just after the first time
              the clock is set. This behavior mimics that of the ntpdate  pro-
              gram, which is to be retired.  The -g and -x options can be used
              with this option.  Note: The kernel time discipline is  disabled
              with this option.

       -r string, --propagationdelay=string
              Specify  the default propagation delay from the broadcast/multi-
              cast server to this client. This is necessary only if the  delay
              cannot be computed automatically by the protocol.

       -s string, --statsdir=string
              Specify  the  directory path for files created by the statistics
              facility. This is the same operation as  the  statsdir  statsdir
              command.

       -t number, --trustedkey=number
              Add  a key number to the trusted key list. This option can occur
              more than once. This is the same operation as the trustedkey key
              command.

       -U number, --updateinterval=number
              interval in seconds between scans for new or dropped interfaces.
              This option takes an integer number as its argument.

              Give the time in seconds between two scans for  new  or  dropped
              interfaces.   For  systems with routing socket support the scans
              will be performed shortly after the interface  change  has  been
              detected  by  the system.  Use 0 to disable scanning. 60 seconds
              is the minimum time between scans.

       --var=nvar
              make ARG an ntp variable (RW).  This option may appear an unlim-
              ited number of times.


       --dvar=ndvar
              make  ARG  an  ntp variable (RW|DEF).  This option may appear an
              unlimited number of times.


       -x, --slew
              Slew up to 600 seconds.

              Normally, the time is slewed if the offset is less than the step
              threshold,  which is 128 ms by default, and stepped if above the
              threshold.  This option sets the threshold to 600  s,  which  is
              well  within  the  accuracy  window  to  set the clock manually.
              Note: Since the slew rate of typical Unix kernels is limited  to
              0.5  ms/s,  each  second  of adjustment requires an amortization
              interval of 2000 s.  Thus, an adjustment as much as 600  s  will
              take  almost  14 days to complete.  This option can be used with
              the -g and -q options.  See the tinker configuration file direc-
              tive  for  other  options.   Note: The kernel time discipline is
              disabled with this option.

       -?, --help
              Display usage information and exit.

       -!, --more-help
              Extended usage information passed thru pager.

        --version
              Output version of program and exit.

OPTION PRESETS
       All of the above options except the last three may be preset by loading
       values from environment variables named:
         NTPD_<option-name> or NTPD
       The  environmental  presets  take precedence (are processed later than)
       the configuration files. The option-name should be in all capital  let-
       ters.   For  example,  to  set  the  --quit  option,  you would set the
       NTPD_QUIT environment variable.

AUTOMATIC SERVICE MANAGEMENT (SMF)
       NTP on Solaris is managed via the service management facility described
       in  smf(7). There are several options controlled by services properties
       which can be set by the system administrator. The available options can
       be listed by executing the following command:
            svccfg -s svc:/network/ntp:default listprop config
       Each of these properties can be set using this command:
            svccfg -s  svc:/network/ntp:default setprop propname = value
       The available options and there meaning are as follows:

       config/always_allow_large_step
              A  boolean  which  when  false, prevents ntpd from allowing step
              larger than 17 minutes except once when the  system  boots.  The
              default  is  true, which allows such a large step once each time
              ntpd starts.

       config/debuglevel
              An integer specifying the level of debugging requested.  A  zero
              means no debugging. The default is zero.

       config/logfile
              A  string  specifying the location of the file used for log out-
              put. The default is  /var/ntp/ntp.log.  The  log  file  must  be
              writable  by  the user "daemon" andmust be in a directory write-
              able by that user.

       config/no_auth_required
              A boolean which when true, specifies that anonymous servers such
              as broadcast, multicast and active peers can be accepted without
              any pre-configured keys. This is very insecure and  should  only
              be  used  if  the nework is secure and all the systems on it are
              trusted. The default is false.

       config/slew_always
              A boolean which when true, instructs ntpd to slew the  clock  as
              much  as  possible,  instead  of stepping the clock. It does not
              prevent all stepping, but increases the  threshold  above  which
              stepping  is  used.  It  also disables the use of the kernel NTP
              facility, which  is  incompatible  with  long  slew  times.  The
              default is false.

       config/allow_step_at_boot
              A boolean which when true, allows ntpd to step the clock once at
              boot, even if slew_always is true. Normally when slew_always  is
              true ntpd will not step the clock except for very large offsets.
              Since the intial offset when the system is booted could be large
              and  no applications will be running yet, this option allows one
              step as soon as the offset  is  determined.  If  slew_always  is
              false or if the NTP service is being restarted, then this option
              has no effect. The default is true.

       config/wait_for_sync
              A boolean which when true, causes the NTP service to delay  com-
              ing  completely  on-line  until  after the first time the system
              clock is synchronized. This  can  potetially  delay  the  system
              start up by a significant amount. The default is false.

       config/disable_local_time_adjustment
              A  boolean  which  when  true,  causes the NTP service to be run
              without the privilege to adjust the system clock. When false the
              privilege  is  required to be present, otherwise the daemon will
              not start. The default is false.

       config/mdnsregister
              A boolean which when true, will cause  the  daemon  to  register
              with the network mDNS system. The default is false.

       config/verbose_logging
              A  boolean  which  when  true, cause the daemon to issue logging
              messages. The default is false.

       config/no_2038
              A boolean which when true will prevent the daemon from  stepping
              the clock to any date in the year 2038 or later. Dates after the
              epoch rollover in Februrary 2038 can render the system  unstable
              if  32-bit  system  processes are in use. In some configurations
              the instability may persist after the problem is corrected.  The
              default is false.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+---------------------+
       |ATTRIBUTE TYPE |  ATTRIBUTE VALUE    |
       +---------------+---------------------+
       |Availability   | service/network/ntp |
       +---------------+---------------------+
       |Stability      | Uncommitted         |
       +---------------+---------------------+
NOTES
       The  system  clock  must  be  set to within 68 years of the actual time
       before ntpd is started.

       The ntpd service is managed by the service management facility, smf(7),
       under the service identifier:

         svc:/network/ntp:default

       Administrative actions on this service, such as enabling, disabling, or
       requesting restart, can be performed  using  svcadm(8).  The  service's
       status can be queried using the svcs(1) command.

       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 qual-
       ifier forces DNS resolution to the IPv6 namespace.

       Various  internal  ntpd  variables  can  be displayed and configuration
       options altered while the ntpd is running using the ntpq  utility  pro-
       gram.

       When  ntpd starts it looks at the value of umask, and if zero ntpd will
       set the umask to 022.

       The documentation available at /usr/share/doc/ntp  is  provided  as  is
       from  the  NTP  distribution  and  may  contain information that is not
       applicable to the software as provided in this particular distribution.

       The ntpd daemon now runs as the user "daemon". Care must be taken if it
       is  configured  to  read  or  write files other than in the directories
       /etc/inet and /var/ntp. Any other locations will require that the  user
       daemon have the proper permissions to access the files.

       There     are     two    example    configuration    files    provided,
       /etc/inet/ntp.client and /etc/inet/ntp.server. The first provides exam-
       ples and some discussion around the configuration information that goes
       into the /etc/inet/ntp.conf file. The second focuses exclusively on the
       configuration  of  hardware  clocks for stratum zero servers and can be
       ignored by most users.

EXAMPLES
       The simplest way to start using the NTP service on a new host is to run
       the command:

         echo 'server hostname iburst' > /etc/inet/ntp.conf

       and then start the service. Replace 'hostname' with the actual hostname
       of an NTP server. You can add more lines like this one with  the  host-
       names  of  more  NTP  servers,  but  do not configure exactly two. Four
       servers is optimal, but never use two.

SEE ALSO
       svcs(1), sntp(8), ntp-keygen(8), ntpdate(8), ntpq(8), ntptrace(8), ntp-
       time(8), svcadm(8), rename(2), attributes(7), smf(7)



       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source          was         downloaded         from          http://ar-
       chive.ntp.org/ntp4/ntp-4.2/ntp-4.2.8p13.tar.gz

       Further information about this software can be found on the open source
       community website at http://www.ntp.org/.



                                                                       ntpd(8)