ntpd man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

ntpd(8)								       ntpd(8)

       ntpd - Network Time Protocol (NTP) daemon

       ntpd [ -46aAbdDgLnNqx ] [ -c conffile ] [ -f driftfile ] [ -i jaildir ]
       [ -I iface ] [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -P priority
       ]  [ -r broadcastdelay ] [ -s statsdir ] [ -t key ] [ -u user[:group] ]
       [ -U interface_update_interval ] [ -v variable ] [ -V variable ]

       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 version 1 and 2, as defined  by  RFC-1059	and  RFC-1119,
       respectively.  The  program  can	 operate  in  any of several modes, as
       described on the Association Management page, and with  both  symmetric
       key  and	 public	 key  cryptography, as described on the Authentication
       Options page.

       The ntpd program ordinarily requires a configuration file as  desccribe
       on  the	Configuration Commands and Options collection above. However a
       client can discover remote servers and  configure  them	automatically.
       This makes it possible to deploy a fleet of workstations without speci‐
       fying configuration details specific to the local environment.  Further
       details are on the Automatic Server Discovery page.

       Once  the NTP software distribution has been compiled and installed and
       the configuration file constructed, the next step is to verify  correct
       operation  and  fix any bugs that may result. Usually, the command line
       that starts the daemon is included in the system startup file, so it is
       executed	 only  at system boot time; however, the daemon can be stopped
       and restarted from root at any time.  Once  started,  the  daemon  will
       begin sending and receiving messages, as specified in the configuration

       The ntpd program operates by  exchanging	 messages  with	 one  or  more
       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 on  the
       Server Options page.

       Most  compters  today incorporate a time-of-year (TOY) chip to maintain
       the time during periods when the power is  off.	When  the  machine  is
       booted,	the  chip  is used to initialize the operating system time. In
       case there is no TOY chip or the TOY time is more than 1000 s from  the
       server  time,  ntpd  assumes something must be terribly wrong and exits
       with a panic message to the system operator. With  the  -g  option  the
       clock  will  be initially set to the server time regardless of the chip
       time. However, once the clock has been set, an error greater than  1000
       s will cause ntpd to exit anyway.

       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, by default
       128 ms, the spike is discarded. However, if the error persists for more
       than  the  stepout  threshold,  by  default  900 s, the system clock is
       stepped to the correct value. In practice the need for a	 step  has  is
       extremely rare and almost always the result of a hardware failure. With
       the -x option the step threshold is increased to 600 s.	Other  options
       are  available  using  the  tinker command on the Miscellaneous Options

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

       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.

       The ntpd program normally operates  continuously	 while	adjusting  the
       time and frequency, but in some cases it may not be practical to run it
       continuously. With the -q option ntpd operates as  in  continous	 mode,
       but exits just after setting the clock for the first time with the con‐
       figured servers. Most applications will probably want  to  specify  the
       iburst  option  with  the  server command. With this option a volley of
       messages is exchanged to groom the data and set the clock in  about  10
       s.  If  nothing	is heard after a few minutes, the daemon times out and

       NTP uses an intricate heuristic algorithm to automatically control  the
       poll  interval  for  maximum  accuracy  consistent with minimum network
       overhead. The algorithm measures the incidental offset  and  jitter  to
       determine the best poll interval. When ntpd starts, the interval is the
       default minimum 64 s. Under normal conditions when the clock discipline
       has  stabilized, the interval increases in steps to the default maximum
       1024 s. In addition, should a  server  become  unreachable  after  some
       time, the interval increases in steps to the maximum in order to reduce
       network overhead.

       The default poll interval range is suitable for	most  conditions,  but
       can  be	changed	 using options on the Server Options and Miscellaneous
       Options pages. However, when using maximum intervals much  larger  than
       the  default,  the  residual clock frequency error must be small enough
       for the discipline loop to capture and correct. The  capture  range  is
       500  PPM	 with  a  64-s interval decreasing by a factor of two for each
       interval doubling. At a 36-hr interval, for example, the capture	 range
       is only 0.24 PPM.

       In  scenarios  where a considerable amount of data are to be downloaded
       or uploaded over telephone modems, timekeeping quality can be seriously
       degraded. This occurs because the differential delays on the two direc‐
       tions of transmission can be quite large. 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.

       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, such as during other than work hours.  The
       filter  remembers  the minimum delay over the most recent interval mea‐
       sured usually in hours. Under conditions of severe  delay,  the	filter
       corrects	 the apparent offset using the sign of the offset and the dif‐
       ference 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  huffpuff	 command,  as  described  in the Miscellaneous Options

       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. When  this	file,  usually	called
       ntp-leapseconds.list, is copied and installed in a directory. The leap‐
       file configuration command 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.

       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.  If the kernel is enabled, the leap is done automatically at
       that time; otherwise, the clock is effectively stopped for  one	second
       at  the	leap. Additional details are in the The NTP Timescale and Leap
       Seconds white paper

       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.

       A  new experimental feature called interleaved modes can be used in NTP
       symmetric or broadcast modes. It is designed  to	 improve  accuracy  by
       avoiding	 kernel	 latency  and  queueing delay, as described on the NTP
       Interleaved Modes page. It is activated by the xleave option  with  the
       peer  or	 broadcast  configuration commands. The NTP protocol automati‐
       cally reconfigures in normal or interleaved mode as required.  Ordinary
       broadcast  clients  can	use the same servers as interleaved clients at
       the same time. Further details are in the white paper  NTP  Interleaved
       On-Wire Protocol and the briefing Interleaved Synchronization Protocols
       for LANs and Space Data Links.

       If ntpd, is configured with NetInfo support, it will  attempt  to  read
       its configuration from the NetInfo service if the default ntp.conf file
       cannot be read and no file is specified by the -c option.

       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 and ntpdc
       utility programs.

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

       Unless  the -n, -d or -D option is used, ntpd changes the current work‐
       ing directory to the root directory, so any options or commands	speci‐
       fying  paths  need  to  use  an absolute path or a path relative to the

       -4      Force DNS resolution of host names to the IPv4 namespace.

       -6      Force DNS resolution of host names to the IPv6 namespace.

       -a      Require cryptographic authentication for broadcast client, mul‐
	       ticast  client  and symmetric passive associations. This is the
	       same operation as the enable auth command and is the default.

       -A      Do  not	require	 cryptographic	authentication	for  broadcast
	       client,	multicast  client  and symmetric passive associations.
	       This is the same operation as  the  disable  auth  command  and
	       almost never a good idea.

       -b      Enable the client to synchronize to broadcast servers.

       -c conffile
	       Specify	the  name  and path of the configuration file, default

       -d      Specify debugging mode. This option may occur more  than	 once,
	       with each occurrence indicating greater detail of display.

       -D level
	       Specify debugging level directly.

       -f driftfile
	       Specify	the  name  and path of the frequency file. This is the
	       same operation as the driftfile driftfile command.

       -g      Normally, ntpd exits with a message to the system  log  if  the
	       offset exceeds the panic threshold, which is 1000 s 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 command for other options.

       -i jaildir
	       Chroot the server to the directory jaildir.  This  option  also
	       implies	that  the  server  attempts to drop root privileges at
	       startup (otherwise, chroot gives very little  additional	 secu‐
	       rity),  and  it is only available if the OS supports to run the
	       server without full root privileges. You may need to also spec‐
	       ify a -u option.

       -I [address | interface name]
	       Open the network address given, or all the addresses associated
	       with the given interface name. This option may appear  multiple
	       times.  This  option  also implies not opening other addresses,
	       except wildcard	and  localhost.	 This  option  is  deprecated.
	       Please consider using the configuration file interface command,
	       which is more versatile.

       -k keyfile
	       Specify the name and path of the symmetric key  file.  This  is
	       the same operation as the keys keyfile command.

       -l logfile
	       Specify	the  name and path of the log file. The default is the
	       system log file. This is the same operation as the logfile log‐
	       file command.

       -L      Do  not	listen	to  virtual  interfaces, defined as those with
	       names containing a colon. This  option  is  deprecated.	Please
	       consider	 using the configuration file interface command, which
	       is more versatile.

       -M      Raise scheduler precision to its maximum (1 msec) using timeBe‐
	       ginPeriod. (Windows only)

       -n      Don't fork.

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

       -p pidfile
	       Specify the name and path of the file used to record  the  ntpd
	       process	ID.  This is the same operation as the pidfile pidfile

       -P priority
	       To the extent permitted by the operating system, run  the  ntpd
	       at the specified priority.

       -q      Exit  the ntpd 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 broadcastdelay
	       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 statsdir
	       Specify the directory path for files created by the  statistics
	       facility.  This	is the same operation as the statsdir statsdir

       -t key  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 user[:group]
	       Specify a user, and optionally a	 group,	 to  switch  to.  This
	       option  is only available if the OS supports running the server
	       without full root privileges. Currently, this  option  is  sup‐
	       ported  under  NetBSD  (configure  with	--enable-clockctl) and
	       Linux (configure with --enable-linuxcaps).

       -U interface update interval
	       Number of seconds to wait between interface list scans to  pick
	       up  new	and  delete  network  interface.  Set  to 0 to disable
	       dynamic interface list updating. The default is to scan every 5

       -v variable

       -V variable
	       Add a system variable listed by default.

       -x      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 manu‐
	       ally. Note: Since the slew rate of typical Unix kernels is lim‐
	       ited to 0.5 ms/s, each second of adjustment requires an amorti‐
	       zation 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 command for other
	       options. Note: The kernel time discipline is disabled with this

       --pccfreq frequency
	       Substitute  processor cycle counter for QueryPerformanceCounter
	       unconditionally using the given frequency  (in  Hz).  --pccfreq
	       can  be	used  on systems which do not use the PCC to implement
	       QueryPerformanceCounter and have a  fixed  PCC  frequency.  The
	       frequency  specified  must  be  accurate	 within	 0.5  percent.
	       --usepcc is equivalent on many  systems	and  should  be	 tried
	       first,  as it does not require determining the frequency of the
	       processor cycle counter. For x86-compatible processors, the PCC
	       is  also	 referred  to as RDTSC, which is the assembly-language
	       instruction to retrieve the current value.  (Windows only)

	       Substitute processor cycle counter for  QueryPerformanceCounter
	       if  they	 appear equivalent. This option should be used only if
	       the PCC frequency is fixed. Power-saving functionality on  many
	       laptops varies the PCC frequency. (Windows only)

       Ordinarily,  ntpd  reads	 the ntp.conf configuration file at startup 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 con‐
       figured as a broadcast client, with servers determined by listening  to
       broadcasts at run time.

       Usually, the configuration file is installed as/etc/ntp.conf, 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 command keyword followed
       by a list of option keywords separated by whitespace. Commands may  not
       be  continued  over  multiple  lines.  Options  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	options	 pages,	 while
       alternatives  are  separated  by	 |.  The  notation  [  ...  ] means an
       optional, indefinite repetition of the last item before the [ ... ].

       │File		      │	 Default	  │  Option   │	 Command      │
       │configuration file    │	 /etc/ntp.conf	  │  -c	      │	 none	      │
       │frequency file	      │	 none		  │  -f	      │	 driftfile    │
       │leapseconds file      │	 none		  │	      │	 leapfile     │
       │process ID file	      │	 none		  │  -p	      │	 pidfile      │
       │log file	      │	 system log	  │  -l	      │	 logfile      │
       │include file	      │	 none		  │  none     │	 includefile  │
       │statistics path	      │	 /var/NTP	  │  -s	      │	 statsdir     │
       │keys path	      │	 /usr/local/etc	  │  -k	      │	 keysdir      │

       A non-zero exit code indicates an error. Any error messages are	logged
       to the system log by default.

       The  exit  code	is 0 only when ntpd is terminated by a signal, or when
       the -q option is used and ntpd successfully sets the system clock.

       ntp.conf(5), ntpq(8), ntpdc(8)

       The official HTML documentation.

       This file was automatically generated from HTML source.


List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net