1316722Sdelphij.Dd March 21 2017 2275970Scy.Dt NTPD 1ntpdmdoc User Commands 3275970Scy.Os 4275970Scy.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) 5275970Scy.\" 6316722Sdelphij.\" It has been AutoGen-ed March 21, 2017 at 10:44:23 AM by AutoGen 5.18.5 7275970Scy.\" From the definitions ntpd-opts.def 8275970Scy.\" and the template file agmdoc-cmd.tpl 9275970Scy.Sh NAME 10275970Scy.Nm ntpd 11275970Scy.Nd NTP daemon program 12275970Scy.Sh SYNOPSIS 13275970Scy.Nm 14275970Scy.\" Mixture of short (flag) options and long options 15275970Scy.Op Fl flags 16275970Scy.Op Fl flag Op Ar value 17275970Scy.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 18275970Scy[ <server1> ... <serverN> ] 19275970Scy.Pp 20275970Scy.Sh DESCRIPTION 21275970ScyThe 22275970Scy.Nm 23275970Scyutility is an operating system daemon which sets 24275970Scyand maintains the system time of day in synchronism with Internet 25275970Scystandard time servers. 26275970ScyIt is a complete implementation of the 27275970ScyNetwork Time Protocol (NTP) version 4, as defined by RFC\-5905, 28275970Scybut also retains compatibility with 29275970Scyversion 3, as defined by RFC\-1305, and versions 1 30275970Scyand 2, as defined by RFC\-1059 and RFC\-1119, respectively. 31275970Scy.Pp 32275970ScyThe 33275970Scy.Nm 34275970Scyutility does most computations in 64\-bit floating point 35275970Scyarithmetic and does relatively clumsy 64\-bit fixed point operations 36275970Scyonly when necessary to preserve the ultimate precision, about 232 37275970Scypicoseconds. 38275970ScyWhile the ultimate precision is not achievable with 39275970Scyordinary workstations and networks of today, it may be required 40275970Scywith future gigahertz CPU clocks and gigabit LANs. 41275970Scy.Pp 42275970ScyOrdinarily, 43275970Scy.Nm 44275970Scyreads the 45275970Scy.Xr ntp.conf 5 46275970Scyconfiguration file at startup time in order to determine the 47275970Scysynchronization sources and operating modes. 48275970ScyIt is also possible to 49275970Scyspecify a working, although limited, configuration entirely on the 50275970Scycommand line, obviating the need for a configuration file. 51275970ScyThis may 52275970Scybe particularly useful when the local host is to be configured as a 53275970Scybroadcast/multicast client, with all peers being determined by 54275970Scylistening to broadcasts at run time. 55275970Scy.Pp 56275970ScyIf NetInfo support is built into 57275970Scy.Nm , 58275970Scythen 59275970Scy.Nm 60275970Scywill attempt to read its configuration from the 61275970ScyNetInfo if the default 62275970Scy.Xr ntp.conf 5 63275970Scyfile cannot be read and no file is 64275970Scyspecified by the 65275970Scy.Fl c 66275970Scyoption. 67275970Scy.Pp 68275970ScyVarious internal 69275970Scy.Nm 70275970Scyvariables can be displayed and 71275970Scyconfiguration options altered while the 72275970Scy.Nm 73275970Scyis running 74275970Scyusing the 75275970Scy.Xr ntpq 1ntpqmdoc 76275970Scyand 77275970Scy.Xr ntpdc 1ntpdcmdoc 78275970Scyutility programs. 79275970Scy.Pp 80275970ScyWhen 81275970Scy.Nm 82275970Scystarts it looks at the value of 83275970Scy.Xr umask 2 , 84275970Scyand if zero 85275970Scy.Nm 86275970Scywill set the 87275970Scy.Xr umask 2 88275970Scyto 022. 89275970Scy.Sh "OPTIONS" 90275970Scy.Bl -tag 91275970Scy.It Fl 4 , Fl \-ipv4 92275970ScyForce IPv4 DNS name resolution. 93275970ScyThis option must not appear in combination with any of the following options: 94275970Scyipv6. 95275970Scy.sp 96275970ScyForce DNS resolution of following host names on the command line 97275970Scyto the IPv4 namespace. 98275970Scy.It Fl 6 , Fl \-ipv6 99275970ScyForce IPv6 DNS name resolution. 100275970ScyThis option must not appear in combination with any of the following options: 101275970Scyipv4. 102275970Scy.sp 103275970ScyForce DNS resolution of following host names on the command line 104275970Scyto the IPv6 namespace. 105275970Scy.It Fl a , Fl \-authreq 106275970ScyRequire crypto authentication. 107275970ScyThis option must not appear in combination with any of the following options: 108275970Scyauthnoreq. 109275970Scy.sp 110275970ScyRequire cryptographic authentication for broadcast client, 111275970Scymulticast client and symmetric passive associations. 112275970ScyThis is the default. 113275970Scy.It Fl A , Fl \-authnoreq 114275970ScyDo not require crypto authentication. 115275970ScyThis option must not appear in combination with any of the following options: 116275970Scyauthreq. 117275970Scy.sp 118275970ScyDo not require cryptographic authentication for broadcast client, 119275970Scymulticast client and symmetric passive associations. 120275970ScyThis is almost never a good idea. 121275970Scy.It Fl b , Fl \-bcastsync 122275970ScyAllow us to sync to broadcast servers. 123275970Scy.sp 124275970Scy.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string 125275970Scyconfiguration file name. 126275970Scy.sp 127275970ScyThe name and path of the configuration file, 128275970Scy\fI/etc/ntp.conf\fP 129275970Scyby default. 130275970Scy.It Fl d , Fl \-debug\-level 131275970ScyIncrease debug verbosity level. 132275970ScyThis option may appear an unlimited number of times. 133275970Scy.sp 134275970Scy.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 135275970ScySet the debug verbosity level. 136275970ScyThis option may appear an unlimited number of times. 137275970ScyThis option takes an integer number as its argument. 138275970Scy.sp 139275970Scy.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string 140275970Scyfrequency drift file name. 141275970Scy.sp 142275970ScyThe name and path of the frequency file, 143275970Scy\fI/etc/ntp.drift\fP 144275970Scyby default. 145275970ScyThis is the same operation as the 146275970Scy\fBdriftfile\fP \fIdriftfile\fP 147282408Scyconfiguration specification in the 148275970Scy\fI/etc/ntp.conf\fP 149275970Scyfile. 150275970Scy.It Fl g , Fl \-panicgate 151275970ScyAllow the first adjustment to be Big. 152275970ScyThis option may appear an unlimited number of times. 153275970Scy.sp 154275970ScyNormally, 155275970Scy\fBntpd\fP 156275970Scyexits 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, 157275970Scy\fBntpd\fP 158275970Scywill exit with a message to the system log. This option can be used with the 159275970Scy\fB\-q\fP 160275970Scyand 161275970Scy\fB\-x\fP 162275970Scyoptions. 163275970ScySee the 164275970Scy\fBtinker\fP 165275970Scyconfiguration file directive for other options. 166282408Scy.It Fl G , Fl \-force\-step\-once 167282408ScyStep any initial offset correction.. 168282408Scy.sp 169282408ScyNormally, 170282408Scy\fBntpd\fP 171282408Scysteps the time if the time offset exceeds the step threshold, 172282408Scywhich is 128 ms by default, and otherwise slews the time. 173282408ScyThis option forces the initial offset correction to be stepped, 174282408Scyso the highest time accuracy can be achieved quickly. 175282408ScyHowever, this may also cause the time to be stepped back 176282408Scyso this option must not be used if 177282408Scyapplications requiring monotonic time are running. 178282408ScySee the \fBtinker\fP configuration file directive for other options. 179275970Scy.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string 180275970ScyJail directory. 181275970Scy.sp 182275970ScyChroot the server to the directory 183275970Scy\fIjaildir\fP 184275970Scy. 185275970ScyThis option also implies that the server attempts to drop root privileges at startup. 186275970ScyYou may need to also specify a 187275970Scy\fB\-u\fP 188275970Scyoption. 189275970ScyThis option is only available if the OS supports adjusting the clock 190275970Scywithout full root privileges. 191275970ScyThis option is supported under NetBSD (configure with 192275970Scy\fB\-\-enable\-clockctl\fP) or Linux (configure with 193275970Scy\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 194275970Scy.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface 195275970ScyListen on an interface name or address. 196275970ScyThis option may appear an unlimited number of times. 197275970Scy.sp 198275970ScyOpen the network address given, or all the addresses associated with the 199275970Scygiven interface name. This option may appear multiple times. This option 200275970Scyalso implies not opening other addresses, except wildcard and localhost. 201275970ScyThis option is deprecated. Please consider using the configuration file 202282408Scy\fBinterface\fP command, which is more versatile. 203275970Scy.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string 204275970Scypath to symmetric keys. 205275970Scy.sp 206275970ScySpecify the name and path of the symmetric key file. 207275970Scy\fI/etc/ntp.keys\fP 208275970Scyis the default. 209275970ScyThis is the same operation as the 210275970Scy\fBkeys\fP \fIkeyfile\fP 211275970Scyconfiguration file directive. 212275970Scy.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string 213275970Scypath to the log file. 214275970Scy.sp 215275970ScySpecify the name and path of the log file. 216275970ScyThe default is the system log file. 217275970ScyThis is the same operation as the 218275970Scy\fBlogfile\fP \fIlogfile\fP 219275970Scyconfiguration file directive. 220275970Scy.It Fl L , Fl \-novirtualips 221275970ScyDo not listen to virtual interfaces. 222275970Scy.sp 223275970ScyDo not listen to virtual interfaces, defined as those with 224275970Scynames containing a colon. This option is deprecated. Please 225275970Scyconsider using the configuration file \fBinterface\fP command, which 226275970Scyis more versatile. 227275970Scy.It Fl M , Fl \-modifymmtimer 228275970ScyModify Multimedia Timer (Windows only). 229275970Scy.sp 230275970ScySet the Windows Multimedia Timer to highest resolution. This 231275970Scyensures the resolution does not change while ntpd is running, 232275970Scyavoiding timekeeping glitches associated with changes. 233275970Scy.It Fl n , Fl \-nofork 234275970ScyDo not fork. 235275970ScyThis option must not appear in combination with any of the following options: 236275970Scywait\-sync. 237275970Scy.sp 238275970Scy.It Fl N , Fl \-nice 239275970ScyRun at high priority. 240275970Scy.sp 241275970ScyTo the extent permitted by the operating system, run 242275970Scy\fBntpd\fP 243275970Scyat the highest priority. 244275970Scy.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string 245275970Scypath to the PID file. 246275970Scy.sp 247275970ScySpecify the name and path of the file used to record 248275970Scy\fBntpd\fP's 249275970Scyprocess ID. 250275970ScyThis is the same operation as the 251275970Scy\fBpidfile\fP \fIpidfile\fP 252275970Scyconfiguration file directive. 253275970Scy.It Fl P Ar number , Fl \-priority Ns = Ns Ar number 254275970ScyProcess priority. 255275970ScyThis option takes an integer number as its argument. 256275970Scy.sp 257275970ScyTo the extent permitted by the operating system, run 258275970Scy\fBntpd\fP 259275970Scyat the specified 260275970Scy\fBsched_setscheduler(SCHED_FIFO)\fP 261275970Scypriority. 262275970Scy.It Fl q , Fl \-quit 263275970ScySet the time and quit. 264275970ScyThis option must not appear in combination with any of the following options: 265275970Scysaveconfigquit, wait\-sync. 266275970Scy.sp 267275970Scy\fBntpd\fP 268275970Scywill not daemonize and will exit after the clock is first 269275970Scysynchronized. This behavior mimics that of the 270275970Scy\fBntpdate\fP 271275970Scyprogram, which will soon be replaced with a shell script. 272275970ScyThe 273275970Scy\fB\-g\fP 274275970Scyand 275275970Scy\fB\-x\fP 276275970Scyoptions can be used with this option. 277275970ScyNote: The kernel time discipline is disabled with this option. 278275970Scy.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string 279275970ScyBroadcast/propagation delay. 280275970Scy.sp 281275970ScySpecify 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. 282275970Scy.It Fl \-saveconfigquit Ns = Ns Ar string 283275970ScySave parsed configuration and quit. 284275970ScyThis option must not appear in combination with any of the following options: 285275970Scyquit, wait\-sync. 286275970Scy.sp 287275970ScyCause \fBntpd\fP to parse its startup configuration file and save an 288275970Scyequivalent to the given filename and exit. This option was 289275970Scydesigned for automated testing. 290275970Scy.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string 291275970ScyStatistics file location. 292275970Scy.sp 293275970ScySpecify the directory path for files created by the statistics facility. 294275970ScyThis is the same operation as the 295275970Scy\fBstatsdir\fP \fIstatsdir\fP 296275970Scyconfiguration file directive. 297275970Scy.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey 298275970ScyTrusted key number. 299275970ScyThis option may appear an unlimited number of times. 300275970Scy.sp 301275970ScyAdd the specified key number to the trusted key list. 302275970Scy.It Fl u Ar string , Fl \-user Ns = Ns Ar string 303275970ScyRun as userid (or userid:groupid). 304275970Scy.sp 305275970ScySpecify a user, and optionally a group, to switch to. 306275970ScyThis option is only available if the OS supports adjusting the clock 307275970Scywithout full root privileges. 308275970ScyThis option is supported under NetBSD (configure with 309275970Scy\fB\-\-enable\-clockctl\fP) or Linux (configure with 310275970Scy\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 311275970Scy.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number 312275970Scyinterval in seconds between scans for new or dropped interfaces. 313275970ScyThis option takes an integer number as its argument. 314275970Scy.sp 315275970ScyGive the time in seconds between two scans for new or dropped interfaces. 316275970ScyFor systems with routing socket support the scans will be performed shortly after the interface change 317275970Scyhas been detected by the system. 318275970ScyUse 0 to disable scanning. 60 seconds is the minimum time between scans. 319275970Scy.It Fl \-var Ns = Ns Ar nvar 320275970Scymake ARG an ntp variable (RW). 321275970ScyThis option may appear an unlimited number of times. 322275970Scy.sp 323275970Scy.It Fl \-dvar Ns = Ns Ar ndvar 324275970Scymake ARG an ntp variable (RW|DEF). 325275970ScyThis option may appear an unlimited number of times. 326275970Scy.sp 327275970Scy.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number 328275970ScySeconds to wait for first clock sync. 329275970ScyThis option must not appear in combination with any of the following options: 330275970Scynofork, quit, saveconfigquit. 331275970ScyThis option takes an integer number as its argument. 332275970Scy.sp 333275970ScyIf greater than zero, alters \fBntpd\fP's behavior when forking to 334275970Scydaemonize. Instead of exiting with status 0 immediately after 335275970Scythe fork, the parent waits up to the specified number of 336275970Scyseconds for the child to first synchronize the clock. The exit 337275970Scystatus is zero (success) if the clock was synchronized, 338275970Scyotherwise it is \fBETIMEDOUT\fP. 339275970ScyThis provides the option for a script starting \fBntpd\fP to easily 340275970Scywait for the first set of the clock before proceeding. 341275970Scy.It Fl x , Fl \-slew 342275970ScySlew up to 600 seconds. 343275970Scy.sp 344275970ScyNormally, 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. 345275970ScyThis option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 346275970ScyNote: 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. 347275970ScyThus, an adjustment as much as 600 s will take almost 14 days to complete. 348275970ScyThis option can be used with the 349275970Scy\fB\-g\fP 350275970Scyand 351275970Scy\fB\-q\fP 352275970Scyoptions. 353275970ScySee the 354275970Scy\fBtinker\fP 355275970Scyconfiguration file directive for other options. 356275970ScyNote: The kernel time discipline is disabled with this option. 357275970Scy.It Fl \-usepcc 358275970ScyUse CPU cycle counter (Windows only). 359275970Scy.sp 360275970ScyAttempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 361275970ScyThe CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 362275970Scythey have the same frequency, the CPU counter (RDTSC on x86) is 363275970Scyused directly, saving the overhead of a system call. 364275970Scy.It Fl \-pccfreq Ns = Ns Ar string 365275970ScyForce CPU cycle counter use (Windows only). 366275970Scy.sp 367275970ScyForce substitution the CPU counter for \fBQueryPerformanceCounter\fP. 368275970ScyThe CPU counter (RDTSC on x86) is used unconditionally with the 369275970Scygiven frequency (in Hz). 370275970Scy.It Fl m , Fl \-mdns 371275970ScyRegister with mDNS as a NTP server. 372275970Scy.sp 373275970ScyRegisters as an NTP server with the local mDNS server which allows 374275970Scythe server to be discovered via mDNS client lookup. 375275970Scy.It Fl \&? , Fl \-help 376275970ScyDisplay usage information and exit. 377275970Scy.It Fl \&! , Fl \-more\-help 378275970ScyPass the extended usage information through a pager. 379275970Scy.It Fl \-version Op Brq Ar v|c|n 380275970ScyOutput version of program and exit. The default mode is `v', a simple 381275970Scyversion. The `c' mode will print copyright information and `n' will 382275970Scyprint the full copyright notice. 383275970Scy.El 384275970Scy.Sh "OPTION PRESETS" 385275970ScyAny option that is not marked as \fInot presettable\fP may be preset 386275970Scyby loading values from environment variables named: 387275970Scy.nf 388275970Scy \fBNTPD_<option\-name>\fP or \fBNTPD\fP 389275970Scy.fi 390275970Scy.ad 391275970Scy.Sh USAGE 392275970Scy.Ss "How NTP Operates" 393275970ScyThe 394275970Scy.Nm 395275970Scyutility operates by exchanging messages with 396275970Scyone or more configured servers over a range of designated poll intervals. 397275970ScyWhen 398275970Scystarted, whether for the first or subsequent times, the program 399275970Scyrequires several exchanges from the majority of these servers so 400275970Scythe signal processing and mitigation algorithms can accumulate and 401275970Scygroom the data and set the clock. 402275970ScyIn order to protect the network 403275970Scyfrom bursts, the initial poll interval for each server is delayed 404275970Scyan interval randomized over a few seconds. 405275970ScyAt the default initial poll 406275970Scyinterval of 64s, several minutes can elapse before the clock is 407275970Scyset. 408275970ScyThis initial delay to set the clock 409275970Scycan be safely and dramatically reduced using the 410275970Scy.Cm iburst 411275970Scykeyword with the 412275970Scy.Ic server 413275970Scyconfiguration 414275970Scycommand, as described in 415275970Scy.Xr ntp.conf 5 . 416275970Scy.Pp 417275970ScyMost operating systems and hardware of today incorporate a 418275970Scytime\-of\-year (TOY) chip to maintain the time during periods when 419275970Scythe power is off. 420275970ScyWhen the machine is booted, the chip is used to 421275970Scyinitialize the operating system time. 422275970ScyAfter the machine has 423275970Scysynchronized to a NTP server, the operating system corrects the 424275970Scychip from time to time. 425275970ScyIn the default case, if 426275970Scy.Nm 427275970Scydetects that the time on the host 428275970Scyis more than 1000s from the server time, 429275970Scy.Nm 430275970Scyassumes something must be terribly wrong and the only 431275970Scyreliable action is for the operator to intervene and set the clock 432275970Scyby hand. 433275970Scy(Reasons for this include there is no TOY chip, 434275970Scyor its battery is dead, or that the TOY chip is just of poor quality.) 435275970ScyThis causes 436275970Scy.Nm 437275970Scyto exit with a panic message to 438275970Scythe system log. 439275970ScyThe 440275970Scy.Fl g 441275970Scyoption overrides this check and the 442275970Scyclock will be set to the server time regardless of the chip time 443275970Scy(up to 68 years in the past or future \(em 444275970Scythis is a limitation of the NTPv4 protocol). 445275970ScyHowever, and to protect against broken hardware, such as when the 446275970ScyCMOS battery fails or the clock counter becomes defective, once the 447275970Scyclock has been set an error greater than 1000s will cause 448275970Scy.Nm 449275970Scyto exit anyway. 450275970Scy.Pp 451275970ScyUnder ordinary conditions, 452275970Scy.Nm 453275970Scyadjusts the clock in 454275970Scysmall steps so that the timescale is effectively continuous and 455275970Scywithout discontinuities. 456275970ScyUnder conditions of extreme network 457275970Scycongestion, the roundtrip delay jitter can exceed three seconds and 458275970Scythe synchronization distance, which is equal to one\-half the 459275970Scyroundtrip delay plus error budget terms, can become very large. 460275970ScyThe 461275970Scy.Nm 462275970Scyalgorithms discard sample offsets exceeding 128 ms, 463275970Scyunless the interval during which no sample offset is less than 128 464275970Scyms exceeds 900s. 465275970ScyThe first sample after that, no matter what the 466275970Scyoffset, steps the clock to the indicated time. 467275970ScyIn practice this 468275970Scyreduces the false alarm rate where the clock is stepped in error to 469275970Scya vanishingly low incidence. 470275970Scy.Pp 471275970ScyAs the result of this behavior, once the clock has been set it 472275970Scyvery rarely strays more than 128 ms even under extreme cases of 473275970Scynetwork path congestion and jitter. 474275970ScySometimes, in particular when 475275970Scy.Nm 476275970Scyis first started without a valid drift file 477275970Scyon a system with a large intrinsic drift 478275970Scythe error might grow to exceed 128 ms, 479275970Scywhich would cause the clock to be set backwards 480275970Scyif the local clock time is more than 128 s 481275970Scyin the future relative to the server. 482275970ScyIn some applications, this behavior may be unacceptable. 483275970ScyThere are several solutions, however. 484275970ScyIf the 485275970Scy.Fl x 486275970Scyoption is included on the command line, the clock will 487275970Scynever be stepped and only slew corrections will be used. 488275970ScyBut this choice comes with a cost that 489275970Scyshould be carefully explored before deciding to use 490275970Scythe 491275970Scy.Fl x 492275970Scyoption. 493275970ScyThe maximum slew rate possible is limited 494275970Scyto 500 parts\-per\-million (PPM) as a consequence of the correctness 495275970Scyprinciples on which the NTP protocol and algorithm design are 496275970Scybased. 497275970ScyAs a result, the local clock can take a long time to 498275970Scyconverge to an acceptable offset, about 2,000 s for each second the 499275970Scyclock is outside the acceptable range. 500275970ScyDuring this interval the 501275970Scylocal clock will not be consistent with any other network clock and 502275970Scythe system cannot be used for distributed applications that require 503275970Scycorrectly synchronized network time. 504275970Scy.Pp 505275970ScyIn spite of the above precautions, sometimes when large 506275970Scyfrequency errors are present the resulting time offsets stray 507275970Scyoutside the 128\-ms range and an eventual step or slew time 508275970Scycorrection is required. 509275970ScyIf following such a correction the 510275970Scyfrequency error is so large that the first sample is outside the 511275970Scyacceptable range, 512275970Scy.Nm 513275970Scyenters the same state as when the 514275970Scy.Pa ntp.drift 515275970Scyfile is not present. 516275970ScyThe intent of this behavior 517275970Scyis to quickly correct the frequency and restore operation to the 518275970Scynormal tracking mode. 519275970ScyIn the most extreme cases 520275970Scy(the host 521275970Scy.Cm time.ien.it 522275970Scycomes to mind), there may be occasional 523275970Scystep/slew corrections and subsequent frequency corrections. 524275970ScyIt 525275970Scyhelps in these cases to use the 526275970Scy.Cm burst 527275970Scykeyword when 528275970Scyconfiguring the server, but 529275970ScyONLY 530275970Scywhen you have permission to do so from the owner of the target host. 531275970Scy.Pp 532275970ScyFinally, 533275970Scyin the past many startup scripts would run 534275970Scy.Xr ntpdate 1ntpdatemdoc 535289764Sglebiusor 536289764Sglebius.Xr sntp 1sntpmdoc 537275970Scyto get the system clock close to correct before starting 538275970Scy.Xr ntpd 1ntpdmdoc , 539275970Scybut this was never more than a mediocre hack and is no longer needed. 540275970ScyIf you are following the instructions in 541275970Scy.Sx "Starting NTP (Best Current Practice)" 542275970Scyand you still need to set the system time before starting 543275970Scy.Nm , 544275970Scyplease open a bug report and document what is going on, 545275970Scyand then look at using 546289764Sglebius.Xr sntp 1sntpmdoc 547289764Sglebiusif you really need to set the clock before starting 548289764Sglebius.Nm . 549275970Scy.Pp 550275970ScyThere is a way to start 551275970Scy.Xr ntpd 1ntpdmdoc 552275970Scythat often addresses all of the problems mentioned above. 553275970Scy.Ss "Starting NTP (Best Current Practice)" 554275970ScyFirst, use the 555275970Scy.Cm iburst 556275970Scyoption on your 557275970Scy.Cm server 558275970Scyentries. 559275970Scy.Pp 560275970ScyIf you can also keep a good 561275970Scy.Pa ntp.drift 562275970Scyfile then 563275970Scy.Xr ntpd 1ntpdmdoc 564275970Scywill effectively "warm\-start" and your system's clock will 565275970Scybe stable in under 11 seconds' time. 566275970Scy.Pp 567275970ScyAs soon as possible in the startup sequence, start 568275970Scy.Xr ntpd 1ntpdmdoc 569275970Scywith at least the 570275970Scy.Fl g 571275970Scyand perhaps the 572275970Scy.Fl N 573275970Scyoptions. 574275970ScyThen, 575275970Scystart the rest of your "normal" processes. 576275970ScyThis will give 577275970Scy.Xr ntpd 1ntpdmdoc 578275970Scyas much time as possible to get the system's clock synchronized and stable. 579275970Scy.Pp 580275970ScyFinally, 581275970Scyif you have processes like 582275970Scy.Cm dovecot 583275970Scyor database servers 584275970Scythat require 585275970Scymonotonically\-increasing time, 586275970Scyrun 587275970Scy.Xr ntp\-wait 1ntp\-waitmdoc 588275970Scyas late as possible in the boot sequence 589275970Scy(perhaps with the 590275970Scy.Fl v 591275970Scyflag) 592275970Scyand after 593275970Scy.Xr ntp\-wait 1ntp\-waitmdoc 594275970Scyexits successfully 595275970Scyit is as safe as it will ever be to start any process that require 596275970Scystable time. 597275970Scy.Ss "Frequency Discipline" 598275970ScyThe 599275970Scy.Nm 600275970Scybehavior at startup depends on whether the 601275970Scyfrequency file, usually 602275970Scy.Pa ntp.drift , 603275970Scyexists. 604275970ScyThis file 605275970Scycontains the latest estimate of clock frequency error. 606275970ScyWhen the 607275970Scy.Nm 608275970Scyis started and the file does not exist, the 609275970Scy.Nm 610275970Scyenters a special mode designed to quickly adapt to 611275970Scythe particular system clock oscillator time and frequency error. 612275970ScyThis takes approximately 15 minutes, after which the time and 613275970Scyfrequency are set to nominal values and the 614275970Scy.Nm 615275970Scyenters 616275970Scynormal mode, where the time and frequency are continuously tracked 617275970Scyrelative to the server. 618275970ScyAfter one hour the frequency file is 619275970Scycreated and the current frequency offset written to it. 620275970ScyWhen the 621275970Scy.Nm 622275970Scyis started and the file does exist, the 623275970Scy.Nm 624275970Scyfrequency is initialized from the file and enters normal mode 625275970Scyimmediately. 626275970ScyAfter that the current frequency offset is written to 627275970Scythe file at hourly intervals. 628275970Scy.Ss "Operating Modes" 629275970ScyThe 630275970Scy.Nm 631275970Scyutility can operate in any of several modes, including 632275970Scysymmetric active/passive, client/server broadcast/multicast and 633275970Scymanycast, as described in the 634275970Scy.Qq Association Management 635275970Scypage 636275970Scy(available as part of the HTML documentation 637275970Scyprovided in 638275970Scy.Pa /usr/share/doc/ntp ) . 639275970ScyIt normally operates continuously while 640275970Scymonitoring for small changes in frequency and trimming the clock 641275970Scyfor the ultimate precision. 642275970ScyHowever, it can operate in a one\-time 643275970Scymode where the time is set from an external server and frequency is 644275970Scyset from a previously recorded frequency file. 645275970ScyA 646275970Scybroadcast/multicast or manycast client can discover remote servers, 647275970Scycompute server\-client propagation delay correction factors and 648275970Scyconfigure itself automatically. 649275970ScyThis makes it possible to deploy a 650275970Scyfleet of workstations without specifying configuration details 651275970Scyspecific to the local environment. 652275970Scy.Pp 653275970ScyBy default, 654275970Scy.Nm 655275970Scyruns in continuous mode where each of 656275970Scypossibly several external servers is polled at intervals determined 657275970Scyby an intricate state machine. 658275970ScyThe state machine measures the 659275970Scyincidental roundtrip delay jitter and oscillator frequency wander 660275970Scyand determines the best poll interval using a heuristic algorithm. 661275970ScyOrdinarily, and in most operating environments, the state machine 662275970Scywill start with 64s intervals and eventually increase in steps to 663275970Scy1024s. 664275970ScyA small amount of random variation is introduced in order to 665275970Scyavoid bunching at the servers. 666275970ScyIn addition, should a server become 667275970Scyunreachable for some time, the poll interval is increased in steps 668275970Scyto 1024s in order to reduce network overhead. 669275970Scy.Pp 670275970ScyIn some cases it may not be practical for 671275970Scy.Nm 672275970Scyto run continuously. 673275970ScyA common workaround has been to run the 674275970Scy.Xr ntpdate 1ntpdatemdoc 675275970Scyor 676275970Scy.Xr sntp 1sntpmdoc 677275970Scyprograms from a 678275970Scy.Xr cron 8 679275970Scyjob at designated 680275970Scytimes. 681275970ScyHowever, these programs do not have the crafted signal 682275970Scyprocessing, error checking or mitigation algorithms of 683275970Scy.Nm . 684275970ScyThe 685275970Scy.Fl q 686275970Scyoption is intended for this purpose. 687275970ScySetting this option will cause 688275970Scy.Nm 689275970Scyto exit just after 690275970Scysetting the clock for the first time. 691275970ScyThe procedure for initially 692275970Scysetting the clock is the same as in continuous mode; most 693275970Scyapplications will probably want to specify the 694275970Scy.Cm iburst 695275970Scykeyword with the 696275970Scy.Ic server 697275970Scyconfiguration command. 698275970ScyWith this 699275970Scykeyword a volley of messages are exchanged to groom the data and 700275970Scythe clock is set in about 10 s. 701275970ScyIf nothing is heard after a 702275970Scycouple of minutes, the daemon times out and exits. 703275970ScyAfter a suitable 704275970Scyperiod of mourning, the 705275970Scy.Xr ntpdate 1ntpdatemdoc 706275970Scyprogram will be 707275970Scyretired. 708275970Scy.Pp 709275970ScyWhen kernel support is available to discipline the clock 710275970Scyfrequency, which is the case for stock Solaris, Tru64, Linux and 711275970Scy.Fx , 712275970Scya useful feature is available to discipline the clock 713275970Scyfrequency. 714275970ScyFirst, 715275970Scy.Nm 716275970Scyis run in continuous mode with 717275970Scyselected servers in order to measure and record the intrinsic clock 718275970Scyfrequency offset in the frequency file. 719275970ScyIt may take some hours for 720275970Scythe frequency and offset to settle down. 721275970ScyThen the 722275970Scy.Nm 723275970Scyis 724275970Scystopped and run in one\-time mode as required. 725275970ScyAt each startup, the 726275970Scyfrequency is read from the file and initializes the kernel 727275970Scyfrequency. 728275970Scy.Ss "Poll Interval Control" 729275970ScyThis version of NTP includes an intricate state machine to 730275970Scyreduce the network load while maintaining a quality of 731275970Scysynchronization consistent with the observed jitter and wander. 732275970ScyThere are a number of ways to tailor the operation in order enhance 733275970Scyaccuracy by reducing the interval or to reduce network overhead by 734275970Scyincreasing it. 735275970ScyHowever, the user is advised to carefully consider 736275970Scythe consequences of changing the poll adjustment range from the 737275970Scydefault minimum of 64 s to the default maximum of 1,024 s. 738275970ScyThe 739275970Scydefault minimum can be changed with the 740275970Scy.Ic tinker 741275970Scy.Cm minpoll 742275970Scycommand to a value not less than 16 s. 743275970ScyThis value is used for all 744275970Scyconfigured associations, unless overridden by the 745275970Scy.Cm minpoll 746275970Scyoption on the configuration command. 747275970ScyNote that most device drivers 748275970Scywill not operate properly if the poll interval is less than 64 s 749275970Scyand that the broadcast server and manycast client associations will 750275970Scyalso use the default, unless overridden. 751275970Scy.Pp 752275970ScyIn some cases involving dial up or toll services, it may be 753275970Scyuseful to increase the minimum interval to a few tens of minutes 754275970Scyand maximum interval to a day or so. 755275970ScyUnder normal operation 756275970Scyconditions, once the clock discipline loop has stabilized the 757275970Scyinterval will be increased in steps from the minimum to the 758275970Scymaximum. 759275970ScyHowever, this assumes the intrinsic clock frequency error 760275970Scyis small enough for the discipline loop correct it. 761275970ScyThe capture 762275970Scyrange of the loop is 500 PPM at an interval of 64s decreasing by a 763275970Scyfactor of two for each doubling of interval. 764275970ScyAt a minimum of 1,024 765275970Scys, for example, the capture range is only 31 PPM. 766275970ScyIf the intrinsic 767275970Scyerror is greater than this, the drift file 768275970Scy.Pa ntp.drift 769275970Scywill 770275970Scyhave to be specially tailored to reduce the residual error below 771275970Scythis limit. 772275970ScyOnce this is done, the drift file is automatically 773275970Scyupdated once per hour and is available to initialize the frequency 774275970Scyon subsequent daemon restarts. 775275970Scy.Ss "The huff\-n'\-puff Filter" 776275970ScyIn scenarios where a considerable amount of data are to be 777275970Scydownloaded or uploaded over telephone modems, timekeeping quality 778275970Scycan be seriously degraded. 779275970ScyThis occurs because the differential 780275970Scydelays on the two directions of transmission can be quite large. 781275970ScyIn 782275970Scymany cases the apparent time errors are so large as to exceed the 783275970Scystep threshold and a step correction can occur during and after the 784275970Scydata transfer is in progress. 785275970Scy.Pp 786275970ScyThe huff\-n'\-puff filter is designed to correct the apparent time 787275970Scyoffset in these cases. 788275970ScyIt depends on knowledge of the propagation 789275970Scydelay when no other traffic is present. 790275970ScyIn common scenarios this 791275970Scyoccurs during other than work hours. 792275970ScyThe filter maintains a shift 793275970Scyregister that remembers the minimum delay over the most recent 794275970Scyinterval measured usually in hours. 795275970ScyUnder conditions of severe 796275970Scydelay, the filter corrects the apparent offset using the sign of 797275970Scythe offset and the difference between the apparent delay and 798275970Scyminimum delay. 799275970ScyThe name of the filter reflects the negative (huff) 800275970Scyand positive (puff) correction, which depends on the sign of the 801275970Scyoffset. 802275970Scy.Pp 803275970ScyThe filter is activated by the 804275970Scy.Ic tinker 805275970Scycommand and 806275970Scy.Cm huffpuff 807275970Scykeyword, as described in 808275970Scy.Xr ntp.conf 5 . 809275970Scy.Sh "ENVIRONMENT" 810275970ScySee \fBOPTION PRESETS\fP for configuration environment variables. 811275970Scy.Sh FILES 812275970Scy.Bl -tag -width /etc/ntp.drift -compact 813275970Scy.It Pa /etc/ntp.conf 814275970Scythe default name of the configuration file 815275970Scy.It Pa /etc/ntp.drift 816275970Scythe default name of the drift file 817275970Scy.It Pa /etc/ntp.keys 818275970Scythe default name of the key file 819275970Scy.El 820275970Scy.Sh "EXIT STATUS" 821275970ScyOne of the following exit values will be returned: 822275970Scy.Bl -tag 823275970Scy.It 0 " (EXIT_SUCCESS)" 824275970ScySuccessful program execution. 825275970Scy.It 1 " (EXIT_FAILURE)" 826275970ScyThe operation failed or the command syntax was not valid. 827275970Scy.It 70 " (EX_SOFTWARE)" 828275970Scylibopts had an internal operational error. Please report 829275970Scyit to autogen\-users@lists.sourceforge.net. Thank you. 830275970Scy.El 831275970Scy.Sh "SEE ALSO" 832275970Scy.Xr ntp.conf 5 , 833275970Scy.Xr ntpdate 1ntpdatemdoc , 834275970Scy.Xr ntpdc 1ntpdcmdoc , 835275970Scy.Xr ntpq 1ntpqmdoc , 836275970Scy.Xr sntp 1sntpmdoc 837275970Scy.Pp 838275970ScyIn addition to the manual pages provided, 839275970Scycomprehensive documentation is available on the world wide web 840275970Scyat 841275970Scy.Li http://www.ntp.org/ . 842275970ScyA snapshot of this documentation is available in HTML format in 843275970Scy.Pa /usr/share/doc/ntp . 844275970Scy.Rs 845275970Scy.%A David L. Mills 846275970Scy.%T Network Time Protocol (Version 1) 847275970Scy.%O RFC1059 848275970Scy.Re 849275970Scy.Rs 850275970Scy.%A David L. Mills 851275970Scy.%T Network Time Protocol (Version 2) 852275970Scy.%O RFC1119 853275970Scy.Re 854275970Scy.Rs 855275970Scy.%A David L. Mills 856275970Scy.%T Network Time Protocol (Version 3) 857275970Scy.%O RFC1305 858275970Scy.Re 859275970Scy.Rs 860275970Scy.%A David L. Mills 861275970Scy.%A J. Martin, Ed. 862275970Scy.%A J. Burbank 863275970Scy.%A W. Kasch 864275970Scy.%T Network Time Protocol Version 4: Protocol and Algorithms Specification 865275970Scy.%O RFC5905 866275970Scy.Re 867275970Scy.Rs 868275970Scy.%A David L. Mills 869275970Scy.%A B. Haberman, Ed. 870275970Scy.%T Network Time Protocol Version 4: Autokey Specification 871275970Scy.%O RFC5906 872275970Scy.Re 873275970Scy.Rs 874275970Scy.%A H. Gerstung 875275970Scy.%A C. Elliott 876275970Scy.%A B. Haberman, Ed. 877275970Scy.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) 878275970Scy.%O RFC5907 879275970Scy.Re 880275970Scy.Rs 881275970Scy.%A R. Gayraud 882275970Scy.%A B. Lourdelet 883275970Scy.%T Network Time Protocol (NTP) Server Option for DHCPv6 884275970Scy.%O RFC5908 885275970Scy.Re 886275970Scy.Sh "AUTHORS" 887280849ScyThe University of Delaware and Network Time Foundation 888275970Scy.Sh "COPYRIGHT" 889316722SdelphijCopyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. 890275970ScyThis program is released under the terms of the NTP license, <http://ntp.org/license>. 891275970Scy.Sh BUGS 892275970ScyThe 893275970Scy.Nm 894275970Scyutility has gotten rather fat. 895275970ScyWhile not huge, it has gotten 896275970Scylarger than might be desirable for an elevated\-priority 897275970Scy.Nm 898275970Scyrunning on a workstation, particularly since many of 899275970Scythe fancy features which consume the space were designed more with 900275970Scya busy primary server, rather than a high stratum workstation in 901275970Scymind. 902275970Scy.Pp 903275970ScyPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org 904275970Scy.Sh NOTES 905275970ScyPortions of this document came from FreeBSD. 906275970Scy.Pp 907275970ScyThis manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP 908275970Scyoption definitions. 909