ntpd.mdoc.in revision 294569
1238730Sdelphij.Dd January 20 2016 2330571Sdelphij.Dt NTPD @NTPD_MS@ User Commands 3238730Sdelphij.Os 4238730Sdelphij.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) 5238730Sdelphij.\" 6238730Sdelphij.\" It has been AutoGen-ed January 20, 2016 at 04:18:12 AM by AutoGen 5.18.5 7238730Sdelphij.\" From the definitions ntpd-opts.def 8238730Sdelphij.\" and the template file agmdoc-cmd.tpl 960786Sps.Sh NAME 1060786Sps.Nm ntpd 1160786Sps.Nd NTP daemon program 1260786Sps.Sh SYNOPSIS 1360786Sps.Nm 1460786Sps.\" Mixture of short (flag) options and long options 1560786Sps.Op Fl flags 1660786Sps.Op Fl flag Op Ar value 1760786Sps.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 1860786Sps[ <server1> ... <serverN> ] 1960786Sps.Pp 2060786Sps.Sh DESCRIPTION 2160786SpsThe 2260786Sps.Nm 2360786Spsutility is an operating system daemon which sets 2460786Spsand maintains the system time of day in synchronism with Internet 2560786Spsstandard time servers. 2660786SpsIt is a complete implementation of the 2760786SpsNetwork Time Protocol (NTP) version 4, as defined by RFC\-5905, 2860786Spsbut also retains compatibility with 2960786Spsversion 3, as defined by RFC\-1305, and versions 1 3060786Spsand 2, as defined by RFC\-1059 and RFC\-1119, respectively. 3160786Sps.Pp 3260786SpsThe 3360786Sps.Nm 3460786Spsutility does most computations in 64\-bit floating point 3560786Spsarithmetic and does relatively clumsy 64\-bit fixed point operations 3660786Spsonly when necessary to preserve the ultimate precision, about 232 3760786Spspicoseconds. 3860786SpsWhile the ultimate precision is not achievable with 3960786Spsordinary workstations and networks of today, it may be required 4060786Spswith future gigahertz CPU clocks and gigabit LANs. 41128345Stjr.Pp 4260786SpsOrdinarily, 43128345Stjr.Nm 44128345Stjrreads the 4560786Sps.Xr ntp.conf 5 4660786Spsconfiguration file at startup time in order to determine the 47128345Stjrsynchronization sources and operating modes. 4860786SpsIt is also possible to 4960786Spsspecify a working, although limited, configuration entirely on the 5060786Spscommand line, obviating the need for a configuration file. 5160786SpsThis may 5260786Spsbe particularly useful when the local host is to be configured as a 5360786Spsbroadcast/multicast client, with all peers being determined by 5460786Spslistening to broadcasts at run time. 5560786Sps.Pp 5660786SpsIf NetInfo support is built into 5760786Sps.Nm , 58191930Sdelphijthen 5960786Sps.Nm 6060786Spswill attempt to read its configuration from the 6160786SpsNetInfo if the default 62128345Stjr.Xr ntp.conf 5 63128345Stjrfile cannot be read and no file is 64128345Stjrspecified by the 65128345Stjr.Fl c 6660786Spsoption. 6760786Sps.Pp 6860786SpsVarious internal 6960786Sps.Nm 70191930Sdelphijvariables can be displayed and 7160786Spsconfiguration options altered while the 7260786Sps.Nm 7360786Spsis running 7460786Spsusing the 7560786Sps.Xr ntpq @NTPQ_MS@ 7660786Spsand 7760786Sps.Xr ntpdc @NTPDC_MS@ 78330571Sdelphijutility programs. 7960786Sps.Pp 8060786SpsWhen 8160786Sps.Nm 8260786Spsstarts it looks at the value of 8360786Sps.Xr umask 2 , 8460786Spsand if zero 8560786Sps.Nm 8660786Spswill set the 8760786Sps.Xr umask 2 8860786Spsto 022. 8960786Sps.Sh "OPTIONS" 9060786Sps.Bl -tag 9160786Sps.It Fl 4 , Fl \-ipv4 9260786SpsForce IPv4 DNS name resolution. 9360786SpsThis option must not appear in combination with any of the following options: 9460786Spsipv6. 9560786Sps.sp 9660786SpsForce DNS resolution of following host names on the command line 9760786Spsto the IPv4 namespace. 9860786Sps.It Fl 6 , Fl \-ipv6 9960786SpsForce IPv6 DNS name resolution. 10060786SpsThis option must not appear in combination with any of the following options: 10160786Spsipv4. 10260786Sps.sp 10360786SpsForce DNS resolution of following host names on the command line 10460786Spsto the IPv6 namespace. 105330571Sdelphij.It Fl a , Fl \-authreq 10660786SpsRequire crypto authentication. 10760786SpsThis option must not appear in combination with any of the following options: 10860786Spsauthnoreq. 10960786Sps.sp 11060786SpsRequire cryptographic authentication for broadcast client, 11160786Spsmulticast client and symmetric passive associations. 11260786SpsThis is the default. 11360786Sps.It Fl A , Fl \-authnoreq 11460786SpsDo not require crypto authentication. 11560786SpsThis option must not appear in combination with any of the following options: 11660786Spsauthreq. 11760786Sps.sp 11860786SpsDo not require cryptographic authentication for broadcast client, 11960786Spsmulticast client and symmetric passive associations. 12060786SpsThis is almost never a good idea. 12160786Sps.It Fl b , Fl \-bcastsync 12260786SpsAllow us to sync to broadcast servers. 12360786Sps.sp 124128345Stjr.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string 125128345Stjrconfiguration file name. 12660786Sps.sp 12760786SpsThe name and path of the configuration file, 128330571Sdelphij\fI/etc/ntp.conf\fP 129330571Sdelphijby default. 130330571Sdelphij.It Fl d , Fl \-debug\-level 131330571SdelphijIncrease debug verbosity level. 132330571SdelphijThis option may appear an unlimited number of times. 13360786Sps.sp 13460786Sps.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 13560786SpsSet the debug verbosity level. 13660786SpsThis option may appear an unlimited number of times. 13760786SpsThis option takes an integer number as its argument. 13860786Sps.sp 139128345Stjr.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string 14060786Spsfrequency drift file name. 14160786Sps.sp 14260786SpsThe name and path of the frequency file, 14360786Sps\fI/etc/ntp.drift\fP 14460786Spsby default. 14560786SpsThis is the same operation as the 14660786Sps\fBdriftfile\fP \fIdriftfile\fP 14760786Spsconfiguration specification in the 14860786Sps\fI/etc/ntp.conf\fP 14960786Spsfile. 15060786Sps.It Fl g , Fl \-panicgate 15160786SpsAllow the first adjustment to be Big. 15260786SpsThis option may appear an unlimited number of times. 15360786Sps.sp 15460786SpsNormally, 15560786Sps\fBntpd\fP 15660786Spsexits 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 threshold is exceeded after that, 15760786Sps\fBntpd\fP 15860786Spswill exit with a message to the system log. This option can be used with the 15960786Sps\fB\-q\fP 16060786Spsand 16160786Sps\fB\-x\fP 16260786Spsoptions. 16360786SpsSee the 16460786Sps\fBtinker\fP 16560786Spsconfiguration file directive for other options. 16660786Sps.It Fl G , Fl \-force\-step\-once 16760786SpsStep any initial offset correction.. 16860786Sps.sp 16960786SpsNormally, 170128345Stjr\fBntpd\fP 17160786Spssteps the time if the time offset exceeds the step threshold, 17260786Spswhich is 128 ms by default, and otherwise slews the time. 17360786SpsThis option forces the initial offset correction to be stepped, 17460786Spsso the highest time accuracy can be achieved quickly. 17560786SpsHowever, this may also cause the time to be stepped back 17660786Spsso this option must not be used if 17760786Spsapplications requiring monotonic time are running. 17860786SpsSee the \fBtinker\fP configuration file directive for other options. 17960786Sps.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string 18060786SpsJail directory. 18160786Sps.sp 18260786SpsChroot the server to the directory 18360786Sps\fIjaildir\fP 18460786Sps. 18560786SpsThis option also implies that the server attempts to drop root privileges at startup. 18660786SpsYou may need to also specify a 18760786Sps\fB\-u\fP 18860786Spsoption. 18960786SpsThis option is only available if the OS supports adjusting the clock 19060786Spswithout full root privileges. 19160786SpsThis option is supported under NetBSD (configure with 19260786Sps\fB\-\-enable\-clockctl\fP) or Linux (configure with 19360786Sps\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 19460786Sps.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface 19560786SpsListen on an interface name or address. 19660786SpsThis option may appear an unlimited number of times. 19760786Sps.sp 19860786SpsOpen the network address given, or all the addresses associated with the 19960786Spsgiven interface name. This option may appear multiple times. This option 20060786Spsalso implies not opening other addresses, except wildcard and localhost. 20160786SpsThis option is deprecated. Please consider using the configuration file 20260786Sps\fBinterface\fP command, which is more versatile. 20360786Sps.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string 20460786Spspath to symmetric keys. 20560786Sps.sp 20660786SpsSpecify the name and path of the symmetric key file. 20760786Sps\fI/etc/ntp.keys\fP 20860786Spsis the default. 20960786SpsThis is the same operation as the 21060786Sps\fBkeys\fP \fIkeyfile\fP 21160786Spsconfiguration file directive. 21260786Sps.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string 21360786Spspath to the log file. 21460786Sps.sp 21560786SpsSpecify the name and path of the log file. 21660786SpsThe default is the system log file. 21760786SpsThis is the same operation as the 21860786Sps\fBlogfile\fP \fIlogfile\fP 219294286Sdelphijconfiguration file directive. 22060786Sps.It Fl L , Fl \-novirtualips 22160786SpsDo not listen to virtual interfaces. 22260786Sps.sp 22360786SpsDo not listen to virtual interfaces, defined as those with 22460786Spsnames containing a colon. This option is deprecated. Please 22560786Spsconsider using the configuration file \fBinterface\fP command, which 22660786Spsis more versatile. 22760786Sps.It Fl M , Fl \-modifymmtimer 22860786SpsModify Multimedia Timer (Windows only). 22960786Sps.sp 23060786SpsSet the Windows Multimedia Timer to highest resolution. This 23160786Spsensures the resolution does not change while ntpd is running, 23260786Spsavoiding timekeeping glitches associated with changes. 23360786Sps.It Fl n , Fl \-nofork 23460786SpsDo not fork. 23560786SpsThis option must not appear in combination with any of the following options: 23660786Spswait\-sync. 23760786Sps.sp 23860786Sps.It Fl N , Fl \-nice 23960786SpsRun at high priority. 24060786Sps.sp 24160786SpsTo the extent permitted by the operating system, run 24260786Sps\fBntpd\fP 24360786Spsat the highest priority. 24460786Sps.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string 245191930Sdelphijpath to the PID file. 246191930Sdelphij.sp 247191930SdelphijSpecify the name and path of the file used to record 248191930Sdelphij\fBntpd\fP's 249191930Sdelphijprocess ID. 250191930SdelphijThis is the same operation as the 251191930Sdelphij\fBpidfile\fP \fIpidfile\fP 252191930Sdelphijconfiguration file directive. 253191930Sdelphij.It Fl P Ar number , Fl \-priority Ns = Ns Ar number 254191930SdelphijProcess priority. 255191930SdelphijThis option takes an integer number as its argument. 256191930Sdelphij.sp 257191930SdelphijTo the extent permitted by the operating system, run 258191930Sdelphij\fBntpd\fP 259191930Sdelphijat the specified 260191930Sdelphij\fBsched_setscheduler(SCHED_FIFO)\fP 26160786Spspriority. 26260786Sps.It Fl q , Fl \-quit 26360786SpsSet the time and quit. 264128345StjrThis option must not appear in combination with any of the following options: 26560786Spssaveconfigquit, wait\-sync. 26660786Sps.sp 26760786Sps\fBntpd\fP 268330571Sdelphijwill not daemonize and will exit after the clock is first 269330571Sdelphijsynchronized. This behavior mimics that of the 27060786Sps\fBntpdate\fP 27160786Spsprogram, which will soon be replaced with a shell script. 27260786SpsThe 27360786Sps\fB\-g\fP 27460786Spsand 27560786Sps\fB\-x\fP 27660786Spsoptions can be used with this option. 27760786SpsNote: The kernel time discipline is disabled with this option. 27860786Sps.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string 27960786SpsBroadcast/propagation delay. 28060786Sps.sp 28160786SpsSpecify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol. 28260786Sps.It Fl \-saveconfigquit Ns = Ns Ar string 28360786SpsSave parsed configuration and quit. 28460786SpsThis option must not appear in combination with any of the following options: 28560786Spsquit, wait\-sync. 28660786Sps.sp 28760786SpsCause \fBntpd\fP to parse its startup configuration file and save an 28860786Spsequivalent to the given filename and exit. This option was 28960786Spsdesigned for automated testing. 29060786Sps.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string 29160786SpsStatistics file location. 29260786Sps.sp 29360786SpsSpecify the directory path for files created by the statistics facility. 29460786SpsThis is the same operation as the 29560786Sps\fBstatsdir\fP \fIstatsdir\fP 29660786Spsconfiguration file directive. 29760786Sps.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey 29860786SpsTrusted key number. 29960786SpsThis option may appear an unlimited number of times. 30060786Sps.sp 30160786SpsAdd the specified key number to the trusted key list. 30260786Sps.It Fl u Ar string , Fl \-user Ns = Ns Ar string 30360786SpsRun as userid (or userid:groupid). 30460786Sps.sp 30560786SpsSpecify a user, and optionally a group, to switch to. 30660786SpsThis option is only available if the OS supports adjusting the clock 30760786Spswithout full root privileges. 30860786SpsThis option is supported under NetBSD (configure with 30960786Sps\fB\-\-enable\-clockctl\fP) or Linux (configure with 31060786Sps\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 31160786Sps.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number 31260786Spsinterval in seconds between scans for new or dropped interfaces. 31360786SpsThis option takes an integer number as its argument. 31460786Sps.sp 31560786SpsGive the time in seconds between two scans for new or dropped interfaces. 31660786SpsFor systems with routing socket support the scans will be performed shortly after the interface change 31760786Spshas been detected by the system. 31860786SpsUse 0 to disable scanning. 60 seconds is the minimum time between scans. 31960786Sps.It Fl \-var Ns = Ns Ar nvar 320128345Stjrmake ARG an ntp variable (RW). 32160786SpsThis option may appear an unlimited number of times. 32260786Sps.sp 32360786Sps.It Fl \-dvar Ns = Ns Ar ndvar 32460786Spsmake ARG an ntp variable (RW|DEF). 325170256SdelphijThis option may appear an unlimited number of times. 326191930Sdelphij.sp 327191930Sdelphij.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number 32860786SpsSeconds to wait for first clock sync. 329191930SdelphijThis option must not appear in combination with any of the following options: 330191930Sdelphijnofork, quit, saveconfigquit. 331191930SdelphijThis option takes an integer number as its argument. 33260786Sps.sp 33360786SpsIf greater than zero, alters \fBntpd\fP's behavior when forking to 33460786Spsdaemonize. Instead of exiting with status 0 immediately after 33560786Spsthe fork, the parent waits up to the specified number of 33660786Spsseconds for the child to first synchronize the clock. The exit 337128345Stjrstatus is zero (success) if the clock was synchronized, 33860786Spsotherwise it is \fBETIMEDOUT\fP. 33960786SpsThis provides the option for a script starting \fBntpd\fP to easily 34060786Spswait for the first set of the clock before proceeding. 34160786Sps.It Fl x , Fl \-slew 34260786SpsSlew up to 600 seconds. 343128345Stjr.sp 34460786SpsNormally, 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. 34560786SpsThis option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 34660786SpsNote: 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. 34760786SpsThus, an adjustment as much as 600 s will take almost 14 days to complete. 34860786SpsThis option can be used with the 34960786Sps\fB\-g\fP 35060786Spsand 35160786Sps\fB\-q\fP 352128345Stjroptions. 35360786SpsSee the 35460786Sps\fBtinker\fP 35560786Spsconfiguration file directive for other options. 35660786SpsNote: The kernel time discipline is disabled with this option. 357170256Sdelphij.It Fl \-usepcc 358191930SdelphijUse CPU cycle counter (Windows only). 359191930Sdelphij.sp 36060786SpsAttempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 361191930SdelphijThe CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 362191930Sdelphijthey have the same frequency, the CPU counter (RDTSC on x86) is 363191930Sdelphijused directly, saving the overhead of a system call. 36460786Sps.It Fl \-pccfreq Ns = Ns Ar string 36560786SpsForce CPU cycle counter use (Windows only). 36660786Sps.sp 36760786SpsForce substitution the CPU counter for \fBQueryPerformanceCounter\fP. 36860786SpsThe CPU counter (RDTSC on x86) is used unconditionally with the 369128345Stjrgiven frequency (in Hz). 37060786Sps.It Fl m , Fl \-mdns 37160786SpsRegister with mDNS as a NTP server. 372128345Stjr.sp 37360786SpsRegisters as an NTP server with the local mDNS server which allows 37460786Spsthe server to be discovered via mDNS client lookup. 37560786Sps.It Fl \&? , Fl \-help 37660786SpsDisplay usage information and exit. 37760786Sps.It Fl \&! , Fl \-more\-help 37860786SpsPass the extended usage information through a pager. 37960786Sps.It Fl \-version Op Brq Ar v|c|n 380128345StjrOutput version of program and exit. The default mode is `v', a simple 381128345Stjrversion. The `c' mode will print copyright information and `n' will 38260786Spsprint the full copyright notice. 383330571Sdelphij.El 38460786Sps.Sh "OPTION PRESETS" 385128345StjrAny option that is not marked as \fInot presettable\fP may be preset 38660786Spsby loading values from environment variables named: 387128345Stjr.nf 38860786Sps \fBNTPD_<option\-name>\fP or \fBNTPD\fP 38960786Sps.fi 39060786Sps.ad 39160786Sps.Sh USAGE 39260786Sps.Ss "How NTP Operates" 39360786SpsThe 39460786Sps.Nm 39560786Spsutility operates by exchanging messages with 396128345Stjrone or more configured servers over a range of designated poll intervals. 39760786SpsWhen 398128345Stjrstarted, whether for the first or subsequent times, the program 39960786Spsrequires several exchanges from the majority of these servers so 40060786Spsthe signal processing and mitigation algorithms can accumulate and 40160786Spsgroom the data and set the clock. 402128345StjrIn order to protect the network 40360786Spsfrom bursts, the initial poll interval for each server is delayed 40460786Spsan interval randomized over a few seconds. 40560786SpsAt the default initial poll 40660786Spsinterval of 64s, several minutes can elapse before the clock is 40760786Spsset. 40860786SpsThis initial delay to set the clock 40960786Spscan be safely and dramatically reduced using the 410128345Stjr.Cm iburst 41160786Spskeyword with the 41260786Sps.Ic server 41360786Spsconfiguration 41460786Spscommand, as described in 415170256Sdelphij.Xr ntp.conf 5 . 416191930Sdelphij.Pp 41760786SpsMost operating systems and hardware of today incorporate a 418191930Sdelphijtime\-of\-year (TOY) chip to maintain the time during periods when 419191930Sdelphijthe power is off. 42060786SpsWhen the machine is booted, the chip is used to 42160786Spsinitialize the operating system time. 42260786SpsAfter the machine has 42360786Spssynchronized to a NTP server, the operating system corrects the 42460786Spschip from time to time. 42560786SpsIn the default case, if 42660786Sps.Nm 42760786Spsdetects that the time on the host 428128345Stjris more than 1000s from the server time, 42960786Sps.Nm 43060786Spsassumes something must be terribly wrong and the only 43160786Spsreliable action is for the operator to intervene and set the clock 43260786Spsby hand. 433170256Sdelphij(Reasons for this include there is no TOY chip, 434191930Sdelphijor its battery is dead, or that the TOY chip is just of poor quality.) 43560786SpsThis causes 436191930Sdelphij.Nm 437191930Sdelphijto exit with a panic message to 43860786Spsthe system log. 43960786SpsThe 44060786Sps.Fl g 44160786Spsoption overrides this check and the 44260786Spsclock will be set to the server time regardless of the chip time 443128345Stjr(up to 68 years in the past or future \(em 44460786Spsthis is a limitation of the NTPv4 protocol). 44560786SpsHowever, and to protect against broken hardware, such as when the 44660786SpsCMOS battery fails or the clock counter becomes defective, once the 44760786Spsclock has been set an error greater than 1000s will cause 44860786Sps.Nm 44960786Spsto exit anyway. 45060786Sps.Pp 45160786SpsUnder ordinary conditions, 452128345Stjr.Nm 45360786Spsadjusts the clock in 45460786Spssmall steps so that the timescale is effectively continuous and 45560786Spswithout discontinuities. 45660786SpsUnder conditions of extreme network 45760786Spscongestion, the roundtrip delay jitter can exceed three seconds and 458128345Stjrthe synchronization distance, which is equal to one\-half the 45960786Spsroundtrip delay plus error budget terms, can become very large. 46060786SpsThe 46160786Sps.Nm 46260786Spsalgorithms discard sample offsets exceeding 128 ms, 46360786Spsunless the interval during which no sample offset is less than 128 46460786Spsms exceeds 900s. 46560786SpsThe first sample after that, no matter what the 466128345Stjroffset, steps the clock to the indicated time. 46760786SpsIn practice this 468128345Stjrreduces the false alarm rate where the clock is stepped in error to 469128345Stjra vanishingly low incidence. 47060786Sps.Pp 471As the result of this behavior, once the clock has been set it 472very rarely strays more than 128 ms even under extreme cases of 473network path congestion and jitter. 474Sometimes, in particular when 475.Nm 476is first started without a valid drift file 477on a system with a large intrinsic drift 478the error might grow to exceed 128 ms, 479which would cause the clock to be set backwards 480if the local clock time is more than 128 s 481in the future relative to the server. 482In some applications, this behavior may be unacceptable. 483There are several solutions, however. 484If the 485.Fl x 486option is included on the command line, the clock will 487never be stepped and only slew corrections will be used. 488But this choice comes with a cost that 489should be carefully explored before deciding to use 490the 491.Fl x 492option. 493The maximum slew rate possible is limited 494to 500 parts\-per\-million (PPM) as a consequence of the correctness 495principles on which the NTP protocol and algorithm design are 496based. 497As a result, the local clock can take a long time to 498converge to an acceptable offset, about 2,000 s for each second the 499clock is outside the acceptable range. 500During this interval the 501local clock will not be consistent with any other network clock and 502the system cannot be used for distributed applications that require 503correctly synchronized network time. 504.Pp 505In spite of the above precautions, sometimes when large 506frequency errors are present the resulting time offsets stray 507outside the 128\-ms range and an eventual step or slew time 508correction is required. 509If following such a correction the 510frequency error is so large that the first sample is outside the 511acceptable range, 512.Nm 513enters the same state as when the 514.Pa ntp.drift 515file is not present. 516The intent of this behavior 517is to quickly correct the frequency and restore operation to the 518normal tracking mode. 519In the most extreme cases 520(the host 521.Cm time.ien.it 522comes to mind), there may be occasional 523step/slew corrections and subsequent frequency corrections. 524It 525helps in these cases to use the 526.Cm burst 527keyword when 528configuring the server, but 529ONLY 530when you have permission to do so from the owner of the target host. 531.Pp 532Finally, 533in the past many startup scripts would run 534.Xr ntpdate @NTPDATE_MS@ 535or 536.Xr sntp @SNTP_MS@ 537to get the system clock close to correct before starting 538.Xr ntpd @NTPD_MS@ , 539but this was never more than a mediocre hack and is no longer needed. 540If you are following the instructions in 541.Sx "Starting NTP (Best Current Practice)" 542and you still need to set the system time before starting 543.Nm , 544please open a bug report and document what is going on, 545and then look at using 546.Xr sntp @SNTP_MS@ 547if you really need to set the clock before starting 548.Nm . 549.Pp 550There is a way to start 551.Xr ntpd @NTPD_MS@ 552that often addresses all of the problems mentioned above. 553.Ss "Starting NTP (Best Current Practice)" 554First, use the 555.Cm iburst 556option on your 557.Cm server 558entries. 559.Pp 560If you can also keep a good 561.Pa ntp.drift 562file then 563.Xr ntpd @NTPD_MS@ 564will effectively "warm\-start" and your system's clock will 565be stable in under 11 seconds' time. 566.Pp 567As soon as possible in the startup sequence, start 568.Xr ntpd @NTPD_MS@ 569with at least the 570.Fl g 571and perhaps the 572.Fl N 573options. 574Then, 575start the rest of your "normal" processes. 576This will give 577.Xr ntpd @NTPD_MS@ 578as much time as possible to get the system's clock synchronized and stable. 579.Pp 580Finally, 581if you have processes like 582.Cm dovecot 583or database servers 584that require 585monotonically\-increasing time, 586run 587.Xr ntp\-wait 1ntp\-waitmdoc 588as late as possible in the boot sequence 589(perhaps with the 590.Fl v 591flag) 592and after 593.Xr ntp\-wait 1ntp\-waitmdoc 594exits successfully 595it is as safe as it will ever be to start any process that require 596stable time. 597.Ss "Frequency Discipline" 598The 599.Nm 600behavior at startup depends on whether the 601frequency file, usually 602.Pa ntp.drift , 603exists. 604This file 605contains the latest estimate of clock frequency error. 606When the 607.Nm 608is started and the file does not exist, the 609.Nm 610enters a special mode designed to quickly adapt to 611the particular system clock oscillator time and frequency error. 612This takes approximately 15 minutes, after which the time and 613frequency are set to nominal values and the 614.Nm 615enters 616normal mode, where the time and frequency are continuously tracked 617relative to the server. 618After one hour the frequency file is 619created and the current frequency offset written to it. 620When the 621.Nm 622is started and the file does exist, the 623.Nm 624frequency is initialized from the file and enters normal mode 625immediately. 626After that the current frequency offset is written to 627the file at hourly intervals. 628.Ss "Operating Modes" 629The 630.Nm 631utility can operate in any of several modes, including 632symmetric active/passive, client/server broadcast/multicast and 633manycast, as described in the 634.Qq Association Management 635page 636(available as part of the HTML documentation 637provided in 638.Pa /usr/share/doc/ntp ) . 639It normally operates continuously while 640monitoring for small changes in frequency and trimming the clock 641for the ultimate precision. 642However, it can operate in a one\-time 643mode where the time is set from an external server and frequency is 644set from a previously recorded frequency file. 645A 646broadcast/multicast or manycast client can discover remote servers, 647compute server\-client propagation delay correction factors and 648configure itself automatically. 649This makes it possible to deploy a 650fleet of workstations without specifying configuration details 651specific to the local environment. 652.Pp 653By default, 654.Nm 655runs in continuous mode where each of 656possibly several external servers is polled at intervals determined 657by an intricate state machine. 658The state machine measures the 659incidental roundtrip delay jitter and oscillator frequency wander 660and determines the best poll interval using a heuristic algorithm. 661Ordinarily, and in most operating environments, the state machine 662will start with 64s intervals and eventually increase in steps to 6631024s. 664A small amount of random variation is introduced in order to 665avoid bunching at the servers. 666In addition, should a server become 667unreachable for some time, the poll interval is increased in steps 668to 1024s in order to reduce network overhead. 669.Pp 670In some cases it may not be practical for 671.Nm 672to run continuously. 673A common workaround has been to run the 674.Xr ntpdate @NTPDATE_MS@ 675or 676.Xr sntp @SNTP_MS@ 677programs from a 678.Xr cron 8 679job at designated 680times. 681However, these programs do not have the crafted signal 682processing, error checking or mitigation algorithms of 683.Nm . 684The 685.Fl q 686option is intended for this purpose. 687Setting this option will cause 688.Nm 689to exit just after 690setting the clock for the first time. 691The procedure for initially 692setting the clock is the same as in continuous mode; most 693applications will probably want to specify the 694.Cm iburst 695keyword with the 696.Ic server 697configuration command. 698With this 699keyword a volley of messages are exchanged to groom the data and 700the clock is set in about 10 s. 701If nothing is heard after a 702couple of minutes, the daemon times out and exits. 703After a suitable 704period of mourning, the 705.Xr ntpdate @NTPDATE_MS@ 706program will be 707retired. 708.Pp 709When kernel support is available to discipline the clock 710frequency, which is the case for stock Solaris, Tru64, Linux and 711.Fx , 712a useful feature is available to discipline the clock 713frequency. 714First, 715.Nm 716is run in continuous mode with 717selected servers in order to measure and record the intrinsic clock 718frequency offset in the frequency file. 719It may take some hours for 720the frequency and offset to settle down. 721Then the 722.Nm 723is 724stopped and run in one\-time mode as required. 725At each startup, the 726frequency is read from the file and initializes the kernel 727frequency. 728.Ss "Poll Interval Control" 729This version of NTP includes an intricate state machine to 730reduce the network load while maintaining a quality of 731synchronization consistent with the observed jitter and wander. 732There are a number of ways to tailor the operation in order enhance 733accuracy by reducing the interval or to reduce network overhead by 734increasing it. 735However, the user is advised to carefully consider 736the consequences of changing the poll adjustment range from the 737default minimum of 64 s to the default maximum of 1,024 s. 738The 739default minimum can be changed with the 740.Ic tinker 741.Cm minpoll 742command to a value not less than 16 s. 743This value is used for all 744configured associations, unless overridden by the 745.Cm minpoll 746option on the configuration command. 747Note that most device drivers 748will not operate properly if the poll interval is less than 64 s 749and that the broadcast server and manycast client associations will 750also use the default, unless overridden. 751.Pp 752In some cases involving dial up or toll services, it may be 753useful to increase the minimum interval to a few tens of minutes 754and maximum interval to a day or so. 755Under normal operation 756conditions, once the clock discipline loop has stabilized the 757interval will be increased in steps from the minimum to the 758maximum. 759However, this assumes the intrinsic clock frequency error 760is small enough for the discipline loop correct it. 761The capture 762range of the loop is 500 PPM at an interval of 64s decreasing by a 763factor of two for each doubling of interval. 764At a minimum of 1,024 765s, for example, the capture range is only 31 PPM. 766If the intrinsic 767error is greater than this, the drift file 768.Pa ntp.drift 769will 770have to be specially tailored to reduce the residual error below 771this limit. 772Once this is done, the drift file is automatically 773updated once per hour and is available to initialize the frequency 774on subsequent daemon restarts. 775.Ss "The huff\-n'\-puff Filter" 776In scenarios where a considerable amount of data are to be 777downloaded or uploaded over telephone modems, timekeeping quality 778can be seriously degraded. 779This occurs because the differential 780delays on the two directions of transmission can be quite large. 781In 782many cases the apparent time errors are so large as to exceed the 783step threshold and a step correction can occur during and after the 784data transfer is in progress. 785.Pp 786The huff\-n'\-puff filter is designed to correct the apparent time 787offset in these cases. 788It depends on knowledge of the propagation 789delay when no other traffic is present. 790In common scenarios this 791occurs during other than work hours. 792The filter maintains a shift 793register that remembers the minimum delay over the most recent 794interval measured usually in hours. 795Under conditions of severe 796delay, the filter corrects the apparent offset using the sign of 797the offset and the difference between the apparent delay and 798minimum delay. 799The name of the filter reflects the negative (huff) 800and positive (puff) correction, which depends on the sign of the 801offset. 802.Pp 803The filter is activated by the 804.Ic tinker 805command and 806.Cm huffpuff 807keyword, as described in 808.Xr ntp.conf 5 . 809.Sh "ENVIRONMENT" 810See \fBOPTION PRESETS\fP for configuration environment variables. 811.Sh FILES 812.Bl -tag -width /etc/ntp.drift -compact 813.It Pa /etc/ntp.conf 814the default name of the configuration file 815.It Pa /etc/ntp.drift 816the default name of the drift file 817.It Pa /etc/ntp.keys 818the default name of the key file 819.El 820.Sh "EXIT STATUS" 821One of the following exit values will be returned: 822.Bl -tag 823.It 0 " (EXIT_SUCCESS)" 824Successful program execution. 825.It 1 " (EXIT_FAILURE)" 826The operation failed or the command syntax was not valid. 827.It 70 " (EX_SOFTWARE)" 828libopts had an internal operational error. Please report 829it to autogen\-users@lists.sourceforge.net. Thank you. 830.El 831.Sh "SEE ALSO" 832.Xr ntp.conf 5 , 833.Xr ntpdate @NTPDATE_MS@ , 834.Xr ntpdc @NTPDC_MS@ , 835.Xr ntpq @NTPQ_MS@ , 836.Xr sntp @SNTP_MS@ 837.Pp 838In addition to the manual pages provided, 839comprehensive documentation is available on the world wide web 840at 841.Li http://www.ntp.org/ . 842A snapshot of this documentation is available in HTML format in 843.Pa /usr/share/doc/ntp . 844.Rs 845.%A David L. Mills 846.%T Network Time Protocol (Version 1) 847.%O RFC1059 848.Re 849.Rs 850.%A David L. Mills 851.%T Network Time Protocol (Version 2) 852.%O RFC1119 853.Re 854.Rs 855.%A David L. Mills 856.%T Network Time Protocol (Version 3) 857.%O RFC1305 858.Re 859.Rs 860.%A David L. Mills 861.%A J. Martin, Ed. 862.%A J. Burbank 863.%A W. Kasch 864.%T Network Time Protocol Version 4: Protocol and Algorithms Specification 865.%O RFC5905 866.Re 867.Rs 868.%A David L. Mills 869.%A B. Haberman, Ed. 870.%T Network Time Protocol Version 4: Autokey Specification 871.%O RFC5906 872.Re 873.Rs 874.%A H. Gerstung 875.%A C. Elliott 876.%A B. Haberman, Ed. 877.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) 878.%O RFC5907 879.Re 880.Rs 881.%A R. Gayraud 882.%A B. Lourdelet 883.%T Network Time Protocol (NTP) Server Option for DHCPv6 884.%O RFC5908 885.Re 886.Sh "AUTHORS" 887The University of Delaware and Network Time Foundation 888.Sh "COPYRIGHT" 889Copyright (C) 1992\-2016 The University of Delaware and Network Time Foundation all rights reserved. 890This program is released under the terms of the NTP license, <http://ntp.org/license>. 891.Sh BUGS 892The 893.Nm 894utility has gotten rather fat. 895While not huge, it has gotten 896larger than might be desirable for an elevated\-priority 897.Nm 898running on a workstation, particularly since many of 899the fancy features which consume the space were designed more with 900a busy primary server, rather than a high stratum workstation in 901mind. 902.Pp 903Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 904.Sh NOTES 905Portions of this document came from FreeBSD. 906.Pp 907This manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP 908option definitions. 909