1/* -*- Mode: Text -*- */ 2 3autogen definitions options; 4 5#include copyright.def 6 7prog-name = "ntpd"; 8prog-title = "NTP daemon program"; 9argument = "[ <server1> ... <serverN> ]"; 10 11#include ntpdbase-opts.def 12 13/* explain: Additional information whenever the usage routine is invoked */ 14explain = <<- _END_EXPLAIN 15 _END_EXPLAIN; 16 17doc-section = { 18 ds-type = 'DESCRIPTION'; 19 ds-format = 'mdoc'; 20 ds-text = <<- _END_PROG_MDOC_DESCRIP 21The 22.Nm 23utility is an operating system daemon which sets 24and maintains the system time of day in synchronism with Internet 25standard time servers. 26It is a complete implementation of the 27Network Time Protocol (NTP) version 4, as defined by RFC-5905, 28but also retains compatibility with 29version 3, as defined by RFC-1305, and versions 1 30and 2, as defined by RFC-1059 and RFC-1119, respectively. 31.Pp 32The 33.Nm 34utility does most computations in 64-bit floating point 35arithmetic and does relatively clumsy 64-bit fixed point operations 36only when necessary to preserve the ultimate precision, about 232 37picoseconds. 38While the ultimate precision is not achievable with 39ordinary workstations and networks of today, it may be required 40with future gigahertz CPU clocks and gigabit LANs. 41.Pp 42Ordinarily, 43.Nm 44reads the 45.Xr ntp.conf 5 46configuration file at startup time in order to determine the 47synchronization sources and operating modes. 48It is also possible to 49specify a working, although limited, configuration entirely on the 50command line, obviating the need for a configuration file. 51This may 52be particularly useful when the local host is to be configured as a 53broadcast/multicast client, with all peers being determined by 54listening to broadcasts at run time. 55.Pp 56If NetInfo support is built into 57.Nm , 58then 59.Nm 60will attempt to read its configuration from the 61NetInfo if the default 62.Xr ntp.conf 5 63file cannot be read and no file is 64specified by the 65.Fl c 66option. 67.Pp 68Various internal 69.Nm 70variables can be displayed and 71configuration options altered while the 72.Nm 73is running 74using the 75.Xr ntpq 1ntpqmdoc 76and 77.Xr ntpdc 1ntpdcmdoc 78utility programs. 79.Pp 80When 81.Nm 82starts it looks at the value of 83.Xr umask 2 , 84and if zero 85.Nm 86will set the 87.Xr umask 2 88to 022. 89 _END_PROG_MDOC_DESCRIP; 90}; 91 92doc-section = { 93 ds-type = 'USAGE'; 94 ds-format = 'mdoc'; 95 ds-text = <<- _END_MDOC_USAGE 96.Ss "How NTP Operates" 97The 98.Nm 99utility operates by exchanging messages with 100one or more configured servers over a range of designated poll intervals. 101When 102started, whether for the first or subsequent times, the program 103requires several exchanges from the majority of these servers so 104the signal processing and mitigation algorithms can accumulate and 105groom the data and set the clock. 106In order to protect the network 107from bursts, the initial poll interval for each server is delayed 108an interval randomized over a few seconds. 109At the default initial poll 110interval of 64s, several minutes can elapse before the clock is 111set. 112This initial delay to set the clock 113can be safely and dramatically reduced using the 114.Cm iburst 115keyword with the 116.Ic server 117configuration 118command, as described in 119.Xr ntp.conf 5 . 120.Pp 121Most operating systems and hardware of today incorporate a 122time-of-year (TOY) chip to maintain the time during periods when 123the power is off. 124When the machine is booted, the chip is used to 125initialize the operating system time. 126After the machine has 127synchronized to a NTP server, the operating system corrects the 128chip from time to time. 129In the default case, if 130.Nm 131detects that the time on the host 132is more than 1000s from the server time, 133.Nm 134assumes something must be terribly wrong and the only 135reliable action is for the operator to intervene and set the clock 136by hand. 137(Reasons for this include there is no TOY chip, 138or its battery is dead, or that the TOY chip is just of poor quality.) 139This causes 140.Nm 141to exit with a panic message to 142the system log. 143The 144.Fl g 145option overrides this check and the 146clock will be set to the server time regardless of the chip time 147(up to 68 years in the past or future \(em 148this is a limitation of the NTPv4 protocol). 149However, and to protect against broken hardware, such as when the 150CMOS battery fails or the clock counter becomes defective, once the 151clock has been set an error greater than 1000s will cause 152.Nm 153to exit anyway. 154.Pp 155Under ordinary conditions, 156.Nm 157adjusts the clock in 158small steps so that the timescale is effectively continuous and 159without discontinuities. 160Under conditions of extreme network 161congestion, the roundtrip delay jitter can exceed three seconds and 162the synchronization distance, which is equal to one-half the 163roundtrip delay plus error budget terms, can become very large. 164The 165.Nm 166algorithms discard sample offsets exceeding 128 ms, 167unless the interval during which no sample offset is less than 128 168ms exceeds 900s. 169The first sample after that, no matter what the 170offset, steps the clock to the indicated time. 171In practice this 172reduces the false alarm rate where the clock is stepped in error to 173a vanishingly low incidence. 174.Pp 175As the result of this behavior, once the clock has been set it 176very rarely strays more than 128 ms even under extreme cases of 177network path congestion and jitter. 178Sometimes, in particular when 179.Nm 180is first started without a valid drift file 181on a system with a large intrinsic drift 182the error might grow to exceed 128 ms, 183which would cause the clock to be set backwards 184if the local clock time is more than 128 s 185in the future relative to the server. 186In some applications, this behavior may be unacceptable. 187There are several solutions, however. 188If the 189.Fl x 190option is included on the command line, the clock will 191never be stepped and only slew corrections will be used. 192But this choice comes with a cost that 193should be carefully explored before deciding to use 194the 195.Fl x 196option. 197The maximum slew rate possible is limited 198to 500 parts-per-million (PPM) as a consequence of the correctness 199principles on which the NTP protocol and algorithm design are 200based. 201As a result, the local clock can take a long time to 202converge to an acceptable offset, about 2,000 s for each second the 203clock is outside the acceptable range. 204During this interval the 205local clock will not be consistent with any other network clock and 206the system cannot be used for distributed applications that require 207correctly synchronized network time. 208.Pp 209In spite of the above precautions, sometimes when large 210frequency errors are present the resulting time offsets stray 211outside the 128-ms range and an eventual step or slew time 212correction is required. 213If following such a correction the 214frequency error is so large that the first sample is outside the 215acceptable range, 216.Nm 217enters the same state as when the 218.Pa ntp.drift 219file is not present. 220The intent of this behavior 221is to quickly correct the frequency and restore operation to the 222normal tracking mode. 223In the most extreme cases 224(the host 225.Cm time.ien.it 226comes to mind), there may be occasional 227step/slew corrections and subsequent frequency corrections. 228It 229helps in these cases to use the 230.Cm burst 231keyword when 232configuring the server, but 233ONLY 234when you have permission to do so from the owner of the target host. 235.Pp 236Finally, 237in the past many startup scripts would run 238.Xr ntpdate 1ntpdatemdoc 239or 240.Xr sntp 1sntpmdoc 241to get the system clock close to correct before starting 242.Xr ntpd 1ntpdmdoc , 243but this was never more than a mediocre hack and is no longer needed. 244If you are following the instructions in 245.Sx "Starting NTP (Best Current Practice)" 246and you still need to set the system time before starting 247.Nm , 248please open a bug report and document what is going on, 249and then look at using 250.Xr sntp 1sntpmdoc 251if you really need to set the clock before starting 252.Nm . 253.Pp 254There is a way to start 255.Xr ntpd 1ntpdmdoc 256that often addresses all of the problems mentioned above. 257.Ss "Starting NTP (Best Current Practice)" 258First, use the 259.Cm iburst 260option on your 261.Cm server 262entries. 263.Pp 264If you can also keep a good 265.Pa ntp.drift 266file then 267.Xr ntpd 1ntpdmdoc 268will effectively "warm-start" and your system's clock will 269be stable in under 11 seconds' time. 270.Pp 271As soon as possible in the startup sequence, start 272.Xr ntpd 1ntpdmdoc 273with at least the 274.Fl g 275and perhaps the 276.Fl N 277options. 278Then, 279start the rest of your "normal" processes. 280This will give 281.Xr ntpd 1ntpdmdoc 282as much time as possible to get the system's clock synchronized and stable. 283.Pp 284Finally, 285if you have processes like 286.Cm dovecot 287or database servers 288that require 289monotonically-increasing time, 290run 291.Xr ntp-wait 1ntp-waitmdoc 292as late as possible in the boot sequence 293(perhaps with the 294.Fl v 295flag) 296and after 297.Xr ntp-wait 1ntp-waitmdoc 298exits successfully 299it is as safe as it will ever be to start any process that require 300stable time. 301.Ss "Frequency Discipline" 302The 303.Nm 304behavior at startup depends on whether the 305frequency file, usually 306.Pa ntp.drift , 307exists. 308This file 309contains the latest estimate of clock frequency error. 310When the 311.Nm 312is started and the file does not exist, the 313.Nm 314enters a special mode designed to quickly adapt to 315the particular system clock oscillator time and frequency error. 316This takes approximately 15 minutes, after which the time and 317frequency are set to nominal values and the 318.Nm 319enters 320normal mode, where the time and frequency are continuously tracked 321relative to the server. 322After one hour the frequency file is 323created and the current frequency offset written to it. 324When the 325.Nm 326is started and the file does exist, the 327.Nm 328frequency is initialized from the file and enters normal mode 329immediately. 330After that the current frequency offset is written to 331the file at hourly intervals. 332.Ss "Operating Modes" 333The 334.Nm 335utility can operate in any of several modes, including 336symmetric active/passive, client/server broadcast/multicast and 337manycast, as described in the 338.Qq Association Management 339page 340(available as part of the HTML documentation 341provided in 342.Pa /usr/share/doc/ntp ) . 343It normally operates continuously while 344monitoring for small changes in frequency and trimming the clock 345for the ultimate precision. 346However, it can operate in a one-time 347mode where the time is set from an external server and frequency is 348set from a previously recorded frequency file. 349A 350broadcast/multicast or manycast client can discover remote servers, 351compute server-client propagation delay correction factors and 352configure itself automatically. 353This makes it possible to deploy a 354fleet of workstations without specifying configuration details 355specific to the local environment. 356.Pp 357By default, 358.Nm 359runs in continuous mode where each of 360possibly several external servers is polled at intervals determined 361by an intricate state machine. 362The state machine measures the 363incidental roundtrip delay jitter and oscillator frequency wander 364and determines the best poll interval using a heuristic algorithm. 365Ordinarily, and in most operating environments, the state machine 366will start with 64s intervals and eventually increase in steps to 3671024s. 368A small amount of random variation is introduced in order to 369avoid bunching at the servers. 370In addition, should a server become 371unreachable for some time, the poll interval is increased in steps 372to 1024s in order to reduce network overhead. 373.Pp 374In some cases it may not be practical for 375.Nm 376to run continuously. 377A common workaround has been to run the 378.Xr ntpdate 1ntpdatemdoc 379or 380.Xr sntp 1sntpmdoc 381programs from a 382.Xr cron 8 383job at designated 384times. 385However, these programs do not have the crafted signal 386processing, error checking or mitigation algorithms of 387.Nm . 388The 389.Fl q 390option is intended for this purpose. 391Setting this option will cause 392.Nm 393to exit just after 394setting the clock for the first time. 395The procedure for initially 396setting the clock is the same as in continuous mode; most 397applications will probably want to specify the 398.Cm iburst 399keyword with the 400.Ic server 401configuration command. 402With this 403keyword a volley of messages are exchanged to groom the data and 404the clock is set in about 10 s. 405If nothing is heard after a 406couple of minutes, the daemon times out and exits. 407After a suitable 408period of mourning, the 409.Xr ntpdate 1ntpdatemdoc 410program will be 411retired. 412.Pp 413When kernel support is available to discipline the clock 414frequency, which is the case for stock Solaris, Tru64, Linux and 415.Fx , 416a useful feature is available to discipline the clock 417frequency. 418First, 419.Nm 420is run in continuous mode with 421selected servers in order to measure and record the intrinsic clock 422frequency offset in the frequency file. 423It may take some hours for 424the frequency and offset to settle down. 425Then the 426.Nm 427is 428stopped and run in one-time mode as required. 429At each startup, the 430frequency is read from the file and initializes the kernel 431frequency. 432.Ss "Poll Interval Control" 433This version of NTP includes an intricate state machine to 434reduce the network load while maintaining a quality of 435synchronization consistent with the observed jitter and wander. 436There are a number of ways to tailor the operation in order enhance 437accuracy by reducing the interval or to reduce network overhead by 438increasing it. 439However, the user is advised to carefully consider 440the consequences of changing the poll adjustment range from the 441default minimum of 64 s to the default maximum of 1,024 s. 442The 443default minimum can be changed with the 444.Ic tinker 445.Cm minpoll 446command to a value not less than 16 s. 447This value is used for all 448configured associations, unless overridden by the 449.Cm minpoll 450option on the configuration command. 451Note that most device drivers 452will not operate properly if the poll interval is less than 64 s 453and that the broadcast server and manycast client associations will 454also use the default, unless overridden. 455.Pp 456In some cases involving dial up or toll services, it may be 457useful to increase the minimum interval to a few tens of minutes 458and maximum interval to a day or so. 459Under normal operation 460conditions, once the clock discipline loop has stabilized the 461interval will be increased in steps from the minimum to the 462maximum. 463However, this assumes the intrinsic clock frequency error 464is small enough for the discipline loop correct it. 465The capture 466range of the loop is 500 PPM at an interval of 64s decreasing by a 467factor of two for each doubling of interval. 468At a minimum of 1,024 469s, for example, the capture range is only 31 PPM. 470If the intrinsic 471error is greater than this, the drift file 472.Pa ntp.drift 473will 474have to be specially tailored to reduce the residual error below 475this limit. 476Once this is done, the drift file is automatically 477updated once per hour and is available to initialize the frequency 478on subsequent daemon restarts. 479.Ss "The huff-n'-puff Filter" 480In scenarios where a considerable amount of data are to be 481downloaded or uploaded over telephone modems, timekeeping quality 482can be seriously degraded. 483This occurs because the differential 484delays on the two directions of transmission can be quite large. 485In 486many cases the apparent time errors are so large as to exceed the 487step threshold and a step correction can occur during and after the 488data transfer is in progress. 489.Pp 490The huff-n'-puff filter is designed to correct the apparent time 491offset in these cases. 492It depends on knowledge of the propagation 493delay when no other traffic is present. 494In common scenarios this 495occurs during other than work hours. 496The filter maintains a shift 497register that remembers the minimum delay over the most recent 498interval measured usually in hours. 499Under conditions of severe 500delay, the filter corrects the apparent offset using the sign of 501the offset and the difference between the apparent delay and 502minimum delay. 503The name of the filter reflects the negative (huff) 504and positive (puff) correction, which depends on the sign of the 505offset. 506.Pp 507The filter is activated by the 508.Ic tinker 509command and 510.Cm huffpuff 511keyword, as described in 512.Xr ntp.conf 5 . 513 _END_MDOC_USAGE; 514}; 515 516doc-section = { 517 ds-type = 'FILES'; 518 ds-format = 'mdoc'; 519 ds-text = <<- _END_MDOC_FILES 520.Bl -tag -width /etc/ntp.drift -compact 521.It Pa /etc/ntp.conf 522the default name of the configuration file 523.It Pa /etc/ntp.drift 524the default name of the drift file 525.It Pa /etc/ntp.keys 526the default name of the key file 527.El 528 _END_MDOC_FILES; 529}; 530 531doc-section = { 532 ds-type = 'SEE ALSO'; 533 ds-format = 'mdoc'; 534 ds-text = <<- _END_MDOC_SEE_ALSO 535.Xr ntp.conf 5 , 536.Xr ntpdate 1ntpdatemdoc , 537.Xr ntpdc 1ntpdcmdoc , 538.Xr ntpq 1ntpqmdoc , 539.Xr sntp 1sntpmdoc 540.Pp 541In addition to the manual pages provided, 542comprehensive documentation is available on the world wide web 543at 544.Li http://www.ntp.org/ . 545A snapshot of this documentation is available in HTML format in 546.Pa /usr/share/doc/ntp . 547.Rs 548.%A David L. Mills 549.%T Network Time Protocol (Version 1) 550.%O RFC1059 551.Re 552.Rs 553.%A David L. Mills 554.%T Network Time Protocol (Version 2) 555.%O RFC1119 556.Re 557.Rs 558.%A David L. Mills 559.%T Network Time Protocol (Version 3) 560.%O RFC1305 561.Re 562.Rs 563.%A David L. Mills 564.%A J. Martin, Ed. 565.%A J. Burbank 566.%A W. Kasch 567.%T Network Time Protocol Version 4: Protocol and Algorithms Specification 568.%O RFC5905 569.Re 570.Rs 571.%A David L. Mills 572.%A B. Haberman, Ed. 573.%T Network Time Protocol Version 4: Autokey Specification 574.%O RFC5906 575.Re 576.Rs 577.%A H. Gerstung 578.%A C. Elliott 579.%A B. Haberman, Ed. 580.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) 581.%O RFC5907 582.Re 583.Rs 584.%A R. Gayraud 585.%A B. Lourdelet 586.%T Network Time Protocol (NTP) Server Option for DHCPv6 587.%O RFC5908 588.Re 589 _END_MDOC_SEE_ALSO; 590}; 591 592doc-section = { 593 ds-type = 'BUGS'; 594 ds-format = 'mdoc'; 595 ds-text = <<- _END_MDOC_BUGS 596The 597.Nm 598utility has gotten rather fat. 599While not huge, it has gotten 600larger than might be desirable for an elevated-priority 601.Nm 602running on a workstation, particularly since many of 603the fancy features which consume the space were designed more with 604a busy primary server, rather than a high stratum workstation in 605mind. 606 _END_MDOC_BUGS; 607}; 608 609doc-section = { 610 ds-type = 'NOTES'; 611 ds-format = 'mdoc'; 612 ds-text = <<- _END_MDOC_NOTES 613Portions of this document came from FreeBSD. 614 _END_MDOC_NOTES; 615}; 616