Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022

ntpd (8)


ntpd - Network Time Protocol daemon Version 4


/usr/lib/inet/ntpd [-46aAbdDgiILmnNqvx] [-c conffile]
[-f driftfile] [-i jaildir] [-k keyfile] [-l logfile]
[-p pidfile] [-P priority] [-r broadcastdelay]
[-s statsdir] [-t trustedkey] [-u user[:group]]
[-U interface_update_time] [--var nvar] [--dvar ndvar]


System Administration Commands                                         ntpd(8)

       ntpd - Network Time Protocol daemon Version 4

       /usr/lib/inet/ntpd [-46aAbdDgiILmnNqvx] [-c conffile]
           [-f driftfile] [-i jaildir] [-k keyfile] [-l logfile]
           [-p pidfile] [-P priority] [-r broadcastdelay]
           [-s statsdir] [-t trustedkey] [-u user[:group]]
           [-U interface_update_time] [--var nvar] [--dvar ndvar]

       The  ntpd  program  is an operating system daemon that synchronizes 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,

   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

       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 round-trip 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

       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

   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
       timestamp  at the next leap event, the offset of UTC relative to Inter-
       national Atomic Time (TAI) after the leap and the  NTP  timestamp  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

       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, dependent 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.

   Monitor Mode
       In addition to the default instance of  NTP  (svc:/network/ntp:default)
       which   behaves   normally,    there   is  second  instance  (svc:/net-
       work/ntp:monitor) which can be used to monitor the system clock. It has
       the  same  effect  as  adding  "disable ntp" to the configuration file,
       which disables ntpd's ability to adjust the system clock. It  can  then
       be  used to monitor and record the system clock offsets but will not be
       able to correct them. When enabled it also disables the check  in  both
       the  NTP  and  PTP  services that prevent them from both running at the
       same time. Thus ntp:monitor can be used to measure  the  clock  offsets
       being set by PTP.

       -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

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

       -i jaildir, --jaildir=string
              Specify  a  directory where ntpd can be isolated with the chroot

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

       -u user[:group], --user=string
              Specify a user, and optionally a group, to switch to.

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

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

              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.

              Output version of program and exit.

       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.

       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:

              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.

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

              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" and must be in a directory  write-
              able by that user.

              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 network is secure and all the systems on  it  are
              trusted. The default is false.

              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.

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

              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 potentially delay the system
              start up by a significant amount. The default is false.

              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.

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

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

              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 Feburary 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 true.

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

       |Availability   | service/network/ntp |
       |Stability      | Uncommitted         |

       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:


       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-

       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.

       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source          was         downloaded         from          http://ar-

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

       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.

       You can add as many servers as you like but only maxclock (default  10)
       servers  will  actually  be  used.  Do  not configure exactly two. Four
       servers is optimal, but never use two. If for some reason you only have
       two  and  you must have redundancy put the prefer keyword on one of the
       server lines to mitigate most of the problems with using two servers.

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