ntpd.8 revision 293894
1130803Smarcel.Dd January 7 2016 2130803Smarcel.Dt NTPD 8 User Commands 3130803Smarcel.Os 4130803Smarcel.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) 5130803Smarcel.\" 6130803Smarcel.\" $FreeBSD: releng/10.1/usr.sbin/ntp/doc/ntpd.8 293894 2016-01-14 09:11:16Z glebius $ 7130803Smarcel.\" 8130803Smarcel.\" It has been AutoGen-ed January 7, 2016 at 11:31:02 PM by AutoGen 5.18.5 9130803Smarcel.\" From the definitions ntpd-opts.def 10130803Smarcel.\" and the template file agmdoc-cmd.tpl 11130803Smarcel.Sh NAME 12130803Smarcel.Nm ntpd 13130803Smarcel.Nd NTP daemon program 14130803Smarcel.Sh SYNOPSIS 15130803Smarcel.Nm 16130803Smarcel.\" Mixture of short (flag) options and long options 17130803Smarcel.Op Fl flags 18130803Smarcel.Op Fl flag Op Ar value 19130803Smarcel.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 20130803Smarcel[ <server1> ... <serverN> ] 21130803Smarcel.Pp 22130803Smarcel.Sh DESCRIPTION 23130803SmarcelThe 24130803Smarcel.Nm 25130803Smarcelutility is an operating system daemon which sets 26130803Smarceland maintains the system time of day in synchronism with Internet 27130803Smarcelstandard time servers. 28130803SmarcelIt is a complete implementation of the 29130803SmarcelNetwork Time Protocol (NTP) version 4, as defined by RFC\-5905, 30130803Smarcelbut also retains compatibility with 31130803Smarcelversion 3, as defined by RFC\-1305, and versions 1 32130803Smarceland 2, as defined by RFC\-1059 and RFC\-1119, respectively. 33130803Smarcel.Pp 34130803SmarcelThe 35130803Smarcel.Nm 36130803Smarcelutility does most computations in 64\-bit floating point 37130803Smarcelarithmetic and does relatively clumsy 64\-bit fixed point operations 38130803Smarcelonly when necessary to preserve the ultimate precision, about 232 39130803Smarcelpicoseconds. 40130803SmarcelWhile the ultimate precision is not achievable with 41130803Smarcelordinary workstations and networks of today, it may be required 42130803Smarcelwith future gigahertz CPU clocks and gigabit LANs. 43130803Smarcel.Pp 44130803SmarcelOrdinarily, 45130803Smarcel.Nm 46130803Smarcelreads the 47130803Smarcel.Xr ntp.conf 5 48130803Smarcelconfiguration file at startup time in order to determine the 49130803Smarcelsynchronization sources and operating modes. 50130803SmarcelIt is also possible to 51130803Smarcelspecify a working, although limited, configuration entirely on the 52130803Smarcelcommand line, obviating the need for a configuration file. 53130803SmarcelThis may 54130803Smarcelbe particularly useful when the local host is to be configured as a 55130803Smarcelbroadcast/multicast client, with all peers being determined by 56130803Smarcellistening to broadcasts at run time. 57130803Smarcel.Pp 58130803SmarcelIf NetInfo support is built into 59130803Smarcel.Nm , 60130803Smarcelthen 61130803Smarcel.Nm 62130803Smarcelwill attempt to read its configuration from the 63130803SmarcelNetInfo if the default 64130803Smarcel.Xr ntp.conf 5 65130803Smarcelfile cannot be read and no file is 66130803Smarcelspecified by the 67130803Smarcel.Fl c 68130803Smarceloption. 69130803Smarcel.Pp 70130803SmarcelVarious internal 71130803Smarcel.Nm 72130803Smarcelvariables can be displayed and 73130803Smarcelconfiguration options altered while the 74130803Smarcel.Nm 75130803Smarcelis running 76130803Smarcelusing the 77130803Smarcel.Xr ntpq 8 78130803Smarceland 79130803Smarcel.Xr ntpdc 8 80130803Smarcelutility programs. 81130803Smarcel.Pp 82130803SmarcelWhen 83130803Smarcel.Nm 84130803Smarcelstarts it looks at the value of 85130803Smarcel.Xr umask 2 , 86130803Smarceland if zero 87130803Smarcel.Nm 88130803Smarcelwill set the 89130803Smarcel.Xr umask 2 90130803Smarcelto 022. 91130803Smarcel.Sh "OPTIONS" 92130803Smarcel.Bl -tag 93130803Smarcel.It Fl 4 , Fl \-ipv4 94130803SmarcelForce IPv4 DNS name resolution. 95130803SmarcelThis option must not appear in combination with any of the following options: 96130803Smarcelipv6. 97130803Smarcel.sp 98130803SmarcelForce DNS resolution of following host names on the command line 99130803Smarcelto the IPv4 namespace. 100130803Smarcel.It Fl 6 , Fl \-ipv6 101130803SmarcelForce IPv6 DNS name resolution. 102130803SmarcelThis option must not appear in combination with any of the following options: 103130803Smarcelipv4. 104130803Smarcel.sp 105130803SmarcelForce DNS resolution of following host names on the command line 106130803Smarcelto the IPv6 namespace. 107130803Smarcel.It Fl a , Fl \-authreq 108130803SmarcelRequire crypto authentication. 109130803SmarcelThis option must not appear in combination with any of the following options: 110130803Smarcelauthnoreq. 111130803Smarcel.sp 112130803SmarcelRequire cryptographic authentication for broadcast client, 113130803Smarcelmulticast client and symmetric passive associations. 114130803SmarcelThis is the default. 115130803Smarcel.It Fl A , Fl \-authnoreq 116130803SmarcelDo not require crypto authentication. 117130803SmarcelThis option must not appear in combination with any of the following options: 118130803Smarcelauthreq. 119130803Smarcel.sp 120130803SmarcelDo not require cryptographic authentication for broadcast client, 121130803Smarcelmulticast client and symmetric passive associations. 122130803SmarcelThis is almost never a good idea. 123130803Smarcel.It Fl b , Fl \-bcastsync 124130803SmarcelAllow us to sync to broadcast servers. 125130803Smarcel.sp 126130803Smarcel.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string 127130803Smarcelconfiguration file name. 128130803Smarcel.sp 129130803SmarcelThe name and path of the configuration file, 130130803Smarcel\fI/etc/ntp.conf\fP 131130803Smarcelby default. 132130803Smarcel.It Fl d , Fl \-debug\-level 133130803SmarcelIncrease debug verbosity level. 134130803SmarcelThis option may appear an unlimited number of times. 135130803Smarcel.sp 136130803Smarcel.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 137130803SmarcelSet the debug verbosity level. 138130803SmarcelThis option may appear an unlimited number of times. 139130803SmarcelThis option takes an integer number as its argument. 140130803Smarcel.sp 141130803Smarcel.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string 142130803Smarcelfrequency drift file name. 143130803Smarcel.sp 144130803SmarcelThe name and path of the frequency file, 145130803Smarcel\fI/etc/ntp.drift\fP 146130803Smarcelby default. 147130803SmarcelThis is the same operation as the 148130803Smarcel\fBdriftfile\fP \fIdriftfile\fP 149130803Smarcelconfiguration specification in the 150130803Smarcel\fI/etc/ntp.conf\fP 151130803Smarcelfile. 152130803Smarcel.It Fl g , Fl \-panicgate 153130803SmarcelAllow the first adjustment to be Big. 154130803SmarcelThis option may appear an unlimited number of times. 155130803Smarcel.sp 156130803SmarcelNormally, 157130803Smarcel\fBntpd\fP 158130803Smarcelexits 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, 159130803Smarcel\fBntpd\fP 160130803Smarcelwill exit with a message to the system log. This option can be used with the 161130803Smarcel\fB\-q\fP 162130803Smarceland 163130803Smarcel\fB\-x\fP 164130803Smarceloptions. 165130803SmarcelSee the 166130803Smarcel\fBtinker\fP 167130803Smarcelconfiguration file directive for other options. 168130803Smarcel.It Fl G , Fl \-force\-step\-once 169130803SmarcelStep any initial offset correction.. 170130803Smarcel.sp 171130803SmarcelNormally, 172130803Smarcel\fBntpd\fP 173130803Smarcelsteps the time if the time offset exceeds the step threshold, 174130803Smarcelwhich is 128 ms by default, and otherwise slews the time. 175130803SmarcelThis option forces the initial offset correction to be stepped, 176130803Smarcelso the highest time accuracy can be achieved quickly. 177130803SmarcelHowever, this may also cause the time to be stepped back 178130803Smarcelso this option must not be used if 179130803Smarcelapplications requiring monotonic time are running. 180130803SmarcelSee the \fBtinker\fP configuration file directive for other options. 181130803Smarcel.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string 182130803SmarcelJail directory. 183130803Smarcel.sp 184130803SmarcelChroot the server to the directory 185130803Smarcel\fIjaildir\fP 186130803Smarcel. 187130803SmarcelThis option also implies that the server attempts to drop root privileges at startup. 188130803SmarcelYou may need to also specify a 189130803Smarcel\fB\-u\fP 190130803Smarceloption. 191130803SmarcelThis option is only available if the OS supports adjusting the clock 192130803Smarcelwithout full root privileges. 193130803SmarcelThis option is supported under NetBSD (configure with 194130803Smarcel\fB\-\-enable\-clockctl\fP) or Linux (configure with 195130803Smarcel\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 196130803Smarcel.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface 197130803SmarcelListen on an interface name or address. 198130803SmarcelThis option may appear an unlimited number of times. 199130803Smarcel.sp 200130803SmarcelOpen the network address given, or all the addresses associated with the 201130803Smarcelgiven interface name. This option may appear multiple times. This option 202130803Smarcelalso implies not opening other addresses, except wildcard and localhost. 203130803SmarcelThis option is deprecated. Please consider using the configuration file 204130803Smarcel\fBinterface\fP command, which is more versatile. 205130803Smarcel.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string 206130803Smarcelpath to symmetric keys. 207130803Smarcel.sp 208130803SmarcelSpecify the name and path of the symmetric key file. 209130803Smarcel\fI/etc/ntp.keys\fP 210130803Smarcelis the default. 211130803SmarcelThis is the same operation as the 212130803Smarcel\fBkeys\fP \fIkeyfile\fP 213130803Smarcelconfiguration file directive. 214130803Smarcel.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string 215130803Smarcelpath to the log file. 216130803Smarcel.sp 217130803SmarcelSpecify the name and path of the log file. 218130803SmarcelThe default is the system log file. 219130803SmarcelThis is the same operation as the 220130803Smarcel\fBlogfile\fP \fIlogfile\fP 221130803Smarcelconfiguration file directive. 222130803Smarcel.It Fl L , Fl \-novirtualips 223130803SmarcelDo not listen to virtual interfaces. 224130803Smarcel.sp 225130803SmarcelDo not listen to virtual interfaces, defined as those with 226130803Smarcelnames containing a colon. This option is deprecated. Please 227130803Smarcelconsider using the configuration file \fBinterface\fP command, which 228130803Smarcelis more versatile. 229130803Smarcel.It Fl M , Fl \-modifymmtimer 230130803SmarcelModify Multimedia Timer (Windows only). 231130803Smarcel.sp 232130803SmarcelSet the Windows Multimedia Timer to highest resolution. This 233130803Smarcelensures the resolution does not change while ntpd is running, 234130803Smarcelavoiding timekeeping glitches associated with changes. 235130803Smarcel.It Fl n , Fl \-nofork 236130803SmarcelDo not fork. 237130803SmarcelThis option must not appear in combination with any of the following options: 238130803Smarcelwait\-sync. 239130803Smarcel.sp 240130803Smarcel.It Fl N , Fl \-nice 241130803SmarcelRun at high priority. 242130803Smarcel.sp 243130803SmarcelTo the extent permitted by the operating system, run 244130803Smarcel\fBntpd\fP 245130803Smarcelat the highest priority. 246130803Smarcel.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string 247130803Smarcelpath to the PID file. 248130803Smarcel.sp 249130803SmarcelSpecify the name and path of the file used to record 250130803Smarcel\fBntpd\fP's 251130803Smarcelprocess ID. 252130803SmarcelThis is the same operation as the 253130803Smarcel\fBpidfile\fP \fIpidfile\fP 254130803Smarcelconfiguration file directive. 255130803Smarcel.It Fl P Ar number , Fl \-priority Ns = Ns Ar number 256130803SmarcelProcess priority. 257130803SmarcelThis option takes an integer number as its argument. 258130803Smarcel.sp 259130803SmarcelTo the extent permitted by the operating system, run 260130803Smarcel\fBntpd\fP 261130803Smarcelat the specified 262130803Smarcel\fBsched_setscheduler(SCHED_FIFO)\fP 263130803Smarcelpriority. 264130803Smarcel.It Fl q , Fl \-quit 265130803SmarcelSet the time and quit. 266130803SmarcelThis option must not appear in combination with any of the following options: 267130803Smarcelsaveconfigquit, wait\-sync. 268130803Smarcel.sp 269130803Smarcel\fBntpd\fP 270130803Smarcelwill not daemonize and will exit after the clock is first 271130803Smarcelsynchronized. This behavior mimics that of the 272130803Smarcel\fBntpdate\fP 273130803Smarcelprogram, which will soon be replaced with a shell script. 274130803SmarcelThe 275130803Smarcel\fB\-g\fP 276130803Smarceland 277130803Smarcel\fB\-x\fP 278130803Smarceloptions can be used with this option. 279130803SmarcelNote: The kernel time discipline is disabled with this option. 280130803Smarcel.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string 281130803SmarcelBroadcast/propagation delay. 282130803Smarcel.sp 283130803SmarcelSpecify 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. 284130803Smarcel.It Fl \-saveconfigquit Ns = Ns Ar string 285130803SmarcelSave parsed configuration and quit. 286130803SmarcelThis option must not appear in combination with any of the following options: 287130803Smarcelquit, wait\-sync. 288130803Smarcel.sp 289130803SmarcelCause \fBntpd\fP to parse its startup configuration file and save an 290130803Smarcelequivalent to the given filename and exit. This option was 291130803Smarceldesigned for automated testing. 292130803Smarcel.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string 293130803SmarcelStatistics file location. 294130803Smarcel.sp 295130803SmarcelSpecify the directory path for files created by the statistics facility. 296130803SmarcelThis is the same operation as the 297130803Smarcel\fBstatsdir\fP \fIstatsdir\fP 298130803Smarcelconfiguration file directive. 299130803Smarcel.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey 300130803SmarcelTrusted key number. 301130803SmarcelThis option may appear an unlimited number of times. 302130803Smarcel.sp 303130803SmarcelAdd the specified key number to the trusted key list. 304130803Smarcel.It Fl u Ar string , Fl \-user Ns = Ns Ar string 305130803SmarcelRun as userid (or userid:groupid). 306130803Smarcel.sp 307130803SmarcelSpecify a user, and optionally a group, to switch to. 308130803SmarcelThis option is only available if the OS supports adjusting the clock 309130803Smarcelwithout full root privileges. 310130803SmarcelThis option is supported under NetBSD (configure with 311130803Smarcel\fB\-\-enable\-clockctl\fP) or Linux (configure with 312130803Smarcel\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 313130803Smarcel.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number 314130803Smarcelinterval in seconds between scans for new or dropped interfaces. 315130803SmarcelThis option takes an integer number as its argument. 316130803Smarcel.sp 317130803SmarcelGive the time in seconds between two scans for new or dropped interfaces. 318130803SmarcelFor systems with routing socket support the scans will be performed shortly after the interface change 319130803Smarcelhas been detected by the system. 320130803SmarcelUse 0 to disable scanning. 60 seconds is the minimum time between scans. 321130803Smarcel.It Fl \-var Ns = Ns Ar nvar 322130803Smarcelmake ARG an ntp variable (RW). 323130803SmarcelThis option may appear an unlimited number of times. 324130803Smarcel.sp 325130803Smarcel.It Fl \-dvar Ns = Ns Ar ndvar 326130803Smarcelmake ARG an ntp variable (RW|DEF). 327130803SmarcelThis option may appear an unlimited number of times. 328130803Smarcel.sp 329130803Smarcel.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number 330130803SmarcelSeconds to wait for first clock sync. 331130803SmarcelThis option must not appear in combination with any of the following options: 332130803Smarcelnofork, quit, saveconfigquit. 333130803SmarcelThis option takes an integer number as its argument. 334130803Smarcel.sp 335130803SmarcelIf greater than zero, alters \fBntpd\fP's behavior when forking to 336130803Smarceldaemonize. Instead of exiting with status 0 immediately after 337130803Smarcelthe fork, the parent waits up to the specified number of 338130803Smarcelseconds for the child to first synchronize the clock. The exit 339130803Smarcelstatus is zero (success) if the clock was synchronized, 340130803Smarcelotherwise it is \fBETIMEDOUT\fP. 341130803SmarcelThis provides the option for a script starting \fBntpd\fP to easily 342130803Smarcelwait for the first set of the clock before proceeding. 343130803Smarcel.It Fl x , Fl \-slew 344130803SmarcelSlew up to 600 seconds. 345130803Smarcel.sp 346130803SmarcelNormally, 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. 347130803SmarcelThis option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 348130803SmarcelNote: 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. 349130803SmarcelThus, an adjustment as much as 600 s will take almost 14 days to complete. 350130803SmarcelThis option can be used with the 351130803Smarcel\fB\-g\fP 352130803Smarceland 353130803Smarcel\fB\-q\fP 354130803Smarceloptions. 355130803SmarcelSee the 356130803Smarcel\fBtinker\fP 357130803Smarcelconfiguration file directive for other options. 358130803SmarcelNote: The kernel time discipline is disabled with this option. 359130803Smarcel.It Fl \-usepcc 360130803SmarcelUse CPU cycle counter (Windows only). 361130803Smarcel.sp 362130803SmarcelAttempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 363130803SmarcelThe CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 364130803Smarcelthey have the same frequency, the CPU counter (RDTSC on x86) is 365130803Smarcelused directly, saving the overhead of a system call. 366130803Smarcel.It Fl \-pccfreq Ns = Ns Ar string 367130803SmarcelForce CPU cycle counter use (Windows only). 368130803Smarcel.sp 369130803SmarcelForce substitution the CPU counter for \fBQueryPerformanceCounter\fP. 370130803SmarcelThe CPU counter (RDTSC on x86) is used unconditionally with the 371130803Smarcelgiven frequency (in Hz). 372130803Smarcel.It Fl m , Fl \-mdns 373130803SmarcelRegister with mDNS as a NTP server. 374130803Smarcel.sp 375130803SmarcelRegisters as an NTP server with the local mDNS server which allows 376130803Smarcelthe server to be discovered via mDNS client lookup. 377130803Smarcel.It Fl \&? , Fl \-help 378130803SmarcelDisplay usage information and exit. 379130803Smarcel.It Fl \&! , Fl \-more\-help 380130803SmarcelPass the extended usage information through a pager. 381130803Smarcel.It Fl \-version Op Brq Ar v|c|n 382130803SmarcelOutput version of program and exit. The default mode is `v', a simple 383130803Smarcelversion. The `c' mode will print copyright information and `n' will 384130803Smarcelprint the full copyright notice. 385130803Smarcel.El 386130803Smarcel.Sh "OPTION PRESETS" 387130803SmarcelAny option that is not marked as \fInot presettable\fP may be preset 388130803Smarcelby loading values from environment variables named: 389130803Smarcel.nf 390130803Smarcel \fBNTPD_<option\-name>\fP or \fBNTPD\fP 391130803Smarcel.fi 392130803Smarcel.ad 393130803Smarcel.Sh USAGE 394130803Smarcel.Ss "How NTP Operates" 395130803SmarcelThe 396130803Smarcel.Nm 397130803Smarcelutility operates by exchanging messages with 398130803Smarcelone or more configured servers over a range of designated poll intervals. 399130803SmarcelWhen 400130803Smarcelstarted, whether for the first or subsequent times, the program 401130803Smarcelrequires several exchanges from the majority of these servers so 402130803Smarcelthe signal processing and mitigation algorithms can accumulate and 403130803Smarcelgroom the data and set the clock. 404130803SmarcelIn order to protect the network 405130803Smarcelfrom bursts, the initial poll interval for each server is delayed 406130803Smarcelan interval randomized over a few seconds. 407130803SmarcelAt the default initial poll 408130803Smarcelinterval of 64s, several minutes can elapse before the clock is 409130803Smarcelset. 410130803SmarcelThis initial delay to set the clock 411130803Smarcelcan be safely and dramatically reduced using the 412130803Smarcel.Cm iburst 413130803Smarcelkeyword with the 414130803Smarcel.Ic server 415130803Smarcelconfiguration 416130803Smarcelcommand, as described in 417130803Smarcel.Xr ntp.conf 5 . 418130803Smarcel.Pp 419130803SmarcelMost operating systems and hardware of today incorporate a 420130803Smarceltime\-of\-year (TOY) chip to maintain the time during periods when 421130803Smarcelthe power is off. 422130803SmarcelWhen the machine is booted, the chip is used to 423130803Smarcelinitialize the operating system time. 424130803SmarcelAfter the machine has 425130803Smarcelsynchronized to a NTP server, the operating system corrects the 426130803Smarcelchip from time to time. 427130803SmarcelIn the default case, if 428130803Smarcel.Nm 429130803Smarceldetects that the time on the host 430130803Smarcelis more than 1000s from the server time, 431130803Smarcel.Nm 432130803Smarcelassumes something must be terribly wrong and the only 433130803Smarcelreliable action is for the operator to intervene and set the clock 434130803Smarcelby hand. 435130803Smarcel(Reasons for this include there is no TOY chip, 436130803Smarcelor its battery is dead, or that the TOY chip is just of poor quality.) 437130803SmarcelThis causes 438130803Smarcel.Nm 439130803Smarcelto exit with a panic message to 440130803Smarcelthe system log. 441130803SmarcelThe 442130803Smarcel.Fl g 443130803Smarceloption overrides this check and the 444130803Smarcelclock will be set to the server time regardless of the chip time 445130803Smarcel(up to 68 years in the past or future \(em 446130803Smarcelthis is a limitation of the NTPv4 protocol). 447130803SmarcelHowever, and to protect against broken hardware, such as when the 448130803SmarcelCMOS battery fails or the clock counter becomes defective, once the 449130803Smarcelclock has been set an error greater than 1000s will cause 450130803Smarcel.Nm 451130803Smarcelto exit anyway. 452130803Smarcel.Pp 453130803SmarcelUnder ordinary conditions, 454130803Smarcel.Nm 455130803Smarceladjusts the clock in 456130803Smarcelsmall steps so that the timescale is effectively continuous and 457130803Smarcelwithout discontinuities. 458130803SmarcelUnder conditions of extreme network 459130803Smarcelcongestion, the roundtrip delay jitter can exceed three seconds and 460130803Smarcelthe synchronization distance, which is equal to one\-half the 461130803Smarcelroundtrip delay plus error budget terms, can become very large. 462130803SmarcelThe 463130803Smarcel.Nm 464130803Smarcelalgorithms discard sample offsets exceeding 128 ms, 465130803Smarcelunless the interval during which no sample offset is less than 128 466130803Smarcelms exceeds 900s. 467130803SmarcelThe first sample after that, no matter what the 468130803Smarceloffset, steps the clock to the indicated time. 469130803SmarcelIn practice this 470130803Smarcelreduces the false alarm rate where the clock is stepped in error to 471130803Smarcela vanishingly low incidence. 472130803Smarcel.Pp 473130803SmarcelAs the result of this behavior, once the clock has been set it 474130803Smarcelvery rarely strays more than 128 ms even under extreme cases of 475130803Smarcelnetwork path congestion and jitter. 476130803SmarcelSometimes, in particular when 477130803Smarcel.Nm 478130803Smarcelis first started without a valid drift file 479130803Smarcelon a system with a large intrinsic drift 480130803Smarcelthe error might grow to exceed 128 ms, 481130803Smarcelwhich would cause the clock to be set backwards 482130803Smarcelif the local clock time is more than 128 s 483130803Smarcelin the future relative to the server. 484130803SmarcelIn some applications, this behavior may be unacceptable. 485130803SmarcelThere are several solutions, however. 486130803SmarcelIf the 487130803Smarcel.Fl x 488130803Smarceloption is included on the command line, the clock will 489130803Smarcelnever be stepped and only slew corrections will be used. 490130803SmarcelBut this choice comes with a cost that 491130803Smarcelshould be carefully explored before deciding to use 492130803Smarcelthe 493130803Smarcel.Fl x 494130803Smarceloption. 495130803SmarcelThe maximum slew rate possible is limited 496130803Smarcelto 500 parts\-per\-million (PPM) as a consequence of the correctness 497130803Smarcelprinciples on which the NTP protocol and algorithm design are 498130803Smarcelbased. 499130803SmarcelAs a result, the local clock can take a long time to 500130803Smarcelconverge to an acceptable offset, about 2,000 s for each second the 501130803Smarcelclock is outside the acceptable range. 502130803SmarcelDuring this interval the 503130803Smarcellocal clock will not be consistent with any other network clock and 504130803Smarcelthe system cannot be used for distributed applications that require 505130803Smarcelcorrectly synchronized network time. 506130803Smarcel.Pp 507130803SmarcelIn spite of the above precautions, sometimes when large 508130803Smarcelfrequency errors are present the resulting time offsets stray 509130803Smarceloutside the 128\-ms range and an eventual step or slew time 510130803Smarcelcorrection is required. 511130803SmarcelIf following such a correction the 512130803Smarcelfrequency error is so large that the first sample is outside the 513130803Smarcelacceptable range, 514130803Smarcel.Nm 515130803Smarcelenters the same state as when the 516130803Smarcel.Pa ntp.drift 517130803Smarcelfile is not present. 518130803SmarcelThe intent of this behavior 519130803Smarcelis to quickly correct the frequency and restore operation to the 520130803Smarcelnormal tracking mode. 521130803SmarcelIn the most extreme cases 522130803Smarcel(the host 523130803Smarcel.Cm time.ien.it 524130803Smarcelcomes to mind), there may be occasional 525130803Smarcelstep/slew corrections and subsequent frequency corrections. 526130803SmarcelIt 527130803Smarcelhelps in these cases to use the 528130803Smarcel.Cm burst 529130803Smarcelkeyword when 530130803Smarcelconfiguring the server, but 531130803SmarcelONLY 532130803Smarcelwhen you have permission to do so from the owner of the target host. 533130803Smarcel.Pp 534130803SmarcelFinally, 535130803Smarcelin the past many startup scripts would run 536130803Smarcel.Xr ntpdate 8 537130803Smarcelor 538130803Smarcel.Xr sntp 8 539130803Smarcelto get the system clock close to correct before starting 540130803Smarcel.Xr ntpd 8 , 541130803Smarcelbut this was never more than a mediocre hack and is no longer needed. 542130803SmarcelIf you are following the instructions in 543130803Smarcel.Sx "Starting NTP (Best Current Practice)" 544130803Smarceland you still need to set the system time before starting 545130803Smarcel.Nm , 546130803Smarcelplease open a bug report and document what is going on, 547130803Smarceland then look at using 548130803Smarcel.Xr sntp 8 549130803Smarcelif you really need to set the clock before starting 550130803Smarcel.Nm . 551130803Smarcel.Pp 552130803SmarcelThere is a way to start 553130803Smarcel.Xr ntpd 8 554130803Smarcelthat often addresses all of the problems mentioned above. 555130803Smarcel.Ss "Starting NTP (Best Current Practice)" 556130803SmarcelFirst, use the 557130803Smarcel.Cm iburst 558130803Smarceloption on your 559130803Smarcel.Cm server 560130803Smarcelentries. 561130803Smarcel.Pp 562130803SmarcelIf you can also keep a good 563130803Smarcel.Pa ntp.drift 564130803Smarcelfile then 565130803Smarcel.Xr ntpd 8 566130803Smarcelwill effectively "warm\-start" and your system's clock will 567130803Smarcelbe stable in under 11 seconds' time. 568130803Smarcel.Pp 569130803SmarcelAs soon as possible in the startup sequence, start 570130803Smarcel.Xr ntpd 8 571130803Smarcelwith at least the 572130803Smarcel.Fl g 573130803Smarceland perhaps the 574130803Smarcel.Fl N 575130803Smarceloptions. 576130803SmarcelThen, 577130803Smarcelstart the rest of your "normal" processes. 578130803SmarcelThis will give 579130803Smarcel.Xr ntpd 8 580130803Smarcelas much time as possible to get the system's clock synchronized and stable. 581130803Smarcel.Pp 582130803SmarcelFinally, 583130803Smarcelif you have processes like 584130803Smarcel.Cm dovecot 585130803Smarcelor database servers 586130803Smarcelthat require 587130803Smarcelmonotonically\-increasing time, 588130803Smarcelrun 589130803Smarcel.Xr ntp\-wait 1ntp\-waitmdoc 590130803Smarcelas late as possible in the boot sequence 591130803Smarcel(perhaps with the 592130803Smarcel.Fl v 593130803Smarcelflag) 594130803Smarceland after 595130803Smarcel.Xr ntp\-wait 1ntp\-waitmdoc 596130803Smarcelexits successfully 597130803Smarcelit is as safe as it will ever be to start any process that require 598130803Smarcelstable time. 599130803Smarcel.Ss "Frequency Discipline" 600130803SmarcelThe 601130803Smarcel.Nm 602130803Smarcelbehavior at startup depends on whether the 603130803Smarcelfrequency file, usually 604130803Smarcel.Pa ntp.drift , 605130803Smarcelexists. 606130803SmarcelThis file 607130803Smarcelcontains the latest estimate of clock frequency error. 608130803SmarcelWhen the 609130803Smarcel.Nm 610130803Smarcelis started and the file does not exist, the 611130803Smarcel.Nm 612130803Smarcelenters a special mode designed to quickly adapt to 613130803Smarcelthe particular system clock oscillator time and frequency error. 614130803SmarcelThis takes approximately 15 minutes, after which the time and 615130803Smarcelfrequency are set to nominal values and the 616130803Smarcel.Nm 617130803Smarcelenters 618130803Smarcelnormal mode, where the time and frequency are continuously tracked 619130803Smarcelrelative to the server. 620130803SmarcelAfter one hour the frequency file is 621130803Smarcelcreated and the current frequency offset written to it. 622130803SmarcelWhen the 623130803Smarcel.Nm 624130803Smarcelis started and the file does exist, the 625130803Smarcel.Nm 626130803Smarcelfrequency is initialized from the file and enters normal mode 627130803Smarcelimmediately. 628130803SmarcelAfter that the current frequency offset is written to 629130803Smarcelthe file at hourly intervals. 630130803Smarcel.Ss "Operating Modes" 631130803SmarcelThe 632130803Smarcel.Nm 633130803Smarcelutility can operate in any of several modes, including 634130803Smarcelsymmetric active/passive, client/server broadcast/multicast and 635130803Smarcelmanycast, as described in the 636130803Smarcel.Qq Association Management 637130803Smarcelpage 638130803Smarcel(available as part of the HTML documentation 639130803Smarcelprovided in 640130803Smarcel.Pa /usr/share/doc/ntp ) . 641130803SmarcelIt normally operates continuously while 642130803Smarcelmonitoring for small changes in frequency and trimming the clock 643130803Smarcelfor the ultimate precision. 644130803SmarcelHowever, it can operate in a one\-time 645130803Smarcelmode where the time is set from an external server and frequency is 646130803Smarcelset from a previously recorded frequency file. 647130803SmarcelA 648130803Smarcelbroadcast/multicast or manycast client can discover remote servers, 649130803Smarcelcompute server\-client propagation delay correction factors and 650130803Smarcelconfigure itself automatically. 651130803SmarcelThis makes it possible to deploy a 652130803Smarcelfleet of workstations without specifying configuration details 653130803Smarcelspecific to the local environment. 654130803Smarcel.Pp 655130803SmarcelBy default, 656130803Smarcel.Nm 657130803Smarcelruns in continuous mode where each of 658130803Smarcelpossibly several external servers is polled at intervals determined 659130803Smarcelby an intricate state machine. 660130803SmarcelThe state machine measures the 661130803Smarcelincidental roundtrip delay jitter and oscillator frequency wander 662130803Smarceland determines the best poll interval using a heuristic algorithm. 663130803SmarcelOrdinarily, and in most operating environments, the state machine 664130803Smarcelwill start with 64s intervals and eventually increase in steps to 665130803Smarcel1024s. 666130803SmarcelA small amount of random variation is introduced in order to 667130803Smarcelavoid bunching at the servers. 668130803SmarcelIn addition, should a server become 669130803Smarcelunreachable for some time, the poll interval is increased in steps 670130803Smarcelto 1024s in order to reduce network overhead. 671130803Smarcel.Pp 672130803SmarcelIn some cases it may not be practical for 673130803Smarcel.Nm 674130803Smarcelto run continuously. 675130803SmarcelA common workaround has been to run the 676130803Smarcel.Xr ntpdate 8 677130803Smarcelor 678130803Smarcel.Xr sntp 8 679130803Smarcelprograms from a 680130803Smarcel.Xr cron 8 681130803Smarceljob at designated 682130803Smarceltimes. 683130803SmarcelHowever, these programs do not have the crafted signal 684130803Smarcelprocessing, error checking or mitigation algorithms of 685130803Smarcel.Nm . 686130803SmarcelThe 687130803Smarcel.Fl q 688130803Smarceloption is intended for this purpose. 689130803SmarcelSetting this option will cause 690130803Smarcel.Nm 691130803Smarcelto exit just after 692130803Smarcelsetting the clock for the first time. 693130803SmarcelThe procedure for initially 694130803Smarcelsetting the clock is the same as in continuous mode; most 695130803Smarcelapplications will probably want to specify the 696130803Smarcel.Cm iburst 697130803Smarcelkeyword with the 698130803Smarcel.Ic server 699130803Smarcelconfiguration command. 700130803SmarcelWith this 701130803Smarcelkeyword a volley of messages are exchanged to groom the data and 702130803Smarcelthe clock is set in about 10 s. 703130803SmarcelIf nothing is heard after a 704130803Smarcelcouple of minutes, the daemon times out and exits. 705130803SmarcelAfter a suitable 706130803Smarcelperiod of mourning, the 707130803Smarcel.Xr ntpdate 8 708130803Smarcelprogram will be 709130803Smarcelretired. 710130803Smarcel.Pp 711130803SmarcelWhen kernel support is available to discipline the clock 712130803Smarcelfrequency, which is the case for stock Solaris, Tru64, Linux and 713130803Smarcel.Fx , 714130803Smarcela useful feature is available to discipline the clock 715130803Smarcelfrequency. 716130803SmarcelFirst, 717130803Smarcel.Nm 718130803Smarcelis run in continuous mode with 719130803Smarcelselected servers in order to measure and record the intrinsic clock 720130803Smarcelfrequency offset in the frequency file. 721130803SmarcelIt may take some hours for 722130803Smarcelthe frequency and offset to settle down. 723130803SmarcelThen the 724130803Smarcel.Nm 725130803Smarcelis 726130803Smarcelstopped and run in one\-time mode as required. 727130803SmarcelAt each startup, the 728130803Smarcelfrequency is read from the file and initializes the kernel 729130803Smarcelfrequency. 730130803Smarcel.Ss "Poll Interval Control" 731130803SmarcelThis version of NTP includes an intricate state machine to 732130803Smarcelreduce the network load while maintaining a quality of 733130803Smarcelsynchronization consistent with the observed jitter and wander. 734130803SmarcelThere are a number of ways to tailor the operation in order enhance 735130803Smarcelaccuracy by reducing the interval or to reduce network overhead by 736130803Smarcelincreasing it. 737130803SmarcelHowever, the user is advised to carefully consider 738130803Smarcelthe consequences of changing the poll adjustment range from the 739130803Smarceldefault minimum of 64 s to the default maximum of 1,024 s. 740130803SmarcelThe 741130803Smarceldefault minimum can be changed with the 742130803Smarcel.Ic tinker 743130803Smarcel.Cm minpoll 744130803Smarcelcommand to a value not less than 16 s. 745130803SmarcelThis value is used for all 746130803Smarcelconfigured associations, unless overridden by the 747130803Smarcel.Cm minpoll 748130803Smarceloption on the configuration command. 749130803SmarcelNote that most device drivers 750130803Smarcelwill not operate properly if the poll interval is less than 64 s 751130803Smarceland that the broadcast server and manycast client associations will 752130803Smarcelalso use the default, unless overridden. 753130803Smarcel.Pp 754130803SmarcelIn some cases involving dial up or toll services, it may be 755130803Smarceluseful to increase the minimum interval to a few tens of minutes 756130803Smarceland maximum interval to a day or so. 757130803SmarcelUnder normal operation 758130803Smarcelconditions, once the clock discipline loop has stabilized the 759130803Smarcelinterval will be increased in steps from the minimum to the 760130803Smarcelmaximum. 761130803SmarcelHowever, this assumes the intrinsic clock frequency error 762130803Smarcelis small enough for the discipline loop correct it. 763130803SmarcelThe capture 764130803Smarcelrange of the loop is 500 PPM at an interval of 64s decreasing by a 765130803Smarcelfactor of two for each doubling of interval. 766130803SmarcelAt a minimum of 1,024 767130803Smarcels, for example, the capture range is only 31 PPM. 768130803SmarcelIf the intrinsic 769130803Smarcelerror is greater than this, the drift file 770130803Smarcel.Pa ntp.drift 771130803Smarcelwill 772130803Smarcelhave to be specially tailored to reduce the residual error below 773130803Smarcelthis limit. 774130803SmarcelOnce this is done, the drift file is automatically 775130803Smarcelupdated once per hour and is available to initialize the frequency 776130803Smarcelon subsequent daemon restarts. 777130803Smarcel.Ss "The huff\-n'\-puff Filter" 778130803SmarcelIn scenarios where a considerable amount of data are to be 779130803Smarceldownloaded or uploaded over telephone modems, timekeeping quality 780130803Smarcelcan be seriously degraded. 781130803SmarcelThis occurs because the differential 782130803Smarceldelays on the two directions of transmission can be quite large. 783130803SmarcelIn 784130803Smarcelmany cases the apparent time errors are so large as to exceed the 785130803Smarcelstep threshold and a step correction can occur during and after the 786130803Smarceldata transfer is in progress. 787130803Smarcel.Pp 788130803SmarcelThe huff\-n'\-puff filter is designed to correct the apparent time 789130803Smarceloffset in these cases. 790130803SmarcelIt depends on knowledge of the propagation 791130803Smarceldelay when no other traffic is present. 792130803SmarcelIn common scenarios this 793130803Smarceloccurs during other than work hours. 794130803SmarcelThe filter maintains a shift 795130803Smarcelregister that remembers the minimum delay over the most recent 796130803Smarcelinterval measured usually in hours. 797Under conditions of severe 798delay, the filter corrects the apparent offset using the sign of 799the offset and the difference between the apparent delay and 800minimum delay. 801The name of the filter reflects the negative (huff) 802and positive (puff) correction, which depends on the sign of the 803offset. 804.Pp 805The filter is activated by the 806.Ic tinker 807command and 808.Cm huffpuff 809keyword, as described in 810.Xr ntp.conf 5 . 811.Sh "ENVIRONMENT" 812See \fBOPTION PRESETS\fP for configuration environment variables. 813.Sh FILES 814.Bl -tag -width /etc/ntp.drift -compact 815.It Pa /etc/ntp.conf 816the default name of the configuration file 817.It Pa /etc/ntp.drift 818the default name of the drift file 819.It Pa /etc/ntp.keys 820the default name of the key file 821.El 822.Sh "EXIT STATUS" 823One of the following exit values will be returned: 824.Bl -tag 825.It 0 " (EXIT_SUCCESS)" 826Successful program execution. 827.It 1 " (EXIT_FAILURE)" 828The operation failed or the command syntax was not valid. 829.It 70 " (EX_SOFTWARE)" 830libopts had an internal operational error. Please report 831it to autogen\-users@lists.sourceforge.net. Thank you. 832.El 833.Sh "SEE ALSO" 834.Xr ntp.conf 5 , 835.Xr ntpdate 8 , 836.Xr ntpdc 8 , 837.Xr ntpq 8 , 838.Xr sntp 8 839.Pp 840In addition to the manual pages provided, 841comprehensive documentation is available on the world wide web 842at 843.Li http://www.ntp.org/ . 844A snapshot of this documentation is available in HTML format in 845.Pa /usr/share/doc/ntp . 846.Rs 847.%A David L. Mills 848.%T Network Time Protocol (Version 1) 849.%O RFC1059 850.Re 851.Rs 852.%A David L. Mills 853.%T Network Time Protocol (Version 2) 854.%O RFC1119 855.Re 856.Rs 857.%A David L. Mills 858.%T Network Time Protocol (Version 3) 859.%O RFC1305 860.Re 861.Rs 862.%A David L. Mills 863.%A J. Martin, Ed. 864.%A J. Burbank 865.%A W. Kasch 866.%T Network Time Protocol Version 4: Protocol and Algorithms Specification 867.%O RFC5905 868.Re 869.Rs 870.%A David L. Mills 871.%A B. Haberman, Ed. 872.%T Network Time Protocol Version 4: Autokey Specification 873.%O RFC5906 874.Re 875.Rs 876.%A H. Gerstung 877.%A C. Elliott 878.%A B. Haberman, Ed. 879.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) 880.%O RFC5907 881.Re 882.Rs 883.%A R. Gayraud 884.%A B. Lourdelet 885.%T Network Time Protocol (NTP) Server Option for DHCPv6 886.%O RFC5908 887.Re 888.Sh "AUTHORS" 889The University of Delaware and Network Time Foundation 890.Sh "COPYRIGHT" 891Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved. 892This program is released under the terms of the NTP license, <http://ntp.org/license>. 893.Sh BUGS 894The 895.Nm 896utility has gotten rather fat. 897While not huge, it has gotten 898larger than might be desirable for an elevated\-priority 899.Nm 900running on a workstation, particularly since many of 901the fancy features which consume the space were designed more with 902a busy primary server, rather than a high stratum workstation in 903mind. 904.Pp 905Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 906.Sh NOTES 907Portions of this document came from FreeBSD. 908.Pp 909This manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP 910option definitions. 911