ntpd.mdoc.in revision 330567
1193323Sed.Dd February 27 2018 2193323Sed.Dt NTPD @NTPD_MS@ User Commands 3193323Sed.Os 4193323Sed.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) 5193323Sed.\" 6193323Sed.\" It has been AutoGen-ed February 27, 2018 at 05:14:47 PM by AutoGen 5.18.5 7193323Sed.\" From the definitions ntpd-opts.def 8193323Sed.\" and the template file agmdoc-cmd.tpl 9193323Sed.Sh NAME 10193323Sed.Nm ntpd 11193323Sed.Nd NTP daemon program 12193323Sed.Sh SYNOPSIS 13193323Sed.Nm 14193323Sed.\" Mixture of short (flag) options and long options 15193323Sed.Op Fl flags 16193323Sed.Op Fl flag Op Ar value 17193323Sed.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 18193323Sed[ <server1> ... <serverN> ] 19193323Sed.Pp 20193323Sed.Sh DESCRIPTION 21193323SedThe 22194612Sed.Nm 23193323Sedutility is an operating system daemon which sets 24193323Sedand maintains the system time of day in synchronism with Internet 25193323Sedstandard time servers. 26193323SedIt is a complete implementation of the 27193323SedNetwork Time Protocol (NTP) version 4, as defined by RFC\-5905, 28193323Sedbut also retains compatibility with 29193323Sedversion 3, as defined by RFC\-1305, and versions 1 30193323Sedand 2, as defined by RFC\-1059 and RFC\-1119, respectively. 31193323Sed.Pp 32193323SedThe 33193323Sed.Nm 34193323Sedutility does most computations in 64\-bit floating point 35193323Sedarithmetic and does relatively clumsy 64\-bit fixed point operations 36193323Sedonly when necessary to preserve the ultimate precision, about 232 37193323Sedpicoseconds. 38193323SedWhile the ultimate precision is not achievable with 39193323Sedordinary workstations and networks of today, it may be required 40193323Sedwith future gigahertz CPU clocks and gigabit LANs. 41193323Sed.Pp 42193323SedOrdinarily, 43193323Sed.Nm 44193323Sedreads the 45193323Sed.Xr ntp.conf 5 46193323Sedconfiguration file at startup time in order to determine the 47193323Sedsynchronization sources and operating modes. 48193323SedIt is also possible to 49193323Sedspecify a working, although limited, configuration entirely on the 50193323Sedcommand line, obviating the need for a configuration file. 51193323SedThis may 52193323Sedbe particularly useful when the local host is to be configured as a 53193323Sedbroadcast/multicast client, with all peers being determined by 54193323Sedlistening to broadcasts at run time. 55193323Sed.Pp 56193323SedIf NetInfo support is built into 57193323Sed.Nm , 58193323Sedthen 59193323Sed.Nm 60193323Sedwill attempt to read its configuration from the 61193323SedNetInfo if the default 62193323Sed.Xr ntp.conf 5 63193323Sedfile cannot be read and no file is 64193323Sedspecified by the 65193323Sed.Fl c 66193323Sedoption. 67193323Sed.Pp 68193323SedVarious internal 69193323Sed.Nm 70193323Sedvariables can be displayed and 71193323Sedconfiguration options altered while the 72193323Sed.Nm 73193323Sedis running 74193323Sedusing the 75193323Sed.Xr ntpq @NTPQ_MS@ 76193323Sedand 77193323Sed.Xr ntpdc @NTPDC_MS@ 78193323Sedutility programs. 79193323Sed.Pp 80193323SedWhen 81193323Sed.Nm 82193323Sedstarts it looks at the value of 83193323Sed.Xr umask 2 , 84193323Sedand if zero 85193323Sed.Nm 86193323Sedwill set the 87193323Sed.Xr umask 2 88193323Sedto 022. 89193323Sed.Sh "OPTIONS" 90193323Sed.Bl -tag 91193323Sed.It Fl 4 , Fl \-ipv4 92193323SedForce IPv4 DNS name resolution. 93193323SedThis option must not appear in combination with any of the following options: 94193323Sedipv6. 95193323Sed.sp 96193323SedForce DNS resolution of following host names on the command line 97193323Sedto the IPv4 namespace. 98193323Sed.It Fl 6 , Fl \-ipv6 99193323SedForce IPv6 DNS name resolution. 100193323SedThis option must not appear in combination with any of the following options: 101193323Sedipv4. 102193323Sed.sp 103193323SedForce DNS resolution of following host names on the command line 104193323Sedto the IPv6 namespace. 105193323Sed.It Fl a , Fl \-authreq 106193323SedRequire crypto authentication. 107193323SedThis option must not appear in combination with any of the following options: 108193323Sedauthnoreq. 109193323Sed.sp 110193323SedRequire cryptographic authentication for broadcast client, 111193323Sedmulticast client and symmetric passive associations. 112193323SedThis is the default. 113193323Sed.It Fl A , Fl \-authnoreq 114193323SedDo not require crypto authentication. 115193323SedThis option must not appear in combination with any of the following options: 116193323Sedauthreq. 117193323Sed.sp 118193323SedDo not require cryptographic authentication for broadcast client, 119193323Sedmulticast client and symmetric passive associations. 120193323SedThis is almost never a good idea. 121193323Sed.It Fl b , Fl \-bcastsync 122193323SedAllow us to sync to broadcast servers. 123193323Sed.sp 124193323Sed.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string 125193323Sedconfiguration file name. 126193323Sed.sp 127193323SedThe name and path of the configuration file, 128193323Sed\fI/etc/ntp.conf\fP 129193323Sedby default. 130193323Sed.It Fl d , Fl \-debug\-level 131193323SedIncrease debug verbosity level. 132193323SedThis option may appear an unlimited number of times. 133193323Sed.sp 134193323Sed.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 135193323SedSet the debug verbosity level. 136193323SedThis option may appear an unlimited number of times. 137193323SedThis option takes an integer number as its argument. 138193323Sed.sp 139193323Sed.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string 140193323Sedfrequency drift file name. 141193323Sed.sp 142193323SedThe name and path of the frequency file, 143193323Sed\fI/etc/ntp.drift\fP 144193323Sedby default. 145193323SedThis is the same operation as the 146193323Sed\fBdriftfile\fP \fIdriftfile\fP 147193323Sedconfiguration specification in the 148193323Sed\fI/etc/ntp.conf\fP 149193323Sedfile. 150193323Sed.It Fl g , Fl \-panicgate 151193323SedAllow the first adjustment to be Big. 152193323SedThis option may appear an unlimited number of times. 153193323Sed.sp 154193323SedNormally, 155193323Sed\fBntpd\fP 156193323Sedexits 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, 157193323Sed\fBntpd\fP 158193323Sedwill exit with a message to the system log. This option can be used with the 159193323Sed\fB\-q\fP 160193323Sedand 161193323Sed\fB\-x\fP 162193323Sedoptions. 163193323SedSee the 164193323Sed\fBtinker\fP 165193323Sedconfiguration file directive for other options. 166193323Sed.It Fl G , Fl \-force\-step\-once 167193323SedStep any initial offset correction.. 168193323Sed.sp 169193323SedNormally, 170193323Sed\fBntpd\fP 171193323Sedsteps the time if the time offset exceeds the step threshold, 172193323Sedwhich is 128 ms by default, and otherwise slews the time. 173193323SedThis option forces the initial offset correction to be stepped, 174193323Sedso the highest time accuracy can be achieved quickly. 175193323SedHowever, this may also cause the time to be stepped back 176193323Sedso this option must not be used if 177193323Sedapplications requiring monotonic time are running. 178193323SedSee the \fBtinker\fP configuration file directive for other options. 179193323Sed.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string 180193323SedJail directory. 181193323Sed.sp 182193323SedChroot the server to the directory 183193323Sed\fIjaildir\fP 184193323Sed. 185193323SedThis option also implies that the server attempts to drop root privileges at startup. 186193323SedYou may need to also specify a 187193323Sed\fB\-u\fP 188193323Sedoption. 189193323SedThis option is only available if the OS supports adjusting the clock 190193323Sedwithout full root privileges. 191193323SedThis option is supported under NetBSD (configure with 192193323Sed\fB\-\-enable\-clockctl\fP) or Linux (configure with 193193323Sed\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 194193323Sed.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface 195193323SedListen on an interface name or address. 196193323SedThis option may appear an unlimited number of times. 197193323Sed.sp 198193323SedOpen the network address given, or all the addresses associated with the 199193323Sedgiven interface name. This option may appear multiple times. This option 200193323Sedalso implies not opening other addresses, except wildcard and localhost. 201193323SedThis option is deprecated. Please consider using the configuration file 202193323Sed\fBinterface\fP command, which is more versatile. 203193323Sed.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string 204193323Sedpath to symmetric keys. 205193323Sed.sp 206193323SedSpecify the name and path of the symmetric key file. 207193323Sed\fI/etc/ntp.keys\fP 208193323Sedis the default. 209193323SedThis is the same operation as the 210193323Sed\fBkeys\fP \fIkeyfile\fP 211193323Sedconfiguration file directive. 212193323Sed.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string 213193323Sedpath to the log file. 214193323Sed.sp 215193323SedSpecify the name and path of the log file. 216193323SedThe default is the system log file. 217193323SedThis is the same operation as the 218193323Sed\fBlogfile\fP \fIlogfile\fP 219193323Sedconfiguration file directive. 220193323Sed.It Fl L , Fl \-novirtualips 221193323SedDo not listen to virtual interfaces. 222193323Sed.sp 223193323SedDo not listen to virtual interfaces, defined as those with 224193323Sednames containing a colon. This option is deprecated. Please 225193323Sedconsider using the configuration file \fBinterface\fP command, which 226193323Sedis more versatile. 227193323Sed.It Fl M , Fl \-modifymmtimer 228193323SedModify Multimedia Timer (Windows only). 229193323Sed.sp 230193323SedSet the Windows Multimedia Timer to highest resolution. This 231193323Sedensures the resolution does not change while ntpd is running, 232193323Sedavoiding timekeeping glitches associated with changes. 233193323Sed.It Fl n , Fl \-nofork 234193323SedDo not fork. 235193323SedThis option must not appear in combination with any of the following options: 236193323Sedwait\-sync. 237193323Sed.sp 238193323Sed.It Fl N , Fl \-nice 239193323SedRun at high priority. 240193323Sed.sp 241193323SedTo the extent permitted by the operating system, run 242193323Sed\fBntpd\fP 243193323Sedat the highest priority. 244193323Sed.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string 245193323Sedpath to the PID file. 246193323Sed.sp 247193323SedSpecify the name and path of the file used to record 248193323Sed\fBntpd\fP's 249193323Sedprocess ID. 250193323SedThis is the same operation as the 251193323Sed\fBpidfile\fP \fIpidfile\fP 252193323Sedconfiguration file directive. 253193323Sed.It Fl P Ar number , Fl \-priority Ns = Ns Ar number 254193323SedProcess priority. 255193323SedThis option takes an integer number as its argument. 256193323Sed.sp 257193323SedTo the extent permitted by the operating system, run 258193323Sed\fBntpd\fP 259193323Sedat the specified 260193323Sed\fBsched_setscheduler(SCHED_FIFO)\fP 261193323Sedpriority. 262193323Sed.It Fl q , Fl \-quit 263193323SedSet the time and quit. 264193323SedThis option must not appear in combination with any of the following options: 265193323Sedsaveconfigquit, wait\-sync. 266193323Sed.sp 267193323Sed\fBntpd\fP 268193323Sedwill not daemonize and will exit after the clock is first 269193323Sedsynchronized. This behavior mimics that of the 270193323Sed\fBntpdate\fP 271193323Sedprogram, which will soon be replaced with a shell script. 272193323SedThe 273193323Sed\fB\-g\fP 274193323Sedand 275193323Sed\fB\-x\fP 276193323Sedoptions can be used with this option. 277193323SedNote: The kernel time discipline is disabled with this option. 278193323Sed.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string 279193323SedBroadcast/propagation delay. 280193323Sed.sp 281193323SedSpecify 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. 282193323Sed.It Fl \-saveconfigquit Ns = Ns Ar string 283193323SedSave parsed configuration and quit. 284193323SedThis option must not appear in combination with any of the following options: 285193323Sedquit, wait\-sync. 286193323Sed.sp 287193323SedCause \fBntpd\fP to parse its startup configuration file and save an 288193323Sedequivalent to the given filename and exit. This option was 289193323Seddesigned for automated testing. 290193323Sed.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string 291193323SedStatistics file location. 292193323Sed.sp 293193323SedSpecify the directory path for files created by the statistics facility. 294193323SedThis is the same operation as the 295193323Sed\fBstatsdir\fP \fIstatsdir\fP 296193323Sedconfiguration file directive. 297193323Sed.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey 298193323SedTrusted key number. 299193323SedThis option may appear an unlimited number of times. 300193323Sed.sp 301193323SedAdd the specified key number to the trusted key list. 302193323Sed.It Fl u Ar string , Fl \-user Ns = Ns Ar string 303193323SedRun as userid (or userid:groupid). 304193323Sed.sp 305193323SedSpecify a user, and optionally a group, to switch to. 306193323SedThis option is only available if the OS supports adjusting the clock 307193323Sedwithout full root privileges. 308193323SedThis option is supported under NetBSD (configure with 309194612Sed\fB\-\-enable\-clockctl\fP) or Linux (configure with 310193323Sed\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 311194612Sed.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number 312193323Sedinterval in seconds between scans for new or dropped interfaces. 313193323SedThis option takes an integer number as its argument. 314193323Sed.sp 315193323SedGive the time in seconds between two scans for new or dropped interfaces. 316193323SedFor systems with routing socket support the scans will be performed shortly after the interface change 317193323Sedhas been detected by the system. 318193323SedUse 0 to disable scanning. 60 seconds is the minimum time between scans. 319193323Sed.It Fl \-var Ns = Ns Ar nvar 320193323Sedmake ARG an ntp variable (RW). 321193323SedThis option may appear an unlimited number of times. 322193323Sed.sp 323193323Sed.It Fl \-dvar Ns = Ns Ar ndvar 324193323Sedmake ARG an ntp variable (RW|DEF). 325193323SedThis option may appear an unlimited number of times. 326193323Sed.sp 327193323Sed.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number 328193323SedSeconds to wait for first clock sync. 329193323SedThis option must not appear in combination with any of the following options: 330193323Sednofork, quit, saveconfigquit. 331193323SedThis option takes an integer number as its argument. 332193323Sed.sp 333193323SedIf greater than zero, alters \fBntpd\fP's behavior when forking to 334193323Seddaemonize. Instead of exiting with status 0 immediately after 335193323Sedthe fork, the parent waits up to the specified number of 336193323Sedseconds for the child to first synchronize the clock. The exit 337193323Sedstatus is zero (success) if the clock was synchronized, 338193323Sedotherwise it is \fBETIMEDOUT\fP. 339193323SedThis provides the option for a script starting \fBntpd\fP to easily 340193323Sedwait for the first set of the clock before proceeding. 341193323Sed.It Fl x , Fl \-slew 342193323SedSlew up to 600 seconds. 343193323Sed.sp 344193323SedNormally, 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. 345193323SedThis option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 346193323SedNote: 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. 347193323SedThus, an adjustment as much as 600 s will take almost 14 days to complete. 348193323SedThis option can be used with the 349193323Sed\fB\-g\fP 350193323Sedand 351193323Sed\fB\-q\fP 352193323Sedoptions. 353193323SedSee the 354193323Sed\fBtinker\fP 355193323Sedconfiguration file directive for other options. 356193323SedNote: The kernel time discipline is disabled with this option. 357194612Sed.It Fl \-usepcc 358193323SedUse CPU cycle counter (Windows only). 359194612Sed.sp 360193323SedAttempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 361193323SedThe CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 362193323Sedthey have the same frequency, the CPU counter (RDTSC on x86) is 363193323Sedused directly, saving the overhead of a system call. 364193323Sed.It Fl \-pccfreq Ns = Ns Ar string 365193323SedForce CPU cycle counter use (Windows only). 366193323Sed.sp 367193323SedForce substitution the CPU counter for \fBQueryPerformanceCounter\fP. 368193323SedThe CPU counter (RDTSC on x86) is used unconditionally with the 369193323Sedgiven frequency (in Hz). 370193323Sed.It Fl m , Fl \-mdns 371193323SedRegister with mDNS as a NTP server. 372193323Sed.sp 373193323SedRegisters as an NTP server with the local mDNS server which allows 374193323Sedthe server to be discovered via mDNS client lookup. 375193323Sed.It Fl \&? , Fl \-help 376195098SedDisplay usage information and exit. 377195098Sed.It Fl \&! , Fl \-more\-help 378194612SedPass the extended usage information through a pager. 379193323Sed.It Fl \-version Op Brq Ar v|c|n 380193323SedOutput version of program and exit. The default mode is `v', a simple 381193323Sedversion. The `c' mode will print copyright information and `n' will 382193323Sedprint the full copyright notice. 383193323Sed.El 384193323Sed.Sh "OPTION PRESETS" 385193323SedAny option that is not marked as \fInot presettable\fP may be preset 386193323Sedby loading values from environment variables named: 387193323Sed.nf 388193323Sed \fBNTPD_<option\-name>\fP or \fBNTPD\fP 389193323Sed.fi 390193323Sed.ad 391193323Sed.Sh USAGE 392193323Sed.Ss "How NTP Operates" 393193323SedThe 394193323Sed.Nm 395193323Sedutility operates by exchanging messages with 396193323Sedone or more configured servers over a range of designated poll intervals. 397193323SedWhen 398193323Sedstarted, whether for the first or subsequent times, the program 399193323Sedrequires several exchanges from the majority of these servers so 400193323Sedthe signal processing and mitigation algorithms can accumulate and 401193323Sedgroom the data and set the clock. 402193323SedIn order to protect the network 403193323Sedfrom bursts, the initial poll interval for each server is delayed 404193323Sedan interval randomized over a few seconds. 405193323SedAt the default initial poll 406193323Sedinterval of 64s, several minutes can elapse before the clock is 407193323Sedset. 408193323SedThis initial delay to set the clock 409193323Sedcan be safely and dramatically reduced using the 410193323Sed.Cm iburst 411193323Sedkeyword with the 412193323Sed.Ic server 413193323Sedconfiguration 414193323Sedcommand, as described in 415193323Sed.Xr ntp.conf 5 . 416193323Sed.Pp 417193323SedMost operating systems and hardware of today incorporate a 418193323Sedtime\-of\-year (TOY) chip to maintain the time during periods when 419193323Sedthe power is off. 420193323SedWhen the machine is booted, the chip is used to 421193323Sedinitialize the operating system time. 422193323SedAfter the machine has 423193323Sedsynchronized to a NTP server, the operating system corrects the 424193323Sedchip from time to time. 425193323SedIn the default case, if 426193323Sed.Nm 427193323Seddetects that the time on the host 428193323Sedis more than 1000s from the server time, 429193323Sed.Nm 430194612Sedassumes something must be terribly wrong and the only 431194612Sedreliable action is for the operator to intervene and set the clock 432193323Sedby hand. 433193323Sed(Reasons for this include there is no TOY chip, 434193323Sedor its battery is dead, or that the TOY chip is just of poor quality.) 435193323SedThis causes 436193323Sed.Nm 437193323Sedto exit with a panic message to 438193323Sedthe system log. 439193323SedThe 440193323Sed.Fl g 441193323Sedoption overrides this check and the 442193323Sedclock will be set to the server time regardless of the chip time 443193323Sed(up to 68 years in the past or future \(em 444193323Sedthis is a limitation of the NTPv4 protocol). 445193323SedHowever, and to protect against broken hardware, such as when the 446193323SedCMOS battery fails or the clock counter becomes defective, once the 447193323Sedclock has been set an error greater than 1000s will cause 448193323Sed.Nm 449193323Sedto exit anyway. 450193323Sed.Pp 451193323SedUnder ordinary conditions, 452193323Sed.Nm 453193323Sedadjusts the clock in 454193323Sedsmall steps so that the timescale is effectively continuous and 455193323Sedwithout discontinuities. 456193323SedUnder conditions of extreme network 457193323Sedcongestion, the roundtrip delay jitter can exceed three seconds and 458193323Sedthe synchronization distance, which is equal to one\-half the 459193323Sedroundtrip delay plus error budget terms, can become very large. 460193323SedThe 461193323Sed.Nm 462193323Sedalgorithms discard sample offsets exceeding 128 ms, 463193323Sedunless the interval during which no sample offset is less than 128 464193323Sedms exceeds 900s. 465193323SedThe first sample after that, no matter what the 466193323Sedoffset, steps the clock to the indicated time. 467193323SedIn practice this 468193323Sedreduces the false alarm rate where the clock is stepped in error to 469193323Seda vanishingly low incidence. 470193323Sed.Pp 471193323SedAs the result of this behavior, once the clock has been set it 472193323Sedvery rarely strays more than 128 ms even under extreme cases of 473193323Sednetwork path congestion and jitter. 474193323SedSometimes, in particular when 475193323Sed.Nm 476193323Sedis first started without a valid drift file 477193323Sedon a system with a large intrinsic drift 478193323Sedthe error might grow to exceed 128 ms, 479193323Sedwhich would cause the clock to be set backwards 480193323Sedif the local clock time is more than 128 s 481193323Sedin the future relative to the server. 482193323SedIn some applications, this behavior may be unacceptable. 483193323SedThere are several solutions, however. 484193323SedIf the 485193323Sed.Fl x 486193323Sedoption is included on the command line, the clock will 487193323Sednever be stepped and only slew corrections will be used. 488193323SedBut this choice comes with a cost that 489193323Sedshould be carefully explored before deciding to use 490193323Sedthe 491193323Sed.Fl x 492193323Sedoption. 493193323SedThe maximum slew rate possible is limited 494193323Sedto 500 parts\-per\-million (PPM) as a consequence of the correctness 495193323Sedprinciples on which the NTP protocol and algorithm design are 496193323Sedbased. 497193323SedAs a result, the local clock can take a long time to 498193323Sedconverge to an acceptable offset, about 2,000 s for each second the 499193323Sedclock is outside the acceptable range. 500193323SedDuring this interval the 501193323Sedlocal clock will not be consistent with any other network clock and 502193323Sedthe system cannot be used for distributed applications that require 503193323Sedcorrectly synchronized network time. 504193323Sed.Pp 505193323SedIn spite of the above precautions, sometimes when large 506194612Sedfrequency errors are present the resulting time offsets stray 507194612Sedoutside the 128\-ms range and an eventual step or slew time 508194612Sedcorrection is required. 509194612SedIf following such a correction the 510194612Sedfrequency error is so large that the first sample is outside the 511194612Sedacceptable range, 512194612Sed.Nm 513194612Sedenters the same state as when the 514194612Sed.Pa ntp.drift 515194612Sedfile is not present. 516194612SedThe intent of this behavior 517194612Sedis to quickly correct the frequency and restore operation to the 518193323Sednormal tracking mode. 519193323SedIn the most extreme cases 520193323Sed(the host 521193323Sed.Cm time.ien.it 522193323Sedcomes to mind), there may be occasional 523193323Sedstep/slew corrections and subsequent frequency corrections. 524193323SedIt 525193323Sedhelps in these cases to use the 526193323Sed.Cm burst 527193323Sedkeyword when 528193323Sedconfiguring the server, but 529193323SedONLY 530193323Sedwhen you have permission to do so from the owner of the target host. 531193323Sed.Pp 532193323SedFinally, 533193323Sedin the past many startup scripts would run 534193323Sed.Xr ntpdate @NTPDATE_MS@ 535193323Sedor 536193323Sed.Xr sntp @SNTP_MS@ 537193323Sedto get the system clock close to correct before starting 538193323Sed.Xr ntpd @NTPD_MS@ , 539193323Sedbut this was never more than a mediocre hack and is no longer needed. 540193323SedIf you are following the instructions in 541193323Sed.Sx "Starting NTP (Best Current Practice)" 542193323Sedand you still need to set the system time before starting 543193323Sed.Nm , 544193323Sedplease open a bug report and document what is going on, 545193323Sedand then look at using 546193323Sed.Xr sntp @SNTP_MS@ 547193323Sedif you really need to set the clock before starting 548193323Sed.Nm . 549193323Sed.Pp 550193323SedThere is a way to start 551193323Sed.Xr ntpd @NTPD_MS@ 552193323Sedthat often addresses all of the problems mentioned above. 553193323Sed.Ss "Starting NTP (Best Current Practice)" 554193323SedFirst, use the 555193323Sed.Cm iburst 556193323Sedoption on your 557193323Sed.Cm server 558193323Sedentries. 559193323Sed.Pp 560193323SedIf you can also keep a good 561193323Sed.Pa ntp.drift 562193323Sedfile then 563193323Sed.Xr ntpd @NTPD_MS@ 564193323Sedwill effectively "warm\-start" and your system's clock will 565193323Sedbe stable in under 11 seconds' time. 566193323Sed.Pp 567193323SedAs soon as possible in the startup sequence, start 568193323Sed.Xr ntpd @NTPD_MS@ 569193323Sedwith at least the 570193323Sed.Fl g 571193323Sedand perhaps the 572193323Sed.Fl N 573193323Sedoptions. 574193323SedThen, 575193323Sedstart the rest of your "normal" processes. 576193323SedThis will give 577193323Sed.Xr ntpd @NTPD_MS@ 578193323Sedas much time as possible to get the system's clock synchronized and stable. 579193323Sed.Pp 580193323SedFinally, 581193323Sedif you have processes like 582193323Sed.Cm dovecot 583193323Sedor database servers 584193323Sedthat require 585193323Sedmonotonically\-increasing time, 586193323Sedrun 587193323Sed.Xr ntp\-wait 1ntp\-waitmdoc 588193323Sedas late as possible in the boot sequence 589193323Sed(perhaps with the 590193323Sed.Fl v 591193323Sedflag) 592193323Sedand after 593193323Sed.Xr ntp\-wait 1ntp\-waitmdoc 594193323Sedexits successfully 595193323Sedit is as safe as it will ever be to start any process that require 596194612Sedstable time. 597193323Sed.Ss "Frequency Discipline" 598194612SedThe 599193323Sed.Nm 600193323Sedbehavior at startup depends on whether the 601193323Sedfrequency file, usually 602193323Sed.Pa ntp.drift , 603193323Sedexists. 604193323SedThis file 605193323Sedcontains the latest estimate of clock frequency error. 606193323SedWhen the 607193323Sed.Nm 608193323Sedis started and the file does not exist, the 609193323Sed.Nm 610193323Sedenters a special mode designed to quickly adapt to 611193323Sedthe particular system clock oscillator time and frequency error. 612193323SedThis takes approximately 15 minutes, after which the time and 613193323Sedfrequency are set to nominal values and the 614193323Sed.Nm 615193323Sedenters 616193323Sednormal mode, where the time and frequency are continuously tracked 617193323Sedrelative to the server. 618193323SedAfter one hour the frequency file is 619193323Sedcreated and the current frequency offset written to it. 620193323SedWhen the 621193323Sed.Nm 622193323Sedis started and the file does exist, the 623193323Sed.Nm 624193323Sedfrequency is initialized from the file and enters normal mode 625194612Sedimmediately. 626193323SedAfter that the current frequency offset is written to 627193323Sedthe file at hourly intervals. 628193323Sed.Ss "Operating Modes" 629193323SedThe 630193323Sed.Nm 631193323Sedutility can operate in any of several modes, including 632193323Sedsymmetric active/passive, client/server broadcast/multicast and 633193323Sedmanycast, as described in the 634193323Sed.Qq Association Management 635193323Sedpage 636193323Sed(available as part of the HTML documentation 637193323Sedprovided in 638193323Sed.Pa /usr/share/doc/ntp ) . 639193323SedIt normally operates continuously while 640193323Sedmonitoring for small changes in frequency and trimming the clock 641193323Sedfor the ultimate precision. 642193323SedHowever, it can operate in a one\-time 643193323Sedmode where the time is set from an external server and frequency is 644193323Sedset from a previously recorded frequency file. 645193323SedA 646193323Sedbroadcast/multicast or manycast client can discover remote servers, 647193323Sedcompute server\-client propagation delay correction factors and 648193323Sedconfigure itself automatically. 649193323SedThis makes it possible to deploy a 650193323Sedfleet of workstations without specifying configuration details 651193323Sedspecific to the local environment. 652193323Sed.Pp 653193323SedBy default, 654193323Sed.Nm 655193323Sedruns in continuous mode where each of 656193323Sedpossibly several external servers is polled at intervals determined 657193323Sedby an intricate state machine. 658193323SedThe state machine measures the 659193323Sedincidental roundtrip delay jitter and oscillator frequency wander 660193323Sedand determines the best poll interval using a heuristic algorithm. 661193323SedOrdinarily, and in most operating environments, the state machine 662193323Sedwill start with 64s intervals and eventually increase in steps to 663193323Sed1024s. 664193323SedA small amount of random variation is introduced in order to 665193323Sedavoid bunching at the servers. 666193323SedIn addition, should a server become 667193323Sedunreachable for some time, the poll interval is increased in steps 668193323Sedto 1024s in order to reduce network overhead. 669193323Sed.Pp 670193323SedIn some cases it may not be practical for 671193323Sed.Nm 672193323Sedto run continuously. 673193323SedA common workaround has been to run the 674193323Sed.Xr ntpdate @NTPDATE_MS@ 675193323Sedor 676193323Sed.Xr sntp @SNTP_MS@ 677193323Sedprograms from a 678194612Sed.Xr cron 8 679193323Sedjob at designated 680193323Sedtimes. 681193323SedHowever, these programs do not have the crafted signal 682193323Sedprocessing, error checking or mitigation algorithms of 683193323Sed.Nm . 684193323SedThe 685193323Sed.Fl q 686193323Sedoption is intended for this purpose. 687193323SedSetting this option will cause 688193323Sed.Nm 689193323Sedto exit just after 690193323Sedsetting the clock for the first time. 691193323SedThe procedure for initially 692193323Sedsetting the clock is the same as in continuous mode; most 693193323Sedapplications will probably want to specify the 694193323Sed.Cm iburst 695193323Sedkeyword with the 696193323Sed.Ic server 697193323Sedconfiguration command. 698193323SedWith this 699193323Sedkeyword a volley of messages are exchanged to groom the data and 700193323Sedthe clock is set in about 10 s. 701193323SedIf nothing is heard after a 702193323Sedcouple of minutes, the daemon times out and exits. 703193323SedAfter a suitable 704193323Sedperiod of mourning, the 705193323Sed.Xr ntpdate @NTPDATE_MS@ 706193323Sedprogram will be 707193323Sedretired. 708193323Sed.Pp 709193323SedWhen kernel support is available to discipline the clock 710193323Sedfrequency, which is the case for stock Solaris, Tru64, Linux and 711193323Sed.Fx , 712193323Seda useful feature is available to discipline the clock 713193323Sedfrequency. 714193323SedFirst, 715193323Sed.Nm 716193323Sedis run in continuous mode with 717193323Sedselected servers in order to measure and record the intrinsic clock 718193323Sedfrequency offset in the frequency file. 719193323SedIt may take some hours for 720193323Sedthe frequency and offset to settle down. 721193323SedThen the 722193323Sed.Nm 723193323Sedis 724193323Sedstopped and run in one\-time mode as required. 725193323SedAt each startup, the 726193323Sedfrequency is read from the file and initializes the kernel 727193323Sedfrequency. 728193323Sed.Ss "Poll Interval Control" 729193323SedThis version of NTP includes an intricate state machine to 730193323Sedreduce the network load while maintaining a quality of 731193323Sedsynchronization consistent with the observed jitter and wander. 732193323SedThere are a number of ways to tailor the operation in order enhance 733193323Sedaccuracy by reducing the interval or to reduce network overhead by 734193323Sedincreasing it. 735193323SedHowever, the user is advised to carefully consider 736193323Sedthe consequences of changing the poll adjustment range from the 737193323Seddefault minimum of 64 s to the default maximum of 1,024 s. 738193323SedThe 739193323Seddefault minimum can be changed with the 740193323Sed.Ic tinker 741193323Sed.Cm minpoll 742193323Sedcommand to a value not less than 16 s. 743193323SedThis value is used for all 744193323Sedconfigured associations, unless overridden by the 745193323Sed.Cm minpoll 746193323Sedoption on the configuration command. 747193323SedNote that most device drivers 748193323Sedwill not operate properly if the poll interval is less than 64 s 749193323Sedand that the broadcast server and manycast client associations will 750193323Sedalso use the default, unless overridden. 751193323Sed.Pp 752193323SedIn some cases involving dial up or toll services, it may be 753193323Seduseful to increase the minimum interval to a few tens of minutes 754193323Sedand maximum interval to a day or so. 755193323SedUnder normal operation 756193323Sedconditions, once the clock discipline loop has stabilized the 757193323Sedinterval will be increased in steps from the minimum to the 758193323Sedmaximum. 759193323SedHowever, this assumes the intrinsic clock frequency error 760193323Sedis small enough for the discipline loop correct it. 761194612SedThe capture 762193323Sedrange of the loop is 500 PPM at an interval of 64s decreasing by a 763194612Sedfactor of two for each doubling of interval. 764193323SedAt a minimum of 1,024 765193323Seds, for example, the capture range is only 31 PPM. 766193323SedIf the intrinsic 767193323Sederror is greater than this, the drift file 768193323Sed.Pa ntp.drift 769193323Sedwill 770194612Sedhave to be specially tailored to reduce the residual error below 771193323Sedthis limit. 772193323SedOnce this is done, the drift file is automatically 773193323Sedupdated once per hour and is available to initialize the frequency 774194612Sedon subsequent daemon restarts. 775194612Sed.Ss "The huff\-n'\-puff Filter" 776194612SedIn scenarios where a considerable amount of data are to be 777193323Seddownloaded or uploaded over telephone modems, timekeeping quality 778193323Sedcan be seriously degraded. 779193323SedThis occurs because the differential 780194612Seddelays on the two directions of transmission can be quite large. 781193323SedIn 782193323Sedmany cases the apparent time errors are so large as to exceed the 783193323Sedstep threshold and a step correction can occur during and after the 784193323Seddata transfer is in progress. 785193323Sed.Pp 786193323SedThe huff\-n'\-puff filter is designed to correct the apparent time 787193323Sedoffset in these cases. 788193323SedIt depends on knowledge of the propagation 789193323Seddelay when no other traffic is present. 790193323SedIn common scenarios this 791193323Sedoccurs during other than work hours. 792193323SedThe filter maintains a shift 793193323Sedregister that remembers the minimum delay over the most recent 794193323Sedinterval measured usually in hours. 795193323SedUnder conditions of severe 796193323Seddelay, the filter corrects the apparent offset using the sign of 797193323Sedthe offset and the difference between the apparent delay and 798193323Sedminimum delay. 799193323SedThe name of the filter reflects the negative (huff) 800193323Sedand positive (puff) correction, which depends on the sign of the 801193323Sedoffset. 802193323Sed.Pp 803193323SedThe filter is activated by the 804193323Sed.Ic tinker 805193323Sedcommand and 806193323Sed.Cm huffpuff 807193323Sedkeyword, as described in 808193323Sed.Xr ntp.conf 5 . 809193323Sed.Sh "ENVIRONMENT" 810193323SedSee \fBOPTION PRESETS\fP for configuration environment variables. 811193323Sed.Sh FILES 812193323Sed.Bl -tag -width /etc/ntp.drift -compact 813193323Sed.It Pa /etc/ntp.conf 814193323Sedthe default name of the configuration file 815193323Sed.It Pa /etc/ntp.drift 816193323Sedthe default name of the drift file 817193323Sed.It Pa /etc/ntp.keys 818193323Sedthe default name of the key file 819193323Sed.El 820193323Sed.Sh "EXIT STATUS" 821193323SedOne of the following exit values will be returned: 822193323Sed.Bl -tag 823193323Sed.It 0 " (EXIT_SUCCESS)" 824193323SedSuccessful program execution. 825193323Sed.It 1 " (EXIT_FAILURE)" 826193323SedThe operation failed or the command syntax was not valid. 827193323Sed.It 70 " (EX_SOFTWARE)" 828193323Sedlibopts had an internal operational error. Please report 829193323Sedit to autogen\-users@lists.sourceforge.net. Thank you. 830193323Sed.El 831193323Sed.Sh "SEE ALSO" 832194612Sed.Xr ntp.conf 5 , 833193323Sed.Xr ntpdate @NTPDATE_MS@ , 834193323Sed.Xr ntpdc @NTPDC_MS@ , 835194612Sed.Xr ntpq @NTPQ_MS@ , 836193323Sed.Xr sntp @SNTP_MS@ 837193323Sed.Pp 838193323SedIn addition to the manual pages provided, 839193323Sedcomprehensive documentation is available on the world wide web 840194612Sedat 841193323Sed.Li http://www.ntp.org/ . 842193323SedA snapshot of this documentation is available in HTML format in 843193323Sed.Pa /usr/share/doc/ntp . 844193323Sed.Rs 845193323Sed.%A David L. Mills 846193323Sed.%T Network Time Protocol (Version 1) 847194612Sed.%O RFC1059 848193323Sed.Re 849193323Sed.Rs 850193323Sed.%A David L. Mills 851193323Sed.%T Network Time Protocol (Version 2) 852193323Sed.%O RFC1119 853193323Sed.Re 854193323Sed.Rs 855193323Sed.%A David L. Mills 856193323Sed.%T Network Time Protocol (Version 3) 857193323Sed.%O RFC1305 858193323Sed.Re 859193323Sed.Rs 860193323Sed.%A David L. Mills 861193323Sed.%A J. Martin, Ed. 862193323Sed.%A J. Burbank 863193323Sed.%A W. Kasch 864193323Sed.%T Network Time Protocol Version 4: Protocol and Algorithms Specification 865193323Sed.%O RFC5905 866193323Sed.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\-2017 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