ntpd.1ntpdmdoc revision 298770
1139749Simp.Dd April 26 2016 265942Sgibbs.Dt NTPD 1ntpdmdoc User Commands 365942Sgibbs.Os 465942Sgibbs.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) 571717Sgibbs.\" 665942Sgibbs.\" It has been AutoGen-ed April 26, 2016 at 08:28:41 PM by AutoGen 5.18.5 765942Sgibbs.\" From the definitions ntpd-opts.def 865942Sgibbs.\" and the template file agmdoc-cmd.tpl 965942Sgibbs.Sh NAME 1065942Sgibbs.Nm ntpd 1165942Sgibbs.Nd NTP daemon program 1295378Sgibbs.Sh SYNOPSIS 1395378Sgibbs.Nm 1495378Sgibbs.\" Mixture of short (flag) options and long options 1595378Sgibbs.Op Fl flags 1695378Sgibbs.Op Fl flag Op Ar value 1795378Sgibbs.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 1895378Sgibbs[ <server1> ... <serverN> ] 1995378Sgibbs.Pp 2095378Sgibbs.Sh DESCRIPTION 2195378SgibbsThe 2265942Sgibbs.Nm 2371717Sgibbsutility is an operating system daemon which sets 2495378Sgibbsand maintains the system time of day in synchronism with Internet 2595378Sgibbsstandard time servers. 2671717SgibbsIt is a complete implementation of the 2795378SgibbsNetwork Time Protocol (NTP) version 4, as defined by RFC\-5905, 2895378Sgibbsbut also retains compatibility with 2995378Sgibbsversion 3, as defined by RFC\-1305, and versions 1 3095378Sgibbsand 2, as defined by RFC\-1059 and RFC\-1119, respectively. 3195378Sgibbs.Pp 3295378SgibbsThe 3365942Sgibbs.Nm 3465942Sgibbsutility does most computations in 64\-bit floating point 3595378Sgibbsarithmetic and does relatively clumsy 64\-bit fixed point operations 3695378Sgibbsonly when necessary to preserve the ultimate precision, about 232 3795378Sgibbspicoseconds. 3895378SgibbsWhile the ultimate precision is not achievable with 3965942Sgibbsordinary workstations and networks of today, it may be required 40123579Sgibbswith future gigahertz CPU clocks and gigabit LANs. 4165942Sgibbs.Pp 4265942SgibbsOrdinarily, 4395378Sgibbs.Nm 4495378Sgibbsreads the 4595378Sgibbs.Xr ntp.conf 5 4695378Sgibbsconfiguration file at startup time in order to determine the 4795378Sgibbssynchronization sources and operating modes. 48123579SgibbsIt is also possible to 49123579Sgibbsspecify a working, although limited, configuration entirely on the 5095378Sgibbscommand line, obviating the need for a configuration file. 5165942SgibbsThis may 5265942Sgibbsbe particularly useful when the local host is to be configured as a 5395378Sgibbsbroadcast/multicast client, with all peers being determined by 5465942Sgibbslistening to broadcasts at run time. 5565942Sgibbs.Pp 5665942SgibbsIf NetInfo support is built into 5765942Sgibbs.Nm , 5865942Sgibbsthen 59107411Sscottl.Nm 60107411Sscottlwill attempt to read its configuration from the 6165942SgibbsNetInfo if the default 62114621Sgibbs.Xr ntp.conf 5 63114621Sgibbsfile cannot be read and no file is 64114621Sgibbsspecified by the 65102669Sgibbs.Fl c 6665942Sgibbsoption. 67132107Sstefanf.Pp 6865942SgibbsVarious internal 6965942Sgibbs.Nm 70115915Sgibbsvariables can be displayed and 7165942Sgibbsconfiguration options altered while the 7265942Sgibbs.Nm 7365942Sgibbsis running 7465942Sgibbsusing the 7565942Sgibbs.Xr ntpq 1ntpqmdoc 7665942Sgibbsand 7765942Sgibbs.Xr ntpdc 1ntpdcmdoc 7865942Sgibbsutility programs. 7965942Sgibbs.Pp 8065942SgibbsWhen 8165942Sgibbs.Nm 8265942Sgibbsstarts it looks at the value of 8365942Sgibbs.Xr umask 2 , 84107411Sscottland if zero 85115915Sgibbs.Nm 86115915Sgibbswill set the 87115915Sgibbs.Xr umask 2 88115915Sgibbsto 022. 89115915Sgibbs.Sh "OPTIONS" 90115915Sgibbs.Bl -tag 91107411Sscottl.It Fl 4 , Fl \-ipv4 92107411SscottlForce IPv4 DNS name resolution. 93107411SscottlThis option must not appear in combination with any of the following options: 94107411Sscottlipv6. 95107411Sscottl.sp 96107411SscottlForce DNS resolution of following host names on the command line 97107411Sscottlto the IPv4 namespace. 98107411Sscottl.It Fl 6 , Fl \-ipv6 99107411SscottlForce IPv6 DNS name resolution. 100107411SscottlThis option must not appear in combination with any of the following options: 101107411Sscottlipv4. 10265942Sgibbs.sp 10365942SgibbsForce DNS resolution of following host names on the command line 10465942Sgibbsto the IPv6 namespace. 10565942Sgibbs.It Fl a , Fl \-authreq 10665942SgibbsRequire crypto authentication. 10765942SgibbsThis option must not appear in combination with any of the following options: 10865942Sgibbsauthnoreq. 10965942Sgibbs.sp 11065942SgibbsRequire cryptographic authentication for broadcast client, 11165942Sgibbsmulticast client and symmetric passive associations. 11265942SgibbsThis is the default. 11365942Sgibbs.It Fl A , Fl \-authnoreq 11465942SgibbsDo not require crypto authentication. 11565942SgibbsThis option must not appear in combination with any of the following options: 11665942Sgibbsauthreq. 11765942Sgibbs.sp 11865942SgibbsDo not require cryptographic authentication for broadcast client, 11965942Sgibbsmulticast client and symmetric passive associations. 12065942SgibbsThis is almost never a good idea. 12165942Sgibbs.It Fl b , Fl \-bcastsync 12265942SgibbsAllow us to sync to broadcast servers. 12365942Sgibbs.sp 12465942Sgibbs.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string 12565942Sgibbsconfiguration file name. 12665942Sgibbs.sp 12795378SgibbsThe name and path of the configuration file, 12865942Sgibbs\fI/etc/ntp.conf\fP 12965942Sgibbsby default. 130102669Sgibbs.It Fl d , Fl \-debug\-level 13165942SgibbsIncrease debug verbosity level. 13274094SgibbsThis option may appear an unlimited number of times. 13374094Sgibbs.sp 13465942Sgibbs.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 13579874SgibbsSet the debug verbosity level. 136102669SgibbsThis option may appear an unlimited number of times. 13765942SgibbsThis option takes an integer number as its argument. 13865942Sgibbs.sp 13965942Sgibbs.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string 14095378Sgibbsfrequency drift file name. 14165942Sgibbs.sp 14265942SgibbsThe name and path of the frequency file, 14365942Sgibbs\fI/etc/ntp.drift\fP 14495378Sgibbsby default. 14595378SgibbsThis is the same operation as the 14695378Sgibbs\fBdriftfile\fP \fIdriftfile\fP 14795378Sgibbsconfiguration specification in the 14895378Sgibbs\fI/etc/ntp.conf\fP 14995378Sgibbsfile. 15095378Sgibbs.It Fl g , Fl \-panicgate 15195378SgibbsAllow the first adjustment to be Big. 15279874SgibbsThis option may appear an unlimited number of times. 15379874Sgibbs.sp 154114621SgibbsNormally, 155114621Sgibbs\fBntpd\fP 15665942Sgibbsexits 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, 157114621Sgibbs\fBntpd\fP 158114621Sgibbswill exit with a message to the system log. This option can be used with the 159114621Sgibbs\fB\-q\fP 160114621Sgibbsand 161115917Sgibbs\fB\-x\fP 16265942Sgibbsoptions. 16365942SgibbsSee the 16465942Sgibbs\fBtinker\fP 16574094Sgibbsconfiguration file directive for other options. 16674094Sgibbs.It Fl G , Fl \-force\-step\-once 16774094SgibbsStep any initial offset correction.. 16874094Sgibbs.sp 16974094SgibbsNormally, 17074094Sgibbs\fBntpd\fP 17174094Sgibbssteps the time if the time offset exceeds the step threshold, 17274094Sgibbswhich is 128 ms by default, and otherwise slews the time. 17374094SgibbsThis option forces the initial offset correction to be stepped, 17474094Sgibbsso the highest time accuracy can be achieved quickly. 17574094SgibbsHowever, this may also cause the time to be stepped back 17674094Sgibbsso this option must not be used if 177123579Sgibbsapplications requiring monotonic time are running. 17874094SgibbsSee the \fBtinker\fP configuration file directive for other options. 17974094Sgibbs.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string 18074094SgibbsJail directory. 18174094Sgibbs.sp 18274094SgibbsChroot the server to the directory 18374094Sgibbs\fIjaildir\fP 18479874Sgibbs. 18565942SgibbsThis option also implies that the server attempts to drop root privileges at startup. 18665942SgibbsYou may need to also specify a 18765942Sgibbs\fB\-u\fP 18865942Sgibbsoption. 18965942SgibbsThis option is only available if the OS supports adjusting the clock 19065942Sgibbswithout full root privileges. 19165942SgibbsThis option is supported under NetBSD (configure with 19265942Sgibbs\fB\-\-enable\-clockctl\fP) or Linux (configure with 19365942Sgibbs\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 19465942Sgibbs.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface 19565942SgibbsListen on an interface name or address. 19665942SgibbsThis option may appear an unlimited number of times. 19774094Sgibbs.sp 19865942SgibbsOpen the network address given, or all the addresses associated with the 19965942Sgibbsgiven interface name. This option may appear multiple times. This option 20065942Sgibbsalso implies not opening other addresses, except wildcard and localhost. 20165942SgibbsThis option is deprecated. Please consider using the configuration file 20265942Sgibbs\fBinterface\fP command, which is more versatile. 20365942Sgibbs.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string 20465942Sgibbspath to symmetric keys. 20565942Sgibbs.sp 20665942SgibbsSpecify the name and path of the symmetric key file. 20765942Sgibbs\fI/etc/ntp.keys\fP 20865942Sgibbsis the default. 20965942SgibbsThis is the same operation as the 21065942Sgibbs\fBkeys\fP \fIkeyfile\fP 21165942Sgibbsconfiguration file directive. 21265942Sgibbs.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string 21365942Sgibbspath to the log file. 21465942Sgibbs.sp 215102669SgibbsSpecify the name and path of the log file. 216102669SgibbsThe default is the system log file. 21765942SgibbsThis is the same operation as the 21865942Sgibbs\fBlogfile\fP \fIlogfile\fP 21965942Sgibbsconfiguration file directive. 22065942Sgibbs.It Fl L , Fl \-novirtualips 221102669SgibbsDo not listen to virtual interfaces. 22265942Sgibbs.sp 22365942SgibbsDo not listen to virtual interfaces, defined as those with 22465942Sgibbsnames containing a colon. This option is deprecated. Please 22565942Sgibbsconsider using the configuration file \fBinterface\fP command, which 22665942Sgibbsis more versatile. 227102669Sgibbs.It Fl M , Fl \-modifymmtimer 228102669SgibbsModify Multimedia Timer (Windows only). 229102669Sgibbs.sp 230102669SgibbsSet the Windows Multimedia Timer to highest resolution. This 23165942Sgibbsensures the resolution does not change while ntpd is running, 23265942Sgibbsavoiding timekeeping glitches associated with changes. 23365942Sgibbs.It Fl n , Fl \-nofork 23465942SgibbsDo not fork. 23565942SgibbsThis option must not appear in combination with any of the following options: 23665942Sgibbswait\-sync. 23765942Sgibbs.sp 23865942Sgibbs.It Fl N , Fl \-nice 23965942SgibbsRun at high priority. 24065942Sgibbs.sp 24165942SgibbsTo the extent permitted by the operating system, run 242114621Sgibbs\fBntpd\fP 243114621Sgibbsat the highest priority. 244114621Sgibbs.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string 24565942Sgibbspath to the PID file. 24665942Sgibbs.sp 24765942SgibbsSpecify the name and path of the file used to record 24865942Sgibbs\fBntpd\fP's 24965942Sgibbsprocess ID. 25065942SgibbsThis is the same operation as the 25165942Sgibbs\fBpidfile\fP \fIpidfile\fP 252102669Sgibbsconfiguration file directive. 253102669Sgibbs.It Fl P Ar number , Fl \-priority Ns = Ns Ar number 254102669SgibbsProcess priority. 255102669SgibbsThis option takes an integer number as its argument. 256168807Sscottl.sp 25765942SgibbsTo the extent permitted by the operating system, run 25871390Sgibbs\fBntpd\fP 25971390Sgibbsat the specified 26071390Sgibbs\fBsched_setscheduler(SCHED_FIFO)\fP 26171390Sgibbspriority. 26271390Sgibbs.It Fl q , Fl \-quit 26365942SgibbsSet the time and quit. 26465942SgibbsThis option must not appear in combination with any of the following options: 26565942Sgibbssaveconfigquit, wait\-sync. 26665942Sgibbs.sp 267168807Sscottl\fBntpd\fP 26874972Sgibbswill not daemonize and will exit after the clock is first 26965942Sgibbssynchronized. This behavior mimics that of the 27065942Sgibbs\fBntpdate\fP 27165942Sgibbsprogram, which will soon be replaced with a shell script. 272114621SgibbsThe 273114621Sgibbs\fB\-g\fP 274114621Sgibbsand 275114621Sgibbs\fB\-x\fP 276114621Sgibbsoptions can be used with this option. 277114621SgibbsNote: The kernel time discipline is disabled with this option. 278114621Sgibbs.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string 279114621SgibbsBroadcast/propagation delay. 280114621Sgibbs.sp 281114621SgibbsSpecify 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. 282114621Sgibbs.It Fl \-saveconfigquit Ns = Ns Ar string 283114621SgibbsSave parsed configuration and quit. 284114621SgibbsThis option must not appear in combination with any of the following options: 285114621Sgibbsquit, wait\-sync. 286114621Sgibbs.sp 287114621SgibbsCause \fBntpd\fP to parse its startup configuration file and save an 288114621Sgibbsequivalent to the given filename and exit. This option was 289114621Sgibbsdesigned for automated testing. 290114621Sgibbs.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string 291114621SgibbsStatistics file location. 292114621Sgibbs.sp 293114621SgibbsSpecify the directory path for files created by the statistics facility. 29465942SgibbsThis is the same operation as the 29565942Sgibbs\fBstatsdir\fP \fIstatsdir\fP 29665942Sgibbsconfiguration file directive. 297102669Sgibbs.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey 29865942SgibbsTrusted key number. 29965942SgibbsThis option may appear an unlimited number of times. 300102669Sgibbs.sp 301102669SgibbsAdd the specified key number to the trusted key list. 302102669Sgibbs.It Fl u Ar string , Fl \-user Ns = Ns Ar string 303102669SgibbsRun as userid (or userid:groupid). 30465942Sgibbs.sp 30565942SgibbsSpecify a user, and optionally a group, to switch to. 30665942SgibbsThis option is only available if the OS supports adjusting the clock 30765942Sgibbswithout full root privileges. 30865942SgibbsThis option is supported under NetBSD (configure with 30965942Sgibbs\fB\-\-enable\-clockctl\fP) or Linux (configure with 31065942Sgibbs\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 31165942Sgibbs.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number 31265942Sgibbsinterval in seconds between scans for new or dropped interfaces. 31365942SgibbsThis option takes an integer number as its argument. 31465942Sgibbs.sp 31565942SgibbsGive the time in seconds between two scans for new or dropped interfaces. 316102669SgibbsFor systems with routing socket support the scans will be performed shortly after the interface change 31765942Sgibbshas been detected by the system. 31865942SgibbsUse 0 to disable scanning. 60 seconds is the minimum time between scans. 31965942Sgibbs.It Fl \-var Ns = Ns Ar nvar 320104231Sgibbsmake ARG an ntp variable (RW). 321114621SgibbsThis option may appear an unlimited number of times. 32265942Sgibbs.sp 32365942Sgibbs.It Fl \-dvar Ns = Ns Ar ndvar 32465942Sgibbsmake ARG an ntp variable (RW|DEF). 325102669SgibbsThis option may appear an unlimited number of times. 32665942Sgibbs.sp 32765942Sgibbs.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number 32865942SgibbsSeconds to wait for first clock sync. 32965942SgibbsThis option must not appear in combination with any of the following options: 33065942Sgibbsnofork, quit, saveconfigquit. 33165942SgibbsThis option takes an integer number as its argument. 33265942Sgibbs.sp 33365942SgibbsIf greater than zero, alters \fBntpd\fP's behavior when forking to 33465942Sgibbsdaemonize. Instead of exiting with status 0 immediately after 33565942Sgibbsthe fork, the parent waits up to the specified number of 33665942Sgibbsseconds for the child to first synchronize the clock. The exit 33765942Sgibbsstatus is zero (success) if the clock was synchronized, 33865942Sgibbsotherwise it is \fBETIMEDOUT\fP. 33965942SgibbsThis provides the option for a script starting \fBntpd\fP to easily 34065942Sgibbswait for the first set of the clock before proceeding. 34165942Sgibbs.It Fl x , Fl \-slew 34265942SgibbsSlew up to 600 seconds. 343102669Sgibbs.sp 344102669SgibbsNormally, 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. 34565942SgibbsThis option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 34665942SgibbsNote: 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. 347102669SgibbsThus, an adjustment as much as 600 s will take almost 14 days to complete. 34865942SgibbsThis option can be used with the 34965942Sgibbs\fB\-g\fP 350102669Sgibbsand 351102669Sgibbs\fB\-q\fP 352102669Sgibbsoptions. 353102669SgibbsSee the 35465942Sgibbs\fBtinker\fP 355102669Sgibbsconfiguration file directive for other options. 35665942SgibbsNote: The kernel time discipline is disabled with this option. 357102669Sgibbs.It Fl \-usepcc 35865942SgibbsUse CPU cycle counter (Windows only). 35965942Sgibbs.sp 36065942SgibbsAttempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 36165942SgibbsThe CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 36265942Sgibbsthey have the same frequency, the CPU counter (RDTSC on x86) is 36365942Sgibbsused directly, saving the overhead of a system call. 364102669Sgibbs.It Fl \-pccfreq Ns = Ns Ar string 36565942SgibbsForce CPU cycle counter use (Windows only). 36665942Sgibbs.sp 367102669SgibbsForce substitution the CPU counter for \fBQueryPerformanceCounter\fP. 36865942SgibbsThe CPU counter (RDTSC on x86) is used unconditionally with the 369102669Sgibbsgiven frequency (in Hz). 37065942Sgibbs.It Fl m , Fl \-mdns 37165942SgibbsRegister with mDNS as a NTP server. 372102669Sgibbs.sp 37365942SgibbsRegisters as an NTP server with the local mDNS server which allows 37465942Sgibbsthe server to be discovered via mDNS client lookup. 37565942Sgibbs.It Fl \&? , Fl \-help 37665942SgibbsDisplay usage information and exit. 377102669Sgibbs.It Fl \&! , Fl \-more\-help 37865942SgibbsPass the extended usage information through a pager. 37965942Sgibbs.It Fl \-version Op Brq Ar v|c|n 380102669SgibbsOutput version of program and exit. The default mode is `v', a simple 38165942Sgibbsversion. The `c' mode will print copyright information and `n' will 38265942Sgibbsprint the full copyright notice. 38365942Sgibbs.El 38479874Sgibbs.Sh "OPTION PRESETS" 38565942SgibbsAny option that is not marked as \fInot presettable\fP may be preset 38665942Sgibbsby loading values from environment variables named: 38765942Sgibbs.nf 38879874Sgibbs \fBNTPD_<option\-name>\fP or \fBNTPD\fP 38979874Sgibbs.fi 39065942Sgibbs.ad 39165942Sgibbs.Sh USAGE 39265942Sgibbs.Ss "How NTP Operates" 39365942SgibbsThe 39479874Sgibbs.Nm 39565942Sgibbsutility operates by exchanging messages with 39665942Sgibbsone or more configured servers over a range of designated poll intervals. 39765942SgibbsWhen 39879874Sgibbsstarted, whether for the first or subsequent times, the program 39979874Sgibbsrequires several exchanges from the majority of these servers so 40065942Sgibbsthe signal processing and mitigation algorithms can accumulate and 40165942Sgibbsgroom the data and set the clock. 40265942SgibbsIn order to protect the network 40365942Sgibbsfrom bursts, the initial poll interval for each server is delayed 40479874Sgibbsan interval randomized over a few seconds. 40565942SgibbsAt the default initial poll 40679874Sgibbsinterval of 64s, several minutes can elapse before the clock is 40779874Sgibbsset. 40879874SgibbsThis initial delay to set the clock 40979874Sgibbscan be safely and dramatically reduced using the 41079874Sgibbs.Cm iburst 41179874Sgibbskeyword with the 412114621Sgibbs.Ic server 41365942Sgibbsconfiguration 41465942Sgibbscommand, as described in 415.Xr ntp.conf 5 . 416.Pp 417Most operating systems and hardware of today incorporate a 418time\-of\-year (TOY) chip to maintain the time during periods when 419the power is off. 420When the machine is booted, the chip is used to 421initialize the operating system time. 422After the machine has 423synchronized to a NTP server, the operating system corrects the 424chip from time to time. 425In the default case, if 426.Nm 427detects that the time on the host 428is more than 1000s from the server time, 429.Nm 430assumes something must be terribly wrong and the only 431reliable action is for the operator to intervene and set the clock 432by hand. 433(Reasons for this include there is no TOY chip, 434or its battery is dead, or that the TOY chip is just of poor quality.) 435This causes 436.Nm 437to exit with a panic message to 438the system log. 439The 440.Fl g 441option overrides this check and the 442clock will be set to the server time regardless of the chip time 443(up to 68 years in the past or future \(em 444this is a limitation of the NTPv4 protocol). 445However, and to protect against broken hardware, such as when the 446CMOS battery fails or the clock counter becomes defective, once the 447clock has been set an error greater than 1000s will cause 448.Nm 449to exit anyway. 450.Pp 451Under ordinary conditions, 452.Nm 453adjusts the clock in 454small steps so that the timescale is effectively continuous and 455without discontinuities. 456Under conditions of extreme network 457congestion, the roundtrip delay jitter can exceed three seconds and 458the synchronization distance, which is equal to one\-half the 459roundtrip delay plus error budget terms, can become very large. 460The 461.Nm 462algorithms discard sample offsets exceeding 128 ms, 463unless the interval during which no sample offset is less than 128 464ms exceeds 900s. 465The first sample after that, no matter what the 466offset, steps the clock to the indicated time. 467In practice this 468reduces the false alarm rate where the clock is stepped in error to 469a vanishingly low incidence. 470.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 1ntpdatemdoc 535or 536.Xr sntp 1sntpmdoc 537to get the system clock close to correct before starting 538.Xr ntpd 1ntpdmdoc , 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 1sntpmdoc 547if you really need to set the clock before starting 548.Nm . 549.Pp 550There is a way to start 551.Xr ntpd 1ntpdmdoc 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 1ntpdmdoc 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 1ntpdmdoc 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 1ntpdmdoc 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 1ntpdatemdoc 675or 676.Xr sntp 1sntpmdoc 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 1ntpdatemdoc 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 1ntpdatemdoc , 834.Xr ntpdc 1ntpdcmdoc , 835.Xr ntpq 1ntpqmdoc , 836.Xr sntp 1sntpmdoc 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