1310419Sdelphij.Dd November 21 2016 2290001Sglebius.Dt NTPD @NTPD_MS@ User Commands 3290001Sglebius.Os 4290001Sglebius.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) 5290001Sglebius.\" 6310419Sdelphij.\" It has been AutoGen-ed November 21, 2016 at 08:02:08 AM by AutoGen 5.18.5 7290001Sglebius.\" From the definitions ntpd-opts.def 8290001Sglebius.\" and the template file agmdoc-cmd.tpl 9290001Sglebius.Sh NAME 10290001Sglebius.Nm ntpd 11290001Sglebius.Nd NTP daemon program 12290001Sglebius.Sh SYNOPSIS 13290001Sglebius.Nm 14290001Sglebius.\" Mixture of short (flag) options and long options 15290001Sglebius.Op Fl flags 16290001Sglebius.Op Fl flag Op Ar value 17290001Sglebius.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 18290001Sglebius[ <server1> ... <serverN> ] 19290001Sglebius.Pp 20290001Sglebius.Sh DESCRIPTION 21290001SglebiusThe 22290001Sglebius.Nm 23290001Sglebiusutility is an operating system daemon which sets 24290001Sglebiusand maintains the system time of day in synchronism with Internet 25290001Sglebiusstandard time servers. 26290001SglebiusIt is a complete implementation of the 27290001SglebiusNetwork Time Protocol (NTP) version 4, as defined by RFC\-5905, 28290001Sglebiusbut also retains compatibility with 29290001Sglebiusversion 3, as defined by RFC\-1305, and versions 1 30290001Sglebiusand 2, as defined by RFC\-1059 and RFC\-1119, respectively. 31290001Sglebius.Pp 32290001SglebiusThe 33290001Sglebius.Nm 34290001Sglebiusutility does most computations in 64\-bit floating point 35290001Sglebiusarithmetic and does relatively clumsy 64\-bit fixed point operations 36290001Sglebiusonly when necessary to preserve the ultimate precision, about 232 37290001Sglebiuspicoseconds. 38290001SglebiusWhile the ultimate precision is not achievable with 39290001Sglebiusordinary workstations and networks of today, it may be required 40290001Sglebiuswith future gigahertz CPU clocks and gigabit LANs. 41290001Sglebius.Pp 42290001SglebiusOrdinarily, 43290001Sglebius.Nm 44290001Sglebiusreads the 45290001Sglebius.Xr ntp.conf 5 46290001Sglebiusconfiguration file at startup time in order to determine the 47290001Sglebiussynchronization sources and operating modes. 48290001SglebiusIt is also possible to 49290001Sglebiusspecify a working, although limited, configuration entirely on the 50290001Sglebiuscommand line, obviating the need for a configuration file. 51290001SglebiusThis may 52290001Sglebiusbe particularly useful when the local host is to be configured as a 53290001Sglebiusbroadcast/multicast client, with all peers being determined by 54290001Sglebiuslistening to broadcasts at run time. 55290001Sglebius.Pp 56290001SglebiusIf NetInfo support is built into 57290001Sglebius.Nm , 58290001Sglebiusthen 59290001Sglebius.Nm 60290001Sglebiuswill attempt to read its configuration from the 61290001SglebiusNetInfo if the default 62290001Sglebius.Xr ntp.conf 5 63290001Sglebiusfile cannot be read and no file is 64290001Sglebiusspecified by the 65290001Sglebius.Fl c 66290001Sglebiusoption. 67290001Sglebius.Pp 68290001SglebiusVarious internal 69290001Sglebius.Nm 70290001Sglebiusvariables can be displayed and 71290001Sglebiusconfiguration options altered while the 72290001Sglebius.Nm 73290001Sglebiusis running 74290001Sglebiususing the 75290001Sglebius.Xr ntpq @NTPQ_MS@ 76290001Sglebiusand 77290001Sglebius.Xr ntpdc @NTPDC_MS@ 78290001Sglebiusutility programs. 79290001Sglebius.Pp 80290001SglebiusWhen 81290001Sglebius.Nm 82290001Sglebiusstarts it looks at the value of 83290001Sglebius.Xr umask 2 , 84290001Sglebiusand if zero 85290001Sglebius.Nm 86290001Sglebiuswill set the 87290001Sglebius.Xr umask 2 88290001Sglebiusto 022. 89290001Sglebius.Sh "OPTIONS" 90290001Sglebius.Bl -tag 91290001Sglebius.It Fl 4 , Fl \-ipv4 92290001SglebiusForce IPv4 DNS name resolution. 93290001SglebiusThis option must not appear in combination with any of the following options: 94290001Sglebiusipv6. 95290001Sglebius.sp 96290001SglebiusForce DNS resolution of following host names on the command line 97290001Sglebiusto the IPv4 namespace. 98290001Sglebius.It Fl 6 , Fl \-ipv6 99290001SglebiusForce IPv6 DNS name resolution. 100290001SglebiusThis option must not appear in combination with any of the following options: 101290001Sglebiusipv4. 102290001Sglebius.sp 103290001SglebiusForce DNS resolution of following host names on the command line 104290001Sglebiusto the IPv6 namespace. 105290001Sglebius.It Fl a , Fl \-authreq 106290001SglebiusRequire crypto authentication. 107290001SglebiusThis option must not appear in combination with any of the following options: 108290001Sglebiusauthnoreq. 109290001Sglebius.sp 110290001SglebiusRequire cryptographic authentication for broadcast client, 111290001Sglebiusmulticast client and symmetric passive associations. 112290001SglebiusThis is the default. 113290001Sglebius.It Fl A , Fl \-authnoreq 114290001SglebiusDo not require crypto authentication. 115290001SglebiusThis option must not appear in combination with any of the following options: 116290001Sglebiusauthreq. 117290001Sglebius.sp 118290001SglebiusDo not require cryptographic authentication for broadcast client, 119290001Sglebiusmulticast client and symmetric passive associations. 120290001SglebiusThis is almost never a good idea. 121290001Sglebius.It Fl b , Fl \-bcastsync 122290001SglebiusAllow us to sync to broadcast servers. 123290001Sglebius.sp 124290001Sglebius.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string 125290001Sglebiusconfiguration file name. 126290001Sglebius.sp 127290001SglebiusThe name and path of the configuration file, 128290001Sglebius\fI/etc/ntp.conf\fP 129290001Sglebiusby default. 130290001Sglebius.It Fl d , Fl \-debug\-level 131290001SglebiusIncrease debug verbosity level. 132290001SglebiusThis option may appear an unlimited number of times. 133290001Sglebius.sp 134290001Sglebius.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 135290001SglebiusSet the debug verbosity level. 136290001SglebiusThis option may appear an unlimited number of times. 137290001SglebiusThis option takes an integer number as its argument. 138290001Sglebius.sp 139290001Sglebius.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string 140290001Sglebiusfrequency drift file name. 141290001Sglebius.sp 142290001SglebiusThe name and path of the frequency file, 143290001Sglebius\fI/etc/ntp.drift\fP 144290001Sglebiusby default. 145290001SglebiusThis is the same operation as the 146290001Sglebius\fBdriftfile\fP \fIdriftfile\fP 147290001Sglebiusconfiguration specification in the 148290001Sglebius\fI/etc/ntp.conf\fP 149290001Sglebiusfile. 150290001Sglebius.It Fl g , Fl \-panicgate 151290001SglebiusAllow the first adjustment to be Big. 152290001SglebiusThis option may appear an unlimited number of times. 153290001Sglebius.sp 154290001SglebiusNormally, 155290001Sglebius\fBntpd\fP 156290001Sglebiusexits 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, 157290001Sglebius\fBntpd\fP 158290001Sglebiuswill exit with a message to the system log. This option can be used with the 159290001Sglebius\fB\-q\fP 160290001Sglebiusand 161290001Sglebius\fB\-x\fP 162290001Sglebiusoptions. 163290001SglebiusSee the 164290001Sglebius\fBtinker\fP 165290001Sglebiusconfiguration file directive for other options. 166290001Sglebius.It Fl G , Fl \-force\-step\-once 167290001SglebiusStep any initial offset correction.. 168290001Sglebius.sp 169290001SglebiusNormally, 170290001Sglebius\fBntpd\fP 171290001Sglebiussteps the time if the time offset exceeds the step threshold, 172290001Sglebiuswhich is 128 ms by default, and otherwise slews the time. 173290001SglebiusThis option forces the initial offset correction to be stepped, 174290001Sglebiusso the highest time accuracy can be achieved quickly. 175290001SglebiusHowever, this may also cause the time to be stepped back 176290001Sglebiusso this option must not be used if 177290001Sglebiusapplications requiring monotonic time are running. 178290001SglebiusSee the \fBtinker\fP configuration file directive for other options. 179290001Sglebius.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string 180290001SglebiusJail directory. 181290001Sglebius.sp 182290001SglebiusChroot the server to the directory 183290001Sglebius\fIjaildir\fP 184290001Sglebius. 185290001SglebiusThis option also implies that the server attempts to drop root privileges at startup. 186290001SglebiusYou may need to also specify a 187290001Sglebius\fB\-u\fP 188290001Sglebiusoption. 189290001SglebiusThis option is only available if the OS supports adjusting the clock 190290001Sglebiuswithout full root privileges. 191290001SglebiusThis option is supported under NetBSD (configure with 192290001Sglebius\fB\-\-enable\-clockctl\fP) or Linux (configure with 193290001Sglebius\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 194290001Sglebius.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface 195290001SglebiusListen on an interface name or address. 196290001SglebiusThis option may appear an unlimited number of times. 197290001Sglebius.sp 198290001SglebiusOpen the network address given, or all the addresses associated with the 199290001Sglebiusgiven interface name. This option may appear multiple times. This option 200290001Sglebiusalso implies not opening other addresses, except wildcard and localhost. 201290001SglebiusThis option is deprecated. Please consider using the configuration file 202290001Sglebius\fBinterface\fP command, which is more versatile. 203290001Sglebius.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string 204290001Sglebiuspath to symmetric keys. 205290001Sglebius.sp 206290001SglebiusSpecify the name and path of the symmetric key file. 207290001Sglebius\fI/etc/ntp.keys\fP 208290001Sglebiusis the default. 209290001SglebiusThis is the same operation as the 210290001Sglebius\fBkeys\fP \fIkeyfile\fP 211290001Sglebiusconfiguration file directive. 212290001Sglebius.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string 213290001Sglebiuspath to the log file. 214290001Sglebius.sp 215290001SglebiusSpecify the name and path of the log file. 216290001SglebiusThe default is the system log file. 217290001SglebiusThis is the same operation as the 218290001Sglebius\fBlogfile\fP \fIlogfile\fP 219290001Sglebiusconfiguration file directive. 220290001Sglebius.It Fl L , Fl \-novirtualips 221290001SglebiusDo not listen to virtual interfaces. 222290001Sglebius.sp 223290001SglebiusDo not listen to virtual interfaces, defined as those with 224290001Sglebiusnames containing a colon. This option is deprecated. Please 225290001Sglebiusconsider using the configuration file \fBinterface\fP command, which 226290001Sglebiusis more versatile. 227290001Sglebius.It Fl M , Fl \-modifymmtimer 228290001SglebiusModify Multimedia Timer (Windows only). 229290001Sglebius.sp 230290001SglebiusSet the Windows Multimedia Timer to highest resolution. This 231290001Sglebiusensures the resolution does not change while ntpd is running, 232290001Sglebiusavoiding timekeeping glitches associated with changes. 233290001Sglebius.It Fl n , Fl \-nofork 234290001SglebiusDo not fork. 235290001SglebiusThis option must not appear in combination with any of the following options: 236290001Sglebiuswait\-sync. 237290001Sglebius.sp 238290001Sglebius.It Fl N , Fl \-nice 239290001SglebiusRun at high priority. 240290001Sglebius.sp 241290001SglebiusTo the extent permitted by the operating system, run 242290001Sglebius\fBntpd\fP 243290001Sglebiusat the highest priority. 244290001Sglebius.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string 245290001Sglebiuspath to the PID file. 246290001Sglebius.sp 247290001SglebiusSpecify the name and path of the file used to record 248290001Sglebius\fBntpd\fP's 249290001Sglebiusprocess ID. 250290001SglebiusThis is the same operation as the 251290001Sglebius\fBpidfile\fP \fIpidfile\fP 252290001Sglebiusconfiguration file directive. 253290001Sglebius.It Fl P Ar number , Fl \-priority Ns = Ns Ar number 254290001SglebiusProcess priority. 255290001SglebiusThis option takes an integer number as its argument. 256290001Sglebius.sp 257290001SglebiusTo the extent permitted by the operating system, run 258290001Sglebius\fBntpd\fP 259290001Sglebiusat the specified 260290001Sglebius\fBsched_setscheduler(SCHED_FIFO)\fP 261290001Sglebiuspriority. 262290001Sglebius.It Fl q , Fl \-quit 263290001SglebiusSet the time and quit. 264290001SglebiusThis option must not appear in combination with any of the following options: 265290001Sglebiussaveconfigquit, wait\-sync. 266290001Sglebius.sp 267290001Sglebius\fBntpd\fP 268290001Sglebiuswill not daemonize and will exit after the clock is first 269290001Sglebiussynchronized. This behavior mimics that of the 270290001Sglebius\fBntpdate\fP 271290001Sglebiusprogram, which will soon be replaced with a shell script. 272290001SglebiusThe 273290001Sglebius\fB\-g\fP 274290001Sglebiusand 275290001Sglebius\fB\-x\fP 276290001Sglebiusoptions can be used with this option. 277290001SglebiusNote: The kernel time discipline is disabled with this option. 278290001Sglebius.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string 279290001SglebiusBroadcast/propagation delay. 280290001Sglebius.sp 281290001SglebiusSpecify 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. 282290001Sglebius.It Fl \-saveconfigquit Ns = Ns Ar string 283290001SglebiusSave parsed configuration and quit. 284290001SglebiusThis option must not appear in combination with any of the following options: 285290001Sglebiusquit, wait\-sync. 286290001Sglebius.sp 287290001SglebiusCause \fBntpd\fP to parse its startup configuration file and save an 288290001Sglebiusequivalent to the given filename and exit. This option was 289290001Sglebiusdesigned for automated testing. 290290001Sglebius.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string 291290001SglebiusStatistics file location. 292290001Sglebius.sp 293290001SglebiusSpecify the directory path for files created by the statistics facility. 294290001SglebiusThis is the same operation as the 295290001Sglebius\fBstatsdir\fP \fIstatsdir\fP 296290001Sglebiusconfiguration file directive. 297290001Sglebius.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey 298290001SglebiusTrusted key number. 299290001SglebiusThis option may appear an unlimited number of times. 300290001Sglebius.sp 301290001SglebiusAdd the specified key number to the trusted key list. 302290001Sglebius.It Fl u Ar string , Fl \-user Ns = Ns Ar string 303290001SglebiusRun as userid (or userid:groupid). 304290001Sglebius.sp 305290001SglebiusSpecify a user, and optionally a group, to switch to. 306290001SglebiusThis option is only available if the OS supports adjusting the clock 307290001Sglebiuswithout full root privileges. 308290001SglebiusThis option is supported under NetBSD (configure with 309290001Sglebius\fB\-\-enable\-clockctl\fP) or Linux (configure with 310290001Sglebius\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 311290001Sglebius.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number 312290001Sglebiusinterval in seconds between scans for new or dropped interfaces. 313290001SglebiusThis option takes an integer number as its argument. 314290001Sglebius.sp 315290001SglebiusGive the time in seconds between two scans for new or dropped interfaces. 316290001SglebiusFor systems with routing socket support the scans will be performed shortly after the interface change 317290001Sglebiushas been detected by the system. 318290001SglebiusUse 0 to disable scanning. 60 seconds is the minimum time between scans. 319290001Sglebius.It Fl \-var Ns = Ns Ar nvar 320290001Sglebiusmake ARG an ntp variable (RW). 321290001SglebiusThis option may appear an unlimited number of times. 322290001Sglebius.sp 323290001Sglebius.It Fl \-dvar Ns = Ns Ar ndvar 324290001Sglebiusmake ARG an ntp variable (RW|DEF). 325290001SglebiusThis option may appear an unlimited number of times. 326290001Sglebius.sp 327290001Sglebius.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number 328290001SglebiusSeconds to wait for first clock sync. 329290001SglebiusThis option must not appear in combination with any of the following options: 330290001Sglebiusnofork, quit, saveconfigquit. 331290001SglebiusThis option takes an integer number as its argument. 332290001Sglebius.sp 333290001SglebiusIf greater than zero, alters \fBntpd\fP's behavior when forking to 334290001Sglebiusdaemonize. Instead of exiting with status 0 immediately after 335290001Sglebiusthe fork, the parent waits up to the specified number of 336290001Sglebiusseconds for the child to first synchronize the clock. The exit 337290001Sglebiusstatus is zero (success) if the clock was synchronized, 338290001Sglebiusotherwise it is \fBETIMEDOUT\fP. 339290001SglebiusThis provides the option for a script starting \fBntpd\fP to easily 340290001Sglebiuswait for the first set of the clock before proceeding. 341290001Sglebius.It Fl x , Fl \-slew 342290001SglebiusSlew up to 600 seconds. 343290001Sglebius.sp 344290001SglebiusNormally, 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. 345290001SglebiusThis option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 346290001SglebiusNote: 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. 347290001SglebiusThus, an adjustment as much as 600 s will take almost 14 days to complete. 348290001SglebiusThis option can be used with the 349290001Sglebius\fB\-g\fP 350290001Sglebiusand 351290001Sglebius\fB\-q\fP 352290001Sglebiusoptions. 353290001SglebiusSee the 354290001Sglebius\fBtinker\fP 355290001Sglebiusconfiguration file directive for other options. 356290001SglebiusNote: The kernel time discipline is disabled with this option. 357290001Sglebius.It Fl \-usepcc 358290001SglebiusUse CPU cycle counter (Windows only). 359290001Sglebius.sp 360290001SglebiusAttempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 361290001SglebiusThe CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 362290001Sglebiusthey have the same frequency, the CPU counter (RDTSC on x86) is 363290001Sglebiusused directly, saving the overhead of a system call. 364290001Sglebius.It Fl \-pccfreq Ns = Ns Ar string 365290001SglebiusForce CPU cycle counter use (Windows only). 366290001Sglebius.sp 367290001SglebiusForce substitution the CPU counter for \fBQueryPerformanceCounter\fP. 368290001SglebiusThe CPU counter (RDTSC on x86) is used unconditionally with the 369290001Sglebiusgiven frequency (in Hz). 370290001Sglebius.It Fl m , Fl \-mdns 371290001SglebiusRegister with mDNS as a NTP server. 372290001Sglebius.sp 373290001SglebiusRegisters as an NTP server with the local mDNS server which allows 374290001Sglebiusthe server to be discovered via mDNS client lookup. 375290001Sglebius.It Fl \&? , Fl \-help 376290001SglebiusDisplay usage information and exit. 377290001Sglebius.It Fl \&! , Fl \-more\-help 378290001SglebiusPass the extended usage information through a pager. 379290001Sglebius.It Fl \-version Op Brq Ar v|c|n 380290001SglebiusOutput version of program and exit. The default mode is `v', a simple 381290001Sglebiusversion. The `c' mode will print copyright information and `n' will 382290001Sglebiusprint the full copyright notice. 383290001Sglebius.El 384290001Sglebius.Sh "OPTION PRESETS" 385290001SglebiusAny option that is not marked as \fInot presettable\fP may be preset 386290001Sglebiusby loading values from environment variables named: 387290001Sglebius.nf 388290001Sglebius \fBNTPD_<option\-name>\fP or \fBNTPD\fP 389290001Sglebius.fi 390290001Sglebius.ad 391290001Sglebius.Sh USAGE 392290001Sglebius.Ss "How NTP Operates" 393290001SglebiusThe 394290001Sglebius.Nm 395290001Sglebiusutility operates by exchanging messages with 396290001Sglebiusone or more configured servers over a range of designated poll intervals. 397290001SglebiusWhen 398290001Sglebiusstarted, whether for the first or subsequent times, the program 399290001Sglebiusrequires several exchanges from the majority of these servers so 400290001Sglebiusthe signal processing and mitigation algorithms can accumulate and 401290001Sglebiusgroom the data and set the clock. 402290001SglebiusIn order to protect the network 403290001Sglebiusfrom bursts, the initial poll interval for each server is delayed 404290001Sglebiusan interval randomized over a few seconds. 405290001SglebiusAt the default initial poll 406290001Sglebiusinterval of 64s, several minutes can elapse before the clock is 407290001Sglebiusset. 408290001SglebiusThis initial delay to set the clock 409290001Sglebiuscan be safely and dramatically reduced using the 410290001Sglebius.Cm iburst 411290001Sglebiuskeyword with the 412290001Sglebius.Ic server 413290001Sglebiusconfiguration 414290001Sglebiuscommand, as described in 415290001Sglebius.Xr ntp.conf 5 . 416290001Sglebius.Pp 417290001SglebiusMost operating systems and hardware of today incorporate a 418290001Sglebiustime\-of\-year (TOY) chip to maintain the time during periods when 419290001Sglebiusthe power is off. 420290001SglebiusWhen the machine is booted, the chip is used to 421290001Sglebiusinitialize the operating system time. 422290001SglebiusAfter the machine has 423290001Sglebiussynchronized to a NTP server, the operating system corrects the 424290001Sglebiuschip from time to time. 425290001SglebiusIn the default case, if 426290001Sglebius.Nm 427290001Sglebiusdetects that the time on the host 428290001Sglebiusis more than 1000s from the server time, 429290001Sglebius.Nm 430290001Sglebiusassumes something must be terribly wrong and the only 431290001Sglebiusreliable action is for the operator to intervene and set the clock 432290001Sglebiusby hand. 433290001Sglebius(Reasons for this include there is no TOY chip, 434290001Sglebiusor its battery is dead, or that the TOY chip is just of poor quality.) 435290001SglebiusThis causes 436290001Sglebius.Nm 437290001Sglebiusto exit with a panic message to 438290001Sglebiusthe system log. 439290001SglebiusThe 440290001Sglebius.Fl g 441290001Sglebiusoption overrides this check and the 442290001Sglebiusclock will be set to the server time regardless of the chip time 443290001Sglebius(up to 68 years in the past or future \(em 444290001Sglebiusthis is a limitation of the NTPv4 protocol). 445290001SglebiusHowever, and to protect against broken hardware, such as when the 446290001SglebiusCMOS battery fails or the clock counter becomes defective, once the 447290001Sglebiusclock has been set an error greater than 1000s will cause 448290001Sglebius.Nm 449290001Sglebiusto exit anyway. 450290001Sglebius.Pp 451290001SglebiusUnder ordinary conditions, 452290001Sglebius.Nm 453290001Sglebiusadjusts the clock in 454290001Sglebiussmall steps so that the timescale is effectively continuous and 455290001Sglebiuswithout discontinuities. 456290001SglebiusUnder conditions of extreme network 457290001Sglebiuscongestion, the roundtrip delay jitter can exceed three seconds and 458290001Sglebiusthe synchronization distance, which is equal to one\-half the 459290001Sglebiusroundtrip delay plus error budget terms, can become very large. 460290001SglebiusThe 461290001Sglebius.Nm 462290001Sglebiusalgorithms discard sample offsets exceeding 128 ms, 463290001Sglebiusunless the interval during which no sample offset is less than 128 464290001Sglebiusms exceeds 900s. 465290001SglebiusThe first sample after that, no matter what the 466290001Sglebiusoffset, steps the clock to the indicated time. 467290001SglebiusIn practice this 468290001Sglebiusreduces the false alarm rate where the clock is stepped in error to 469290001Sglebiusa vanishingly low incidence. 470290001Sglebius.Pp 471290001SglebiusAs the result of this behavior, once the clock has been set it 472290001Sglebiusvery rarely strays more than 128 ms even under extreme cases of 473290001Sglebiusnetwork path congestion and jitter. 474290001SglebiusSometimes, in particular when 475290001Sglebius.Nm 476290001Sglebiusis first started without a valid drift file 477290001Sglebiuson a system with a large intrinsic drift 478290001Sglebiusthe error might grow to exceed 128 ms, 479290001Sglebiuswhich would cause the clock to be set backwards 480290001Sglebiusif the local clock time is more than 128 s 481290001Sglebiusin the future relative to the server. 482290001SglebiusIn some applications, this behavior may be unacceptable. 483290001SglebiusThere are several solutions, however. 484290001SglebiusIf the 485290001Sglebius.Fl x 486290001Sglebiusoption is included on the command line, the clock will 487290001Sglebiusnever be stepped and only slew corrections will be used. 488290001SglebiusBut this choice comes with a cost that 489290001Sglebiusshould be carefully explored before deciding to use 490290001Sglebiusthe 491290001Sglebius.Fl x 492290001Sglebiusoption. 493290001SglebiusThe maximum slew rate possible is limited 494290001Sglebiusto 500 parts\-per\-million (PPM) as a consequence of the correctness 495290001Sglebiusprinciples on which the NTP protocol and algorithm design are 496290001Sglebiusbased. 497290001SglebiusAs a result, the local clock can take a long time to 498290001Sglebiusconverge to an acceptable offset, about 2,000 s for each second the 499290001Sglebiusclock is outside the acceptable range. 500290001SglebiusDuring this interval the 501290001Sglebiuslocal clock will not be consistent with any other network clock and 502290001Sglebiusthe system cannot be used for distributed applications that require 503290001Sglebiuscorrectly synchronized network time. 504290001Sglebius.Pp 505290001SglebiusIn spite of the above precautions, sometimes when large 506290001Sglebiusfrequency errors are present the resulting time offsets stray 507290001Sglebiusoutside the 128\-ms range and an eventual step or slew time 508290001Sglebiuscorrection is required. 509290001SglebiusIf following such a correction the 510290001Sglebiusfrequency error is so large that the first sample is outside the 511290001Sglebiusacceptable range, 512290001Sglebius.Nm 513290001Sglebiusenters the same state as when the 514290001Sglebius.Pa ntp.drift 515290001Sglebiusfile is not present. 516290001SglebiusThe intent of this behavior 517290001Sglebiusis to quickly correct the frequency and restore operation to the 518290001Sglebiusnormal tracking mode. 519290001SglebiusIn the most extreme cases 520290001Sglebius(the host 521290001Sglebius.Cm time.ien.it 522290001Sglebiuscomes to mind), there may be occasional 523290001Sglebiusstep/slew corrections and subsequent frequency corrections. 524290001SglebiusIt 525290001Sglebiushelps in these cases to use the 526290001Sglebius.Cm burst 527290001Sglebiuskeyword when 528290001Sglebiusconfiguring the server, but 529290001SglebiusONLY 530290001Sglebiuswhen you have permission to do so from the owner of the target host. 531290001Sglebius.Pp 532290001SglebiusFinally, 533290001Sglebiusin the past many startup scripts would run 534290001Sglebius.Xr ntpdate @NTPDATE_MS@ 535290001Sglebiusor 536290001Sglebius.Xr sntp @SNTP_MS@ 537290001Sglebiusto get the system clock close to correct before starting 538290001Sglebius.Xr ntpd @NTPD_MS@ , 539290001Sglebiusbut this was never more than a mediocre hack and is no longer needed. 540290001SglebiusIf you are following the instructions in 541290001Sglebius.Sx "Starting NTP (Best Current Practice)" 542290001Sglebiusand you still need to set the system time before starting 543290001Sglebius.Nm , 544290001Sglebiusplease open a bug report and document what is going on, 545290001Sglebiusand then look at using 546290001Sglebius.Xr sntp @SNTP_MS@ 547290001Sglebiusif you really need to set the clock before starting 548290001Sglebius.Nm . 549290001Sglebius.Pp 550290001SglebiusThere is a way to start 551290001Sglebius.Xr ntpd @NTPD_MS@ 552290001Sglebiusthat often addresses all of the problems mentioned above. 553290001Sglebius.Ss "Starting NTP (Best Current Practice)" 554290001SglebiusFirst, use the 555290001Sglebius.Cm iburst 556290001Sglebiusoption on your 557290001Sglebius.Cm server 558290001Sglebiusentries. 559290001Sglebius.Pp 560290001SglebiusIf you can also keep a good 561290001Sglebius.Pa ntp.drift 562290001Sglebiusfile then 563290001Sglebius.Xr ntpd @NTPD_MS@ 564290001Sglebiuswill effectively "warm\-start" and your system's clock will 565290001Sglebiusbe stable in under 11 seconds' time. 566290001Sglebius.Pp 567290001SglebiusAs soon as possible in the startup sequence, start 568290001Sglebius.Xr ntpd @NTPD_MS@ 569290001Sglebiuswith at least the 570290001Sglebius.Fl g 571290001Sglebiusand perhaps the 572290001Sglebius.Fl N 573290001Sglebiusoptions. 574290001SglebiusThen, 575290001Sglebiusstart the rest of your "normal" processes. 576290001SglebiusThis will give 577290001Sglebius.Xr ntpd @NTPD_MS@ 578290001Sglebiusas much time as possible to get the system's clock synchronized and stable. 579290001Sglebius.Pp 580290001SglebiusFinally, 581290001Sglebiusif you have processes like 582290001Sglebius.Cm dovecot 583290001Sglebiusor database servers 584290001Sglebiusthat require 585290001Sglebiusmonotonically\-increasing time, 586290001Sglebiusrun 587290001Sglebius.Xr ntp\-wait 1ntp\-waitmdoc 588290001Sglebiusas late as possible in the boot sequence 589290001Sglebius(perhaps with the 590290001Sglebius.Fl v 591290001Sglebiusflag) 592290001Sglebiusand after 593290001Sglebius.Xr ntp\-wait 1ntp\-waitmdoc 594290001Sglebiusexits successfully 595290001Sglebiusit is as safe as it will ever be to start any process that require 596290001Sglebiusstable time. 597290001Sglebius.Ss "Frequency Discipline" 598290001SglebiusThe 599290001Sglebius.Nm 600290001Sglebiusbehavior at startup depends on whether the 601290001Sglebiusfrequency file, usually 602290001Sglebius.Pa ntp.drift , 603290001Sglebiusexists. 604290001SglebiusThis file 605290001Sglebiuscontains the latest estimate of clock frequency error. 606290001SglebiusWhen the 607290001Sglebius.Nm 608290001Sglebiusis started and the file does not exist, the 609290001Sglebius.Nm 610290001Sglebiusenters a special mode designed to quickly adapt to 611290001Sglebiusthe particular system clock oscillator time and frequency error. 612290001SglebiusThis takes approximately 15 minutes, after which the time and 613290001Sglebiusfrequency are set to nominal values and the 614290001Sglebius.Nm 615290001Sglebiusenters 616290001Sglebiusnormal mode, where the time and frequency are continuously tracked 617290001Sglebiusrelative to the server. 618290001SglebiusAfter one hour the frequency file is 619290001Sglebiuscreated and the current frequency offset written to it. 620290001SglebiusWhen the 621290001Sglebius.Nm 622290001Sglebiusis started and the file does exist, the 623290001Sglebius.Nm 624290001Sglebiusfrequency is initialized from the file and enters normal mode 625290001Sglebiusimmediately. 626290001SglebiusAfter that the current frequency offset is written to 627290001Sglebiusthe file at hourly intervals. 628290001Sglebius.Ss "Operating Modes" 629290001SglebiusThe 630290001Sglebius.Nm 631290001Sglebiusutility can operate in any of several modes, including 632290001Sglebiussymmetric active/passive, client/server broadcast/multicast and 633290001Sglebiusmanycast, as described in the 634290001Sglebius.Qq Association Management 635290001Sglebiuspage 636290001Sglebius(available as part of the HTML documentation 637290001Sglebiusprovided in 638290001Sglebius.Pa /usr/share/doc/ntp ) . 639290001SglebiusIt normally operates continuously while 640290001Sglebiusmonitoring for small changes in frequency and trimming the clock 641290001Sglebiusfor the ultimate precision. 642290001SglebiusHowever, it can operate in a one\-time 643290001Sglebiusmode where the time is set from an external server and frequency is 644290001Sglebiusset from a previously recorded frequency file. 645290001SglebiusA 646290001Sglebiusbroadcast/multicast or manycast client can discover remote servers, 647290001Sglebiuscompute server\-client propagation delay correction factors and 648290001Sglebiusconfigure itself automatically. 649290001SglebiusThis makes it possible to deploy a 650290001Sglebiusfleet of workstations without specifying configuration details 651290001Sglebiusspecific to the local environment. 652290001Sglebius.Pp 653290001SglebiusBy default, 654290001Sglebius.Nm 655290001Sglebiusruns in continuous mode where each of 656290001Sglebiuspossibly several external servers is polled at intervals determined 657290001Sglebiusby an intricate state machine. 658290001SglebiusThe state machine measures the 659290001Sglebiusincidental roundtrip delay jitter and oscillator frequency wander 660290001Sglebiusand determines the best poll interval using a heuristic algorithm. 661290001SglebiusOrdinarily, and in most operating environments, the state machine 662290001Sglebiuswill start with 64s intervals and eventually increase in steps to 663290001Sglebius1024s. 664290001SglebiusA small amount of random variation is introduced in order to 665290001Sglebiusavoid bunching at the servers. 666290001SglebiusIn addition, should a server become 667290001Sglebiusunreachable for some time, the poll interval is increased in steps 668290001Sglebiusto 1024s in order to reduce network overhead. 669290001Sglebius.Pp 670290001SglebiusIn some cases it may not be practical for 671290001Sglebius.Nm 672290001Sglebiusto run continuously. 673290001SglebiusA common workaround has been to run the 674290001Sglebius.Xr ntpdate @NTPDATE_MS@ 675290001Sglebiusor 676290001Sglebius.Xr sntp @SNTP_MS@ 677290001Sglebiusprograms from a 678290001Sglebius.Xr cron 8 679290001Sglebiusjob at designated 680290001Sglebiustimes. 681290001SglebiusHowever, these programs do not have the crafted signal 682290001Sglebiusprocessing, error checking or mitigation algorithms of 683290001Sglebius.Nm . 684290001SglebiusThe 685290001Sglebius.Fl q 686290001Sglebiusoption is intended for this purpose. 687290001SglebiusSetting this option will cause 688290001Sglebius.Nm 689290001Sglebiusto exit just after 690290001Sglebiussetting the clock for the first time. 691290001SglebiusThe procedure for initially 692290001Sglebiussetting the clock is the same as in continuous mode; most 693290001Sglebiusapplications will probably want to specify the 694290001Sglebius.Cm iburst 695290001Sglebiuskeyword with the 696290001Sglebius.Ic server 697290001Sglebiusconfiguration command. 698290001SglebiusWith this 699290001Sglebiuskeyword a volley of messages are exchanged to groom the data and 700290001Sglebiusthe clock is set in about 10 s. 701290001SglebiusIf nothing is heard after a 702290001Sglebiuscouple of minutes, the daemon times out and exits. 703290001SglebiusAfter a suitable 704290001Sglebiusperiod of mourning, the 705290001Sglebius.Xr ntpdate @NTPDATE_MS@ 706290001Sglebiusprogram will be 707290001Sglebiusretired. 708290001Sglebius.Pp 709290001SglebiusWhen kernel support is available to discipline the clock 710290001Sglebiusfrequency, which is the case for stock Solaris, Tru64, Linux and 711290001Sglebius.Fx , 712290001Sglebiusa useful feature is available to discipline the clock 713290001Sglebiusfrequency. 714290001SglebiusFirst, 715290001Sglebius.Nm 716290001Sglebiusis run in continuous mode with 717290001Sglebiusselected servers in order to measure and record the intrinsic clock 718290001Sglebiusfrequency offset in the frequency file. 719290001SglebiusIt may take some hours for 720290001Sglebiusthe frequency and offset to settle down. 721290001SglebiusThen the 722290001Sglebius.Nm 723290001Sglebiusis 724290001Sglebiusstopped and run in one\-time mode as required. 725290001SglebiusAt each startup, the 726290001Sglebiusfrequency is read from the file and initializes the kernel 727290001Sglebiusfrequency. 728290001Sglebius.Ss "Poll Interval Control" 729290001SglebiusThis version of NTP includes an intricate state machine to 730290001Sglebiusreduce the network load while maintaining a quality of 731290001Sglebiussynchronization consistent with the observed jitter and wander. 732290001SglebiusThere are a number of ways to tailor the operation in order enhance 733290001Sglebiusaccuracy by reducing the interval or to reduce network overhead by 734290001Sglebiusincreasing it. 735290001SglebiusHowever, the user is advised to carefully consider 736290001Sglebiusthe consequences of changing the poll adjustment range from the 737290001Sglebiusdefault minimum of 64 s to the default maximum of 1,024 s. 738290001SglebiusThe 739290001Sglebiusdefault minimum can be changed with the 740290001Sglebius.Ic tinker 741290001Sglebius.Cm minpoll 742290001Sglebiuscommand to a value not less than 16 s. 743290001SglebiusThis value is used for all 744290001Sglebiusconfigured associations, unless overridden by the 745290001Sglebius.Cm minpoll 746290001Sglebiusoption on the configuration command. 747290001SglebiusNote that most device drivers 748290001Sglebiuswill not operate properly if the poll interval is less than 64 s 749290001Sglebiusand that the broadcast server and manycast client associations will 750290001Sglebiusalso use the default, unless overridden. 751290001Sglebius.Pp 752290001SglebiusIn some cases involving dial up or toll services, it may be 753290001Sglebiususeful to increase the minimum interval to a few tens of minutes 754290001Sglebiusand maximum interval to a day or so. 755290001SglebiusUnder normal operation 756290001Sglebiusconditions, once the clock discipline loop has stabilized the 757290001Sglebiusinterval will be increased in steps from the minimum to the 758290001Sglebiusmaximum. 759290001SglebiusHowever, this assumes the intrinsic clock frequency error 760290001Sglebiusis small enough for the discipline loop correct it. 761290001SglebiusThe capture 762290001Sglebiusrange of the loop is 500 PPM at an interval of 64s decreasing by a 763290001Sglebiusfactor of two for each doubling of interval. 764290001SglebiusAt a minimum of 1,024 765290001Sglebiuss, for example, the capture range is only 31 PPM. 766290001SglebiusIf the intrinsic 767290001Sglebiuserror is greater than this, the drift file 768290001Sglebius.Pa ntp.drift 769290001Sglebiuswill 770290001Sglebiushave to be specially tailored to reduce the residual error below 771290001Sglebiusthis limit. 772290001SglebiusOnce this is done, the drift file is automatically 773290001Sglebiusupdated once per hour and is available to initialize the frequency 774290001Sglebiuson subsequent daemon restarts. 775290001Sglebius.Ss "The huff\-n'\-puff Filter" 776290001SglebiusIn scenarios where a considerable amount of data are to be 777290001Sglebiusdownloaded or uploaded over telephone modems, timekeeping quality 778290001Sglebiuscan be seriously degraded. 779290001SglebiusThis occurs because the differential 780290001Sglebiusdelays on the two directions of transmission can be quite large. 781290001SglebiusIn 782290001Sglebiusmany cases the apparent time errors are so large as to exceed the 783290001Sglebiusstep threshold and a step correction can occur during and after the 784290001Sglebiusdata transfer is in progress. 785290001Sglebius.Pp 786290001SglebiusThe huff\-n'\-puff filter is designed to correct the apparent time 787290001Sglebiusoffset in these cases. 788290001SglebiusIt depends on knowledge of the propagation 789290001Sglebiusdelay when no other traffic is present. 790290001SglebiusIn common scenarios this 791290001Sglebiusoccurs during other than work hours. 792290001SglebiusThe filter maintains a shift 793290001Sglebiusregister that remembers the minimum delay over the most recent 794290001Sglebiusinterval measured usually in hours. 795290001SglebiusUnder conditions of severe 796290001Sglebiusdelay, the filter corrects the apparent offset using the sign of 797290001Sglebiusthe offset and the difference between the apparent delay and 798290001Sglebiusminimum delay. 799290001SglebiusThe name of the filter reflects the negative (huff) 800290001Sglebiusand positive (puff) correction, which depends on the sign of the 801290001Sglebiusoffset. 802290001Sglebius.Pp 803290001SglebiusThe filter is activated by the 804290001Sglebius.Ic tinker 805290001Sglebiuscommand and 806290001Sglebius.Cm huffpuff 807290001Sglebiuskeyword, as described in 808290001Sglebius.Xr ntp.conf 5 . 809290001Sglebius.Sh "ENVIRONMENT" 810290001SglebiusSee \fBOPTION PRESETS\fP for configuration environment variables. 811290001Sglebius.Sh FILES 812290001Sglebius.Bl -tag -width /etc/ntp.drift -compact 813290001Sglebius.It Pa /etc/ntp.conf 814290001Sglebiusthe default name of the configuration file 815290001Sglebius.It Pa /etc/ntp.drift 816290001Sglebiusthe default name of the drift file 817290001Sglebius.It Pa /etc/ntp.keys 818290001Sglebiusthe default name of the key file 819290001Sglebius.El 820290001Sglebius.Sh "EXIT STATUS" 821290001SglebiusOne of the following exit values will be returned: 822290001Sglebius.Bl -tag 823290001Sglebius.It 0 " (EXIT_SUCCESS)" 824290001SglebiusSuccessful program execution. 825290001Sglebius.It 1 " (EXIT_FAILURE)" 826290001SglebiusThe operation failed or the command syntax was not valid. 827290001Sglebius.It 70 " (EX_SOFTWARE)" 828290001Sglebiuslibopts had an internal operational error. Please report 829290001Sglebiusit to autogen\-users@lists.sourceforge.net. Thank you. 830290001Sglebius.El 831290001Sglebius.Sh "SEE ALSO" 832290001Sglebius.Xr ntp.conf 5 , 833290001Sglebius.Xr ntpdate @NTPDATE_MS@ , 834290001Sglebius.Xr ntpdc @NTPDC_MS@ , 835290001Sglebius.Xr ntpq @NTPQ_MS@ , 836290001Sglebius.Xr sntp @SNTP_MS@ 837290001Sglebius.Pp 838290001SglebiusIn addition to the manual pages provided, 839290001Sglebiuscomprehensive documentation is available on the world wide web 840290001Sglebiusat 841290001Sglebius.Li http://www.ntp.org/ . 842290001SglebiusA snapshot of this documentation is available in HTML format in 843290001Sglebius.Pa /usr/share/doc/ntp . 844290001Sglebius.Rs 845290001Sglebius.%A David L. Mills 846290001Sglebius.%T Network Time Protocol (Version 1) 847290001Sglebius.%O RFC1059 848290001Sglebius.Re 849290001Sglebius.Rs 850290001Sglebius.%A David L. Mills 851290001Sglebius.%T Network Time Protocol (Version 2) 852290001Sglebius.%O RFC1119 853290001Sglebius.Re 854290001Sglebius.Rs 855290001Sglebius.%A David L. Mills 856290001Sglebius.%T Network Time Protocol (Version 3) 857290001Sglebius.%O RFC1305 858290001Sglebius.Re 859290001Sglebius.Rs 860290001Sglebius.%A David L. Mills 861290001Sglebius.%A J. Martin, Ed. 862290001Sglebius.%A J. Burbank 863290001Sglebius.%A W. Kasch 864290001Sglebius.%T Network Time Protocol Version 4: Protocol and Algorithms Specification 865290001Sglebius.%O RFC5905 866290001Sglebius.Re 867290001Sglebius.Rs 868290001Sglebius.%A David L. Mills 869290001Sglebius.%A B. Haberman, Ed. 870290001Sglebius.%T Network Time Protocol Version 4: Autokey Specification 871290001Sglebius.%O RFC5906 872290001Sglebius.Re 873290001Sglebius.Rs 874290001Sglebius.%A H. Gerstung 875290001Sglebius.%A C. Elliott 876290001Sglebius.%A B. Haberman, Ed. 877290001Sglebius.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) 878290001Sglebius.%O RFC5907 879290001Sglebius.Re 880290001Sglebius.Rs 881290001Sglebius.%A R. Gayraud 882290001Sglebius.%A B. Lourdelet 883290001Sglebius.%T Network Time Protocol (NTP) Server Option for DHCPv6 884290001Sglebius.%O RFC5908 885290001Sglebius.Re 886290001Sglebius.Sh "AUTHORS" 887290001SglebiusThe University of Delaware and Network Time Foundation 888290001Sglebius.Sh "COPYRIGHT" 889294905SdelphijCopyright (C) 1992\-2016 The University of Delaware and Network Time Foundation all rights reserved. 890290001SglebiusThis program is released under the terms of the NTP license, <http://ntp.org/license>. 891290001Sglebius.Sh BUGS 892290001SglebiusThe 893290001Sglebius.Nm 894290001Sglebiusutility has gotten rather fat. 895290001SglebiusWhile not huge, it has gotten 896290001Sglebiuslarger than might be desirable for an elevated\-priority 897290001Sglebius.Nm 898290001Sglebiusrunning on a workstation, particularly since many of 899290001Sglebiusthe fancy features which consume the space were designed more with 900290001Sglebiusa busy primary server, rather than a high stratum workstation in 901290001Sglebiusmind. 902290001Sglebius.Pp 903290001SglebiusPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org 904290001Sglebius.Sh NOTES 905290001SglebiusPortions of this document came from FreeBSD. 906290001Sglebius.Pp 907290001SglebiusThis manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP 908290001Sglebiusoption definitions. 909