man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2014

ntpd (1m)


ntpd - Network Time Protocol daemon Version 4


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


SunOS 5.11                                                      1

System Administration Commands                           ntpd(1M)

     ntpd - Network Time Protocol daemon Version 4

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

     The ntpd program is an operating system daemon that synchro-
     nises 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 com-
     patibility  with version 3, as defined by RFC 1305, and ver-
     sions 1 and 2, as defined by RFC 1059 and RFC 1119,  respec-

  How NTP Operates
     The ntpd program operates by exchanging messages with one or
     more configured servers at designated intervals ranging from
     about one minute to about 17 minutes. When started, the pro-
     gram requires several exchanges while the algorithms accumu-
     late  and  groom the data before setting the clock. The ini-
     tial 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 synchronized 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
     something must be terribly wrong and exits with a panic mes-
     sage  to  the system log. If it was started via SMF, the ntp
     service is placed into maintainance 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 network 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

SunOS 5.11                Last change:                          1

System Administration Commands                           ntpd(1M)

     command  as  described  in the miscellaneous options page at

     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 sys-
     tem cannot be used for distributed applications that require
     correctly synchronized network time.

  Frequency Discipline
     The  frequency  file, usually called ntp.drift, contains the
     latest estimate 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, includ-
     ing symmetric active/passive, client/server broadcast/multi-
     cast  and  manycast, as described in the Association Manage-
     ment page at file:///usr/share/doc/ntp/assoc.html.  It  nor-
     mally  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/mul-
     ticast or manycast client can discover remote servers,  com-
     pute  server-client propagation delay correction factors and
     configure itself automatically. This makes  it  possible  to
     deploy a fleet of workstations without specifying configura-
     tion details specific to the local environment.

     By default, ntpd runs in continuous mode where each of  pos-
     sibly several external servers is polled at intervals deter-
     mined 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. Ordinarily,
     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

SunOS 5.11                Last change:                          2

System Administration Commands                           ntpd(1M)

     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 con-
     tinuously. 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  process-
     ing,  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 initially setting the clock is the
     same as in continuous mode; most applications will  probably
     want  to specify the iburst keyword with the server configu-
     ration 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 dae-
     mon  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 discipline 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  kernel  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 syn-
     chronization consistent with the observed jitter and wander.
     There  are a number of ways to tailor 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  broad-
     cast  server  and manycast client associations will also use
     the default, unless overridden. In general, it  is  best  to

SunOS 5.11                Last change:                          3

System Administration Commands                           ntpd(1M)

     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,  time-
     keeping quality can be seriously degraded due to the differ-
     ent 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 trans-
     fer 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 fil-
     ter maintains a shift register that  remembers  the  minimum
     delay  over  the  most  recent  interval measured usually 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)  pro-
     vides  an  historic  leapseconds  file  at for
     retrieval via FTP. This file,  usually  called  ntp-leapsec-
     onds.list,  is  copied  into the /etc/inet directory and the
     leapfile 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 International Atomic Time
     (TAI) after the leap and the NTP seconds when  the  leapsec-
     onds file expires and should be retrieved again.

SunOS 5.11                Last change:                          4

System Administration Commands                           ntpd(1M)

     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 val-
     ues 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 current day.  Additional
     details  are in the The NTP Timescale and Leap Seconds white
     paper at

     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  sur-
     vivors  show warning, a leap is programmed 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.

     -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, multicast client and symmetric passive associa-
          tions.  This is the  default.   This  option  must  not
          appear with authnoreq option.

     -A, --authnoreq
          Do  not require cryptographic authentication for broad-
          cast 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,

SunOS 5.11                Last change:                          5

System Administration Commands                           ntpd(1M)

          /etc/inet/ntp.conf by default.

     -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 multi-
          ple 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 threshold  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

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

     -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

SunOS 5.11                Last change:                          6

System Administration Commands                           ntpd(1M)

          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)

     -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 program, 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  broad-
          cast/multicast 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

          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 unlimited number of times.

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

SunOS 5.11                Last change:                          7

System Administration Commands                           ntpd(1M)

     -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 directive for other options.   Note:
          The  kernel  time  discipline  is  disabled  with  this

     -?, --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 letters.  For example, to set the --quit
     option, you would set the NTPD_QUIT environment variable.

     NTP on Solaris is managed via the service management  facil-
     ity described in
      smf(5).  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
          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.

SunOS 5.11                Last change:                          8

System Administration Commands                           ntpd(1M)

          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 output. The default is /var/ntp/ntp.log

          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.

          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

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

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

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

     See   attributes(5)   for   descriptions  of  the  following

SunOS 5.11                Last change:                          9

System Administration Commands                           ntpd(1M)

     |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 facil-
     ity, smf(5), under the service identifier:


     Administrative actions on this service,  such  as  enabling,
     disabling,  or  requesting  restart,  can be performed using
     svcadm(1M). 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 qualifier forces DNS resolution to the
     IPv6 namespace.

     Various internal ntpd variables can be displayed and config-
     uration  options altered while the ntpd is running using the
     ntpq and ntpdc utility programs.

     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 pro-
     vided as is from the NTP distribution and may contain infor-
     mation that is not applicable to the software as provided in
     this particular distribution.

     svcs(1), sntp(1M),  ntp-keygen(1M),  ntpdate(1m),  ntpq(1M),
     ntptrace(1M), ntptime(1M), svcadm(1M), ntpdc(1M), rename(2),
     attributes(5), smf(5)

     This  software  was   built   from   source   available   at    The  original
     community   source   was   downloaded    from     http://ar-

     Further  information about this software can be found on the
     open source community website at

SunOS 5.11                Last change:                         10