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