ntpd.mdoc.in revision 309007
1.Dd November 21 2016 2.Dt NTPD @NTPD_MS@ User Commands 3.Os 4.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) 5.\" 6.\" It has been AutoGen-ed November 21, 2016 at 08:02:08 AM by AutoGen 5.18.5 7.\" From the definitions ntpd-opts.def 8.\" and the template file agmdoc-cmd.tpl 9.Sh NAME 10.Nm ntpd 11.Nd NTP daemon program 12.Sh SYNOPSIS 13.Nm 14.\" Mixture of short (flag) options and long options 15.Op Fl flags 16.Op Fl flag Op Ar value 17.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 18[ <server1> ... <serverN> ] 19.Pp 20.Sh DESCRIPTION 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 @NTPQ_MS@ 76and 77.Xr ntpdc @NTPDC_MS@ 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.Sh "OPTIONS" 90.Bl -tag 91.It Fl 4 , Fl \-ipv4 92Force IPv4 DNS name resolution. 93This option must not appear in combination with any of the following options: 94ipv6. 95.sp 96Force DNS resolution of following host names on the command line 97to the IPv4 namespace. 98.It Fl 6 , Fl \-ipv6 99Force IPv6 DNS name resolution. 100This option must not appear in combination with any of the following options: 101ipv4. 102.sp 103Force DNS resolution of following host names on the command line 104to the IPv6 namespace. 105.It Fl a , Fl \-authreq 106Require crypto authentication. 107This option must not appear in combination with any of the following options: 108authnoreq. 109.sp 110Require cryptographic authentication for broadcast client, 111multicast client and symmetric passive associations. 112This is the default. 113.It Fl A , Fl \-authnoreq 114Do not require crypto authentication. 115This option must not appear in combination with any of the following options: 116authreq. 117.sp 118Do not require cryptographic authentication for broadcast client, 119multicast client and symmetric passive associations. 120This is almost never a good idea. 121.It Fl b , Fl \-bcastsync 122Allow us to sync to broadcast servers. 123.sp 124.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string 125configuration file name. 126.sp 127The name and path of the configuration file, 128\fI/etc/ntp.conf\fP 129by default. 130.It Fl d , Fl \-debug\-level 131Increase debug verbosity level. 132This option may appear an unlimited number of times. 133.sp 134.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 135Set the debug verbosity level. 136This option may appear an unlimited number of times. 137This option takes an integer number as its argument. 138.sp 139.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string 140frequency drift file name. 141.sp 142The name and path of the frequency file, 143\fI/etc/ntp.drift\fP 144by default. 145This is the same operation as the 146\fBdriftfile\fP \fIdriftfile\fP 147configuration specification in the 148\fI/etc/ntp.conf\fP 149file. 150.It Fl g , Fl \-panicgate 151Allow the first adjustment to be Big. 152This option may appear an unlimited number of times. 153.sp 154Normally, 155\fBntpd\fP 156exits 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, 157\fBntpd\fP 158will exit with a message to the system log. This option can be used with the 159\fB\-q\fP 160and 161\fB\-x\fP 162options. 163See the 164\fBtinker\fP 165configuration file directive for other options. 166.It Fl G , Fl \-force\-step\-once 167Step any initial offset correction.. 168.sp 169Normally, 170\fBntpd\fP 171steps the time if the time offset exceeds the step threshold, 172which is 128 ms by default, and otherwise slews the time. 173This option forces the initial offset correction to be stepped, 174so the highest time accuracy can be achieved quickly. 175However, this may also cause the time to be stepped back 176so this option must not be used if 177applications requiring monotonic time are running. 178See the \fBtinker\fP configuration file directive for other options. 179.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string 180Jail directory. 181.sp 182Chroot the server to the directory 183\fIjaildir\fP 184. 185This option also implies that the server attempts to drop root privileges at startup. 186You may need to also specify a 187\fB\-u\fP 188option. 189This option is only available if the OS supports adjusting the clock 190without full root privileges. 191This option is supported under NetBSD (configure with 192\fB\-\-enable\-clockctl\fP) or Linux (configure with 193\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 194.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface 195Listen on an interface name or address. 196This option may appear an unlimited number of times. 197.sp 198Open the network address given, or all the addresses associated with the 199given interface name. This option may appear multiple times. This option 200also implies not opening other addresses, except wildcard and localhost. 201This option is deprecated. Please consider using the configuration file 202\fBinterface\fP command, which is more versatile. 203.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string 204path to symmetric keys. 205.sp 206Specify the name and path of the symmetric key file. 207\fI/etc/ntp.keys\fP 208is the default. 209This is the same operation as the 210\fBkeys\fP \fIkeyfile\fP 211configuration file directive. 212.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string 213path to the log file. 214.sp 215Specify the name and path of the log file. 216The default is the system log file. 217This is the same operation as the 218\fBlogfile\fP \fIlogfile\fP 219configuration file directive. 220.It Fl L , Fl \-novirtualips 221Do not listen to virtual interfaces. 222.sp 223Do not listen to virtual interfaces, defined as those with 224names containing a colon. This option is deprecated. Please 225consider using the configuration file \fBinterface\fP command, which 226is more versatile. 227.It Fl M , Fl \-modifymmtimer 228Modify Multimedia Timer (Windows only). 229.sp 230Set the Windows Multimedia Timer to highest resolution. This 231ensures the resolution does not change while ntpd is running, 232avoiding timekeeping glitches associated with changes. 233.It Fl n , Fl \-nofork 234Do not fork. 235This option must not appear in combination with any of the following options: 236wait\-sync. 237.sp 238.It Fl N , Fl \-nice 239Run at high priority. 240.sp 241To the extent permitted by the operating system, run 242\fBntpd\fP 243at the highest priority. 244.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string 245path to the PID file. 246.sp 247Specify the name and path of the file used to record 248\fBntpd\fP's 249process ID. 250This is the same operation as the 251\fBpidfile\fP \fIpidfile\fP 252configuration file directive. 253.It Fl P Ar number , Fl \-priority Ns = Ns Ar number 254Process priority. 255This option takes an integer number as its argument. 256.sp 257To the extent permitted by the operating system, run 258\fBntpd\fP 259at the specified 260\fBsched_setscheduler(SCHED_FIFO)\fP 261priority. 262.It Fl q , Fl \-quit 263Set the time and quit. 264This option must not appear in combination with any of the following options: 265saveconfigquit, wait\-sync. 266.sp 267\fBntpd\fP 268will not daemonize and will exit after the clock is first 269synchronized. This behavior mimics that of the 270\fBntpdate\fP 271program, which will soon be replaced with a shell script. 272The 273\fB\-g\fP 274and 275\fB\-x\fP 276options can be used with this option. 277Note: The kernel time discipline is disabled with this option. 278.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string 279Broadcast/propagation delay. 280.sp 281Specify 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. 282.It Fl \-saveconfigquit Ns = Ns Ar string 283Save parsed configuration and quit. 284This option must not appear in combination with any of the following options: 285quit, wait\-sync. 286.sp 287Cause \fBntpd\fP to parse its startup configuration file and save an 288equivalent to the given filename and exit. This option was 289designed for automated testing. 290.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string 291Statistics file location. 292.sp 293Specify the directory path for files created by the statistics facility. 294This is the same operation as the 295\fBstatsdir\fP \fIstatsdir\fP 296configuration file directive. 297.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey 298Trusted key number. 299This option may appear an unlimited number of times. 300.sp 301Add the specified key number to the trusted key list. 302.It Fl u Ar string , Fl \-user Ns = Ns Ar string 303Run as userid (or userid:groupid). 304.sp 305Specify a user, and optionally a group, to switch to. 306This option is only available if the OS supports adjusting the clock 307without full root privileges. 308This option is supported under NetBSD (configure with 309\fB\-\-enable\-clockctl\fP) or Linux (configure with 310\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 311.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number 312interval in seconds between scans for new or dropped interfaces. 313This option takes an integer number as its argument. 314.sp 315Give the time in seconds between two scans for new or dropped interfaces. 316For systems with routing socket support the scans will be performed shortly after the interface change 317has been detected by the system. 318Use 0 to disable scanning. 60 seconds is the minimum time between scans. 319.It Fl \-var Ns = Ns Ar nvar 320make ARG an ntp variable (RW). 321This option may appear an unlimited number of times. 322.sp 323.It Fl \-dvar Ns = Ns Ar ndvar 324make ARG an ntp variable (RW|DEF). 325This option may appear an unlimited number of times. 326.sp 327.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number 328Seconds to wait for first clock sync. 329This option must not appear in combination with any of the following options: 330nofork, quit, saveconfigquit. 331This option takes an integer number as its argument. 332.sp 333If greater than zero, alters \fBntpd\fP's behavior when forking to 334daemonize. Instead of exiting with status 0 immediately after 335the fork, the parent waits up to the specified number of 336seconds for the child to first synchronize the clock. The exit 337status is zero (success) if the clock was synchronized, 338otherwise it is \fBETIMEDOUT\fP. 339This provides the option for a script starting \fBntpd\fP to easily 340wait for the first set of the clock before proceeding. 341.It Fl x , Fl \-slew 342Slew up to 600 seconds. 343.sp 344Normally, 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. 345This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 346Note: 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. 347Thus, an adjustment as much as 600 s will take almost 14 days to complete. 348This option can be used with the 349\fB\-g\fP 350and 351\fB\-q\fP 352options. 353See the 354\fBtinker\fP 355configuration file directive for other options. 356Note: The kernel time discipline is disabled with this option. 357.It Fl \-usepcc 358Use CPU cycle counter (Windows only). 359.sp 360Attempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 361The CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 362they have the same frequency, the CPU counter (RDTSC on x86) is 363used directly, saving the overhead of a system call. 364.It Fl \-pccfreq Ns = Ns Ar string 365Force CPU cycle counter use (Windows only). 366.sp 367Force substitution the CPU counter for \fBQueryPerformanceCounter\fP. 368The CPU counter (RDTSC on x86) is used unconditionally with the 369given frequency (in Hz). 370.It Fl m , Fl \-mdns 371Register with mDNS as a NTP server. 372.sp 373Registers as an NTP server with the local mDNS server which allows 374the server to be discovered via mDNS client lookup. 375.It Fl \&? , Fl \-help 376Display usage information and exit. 377.It Fl \&! , Fl \-more\-help 378Pass the extended usage information through a pager. 379.It Fl \-version Op Brq Ar v|c|n 380Output version of program and exit. The default mode is `v', a simple 381version. The `c' mode will print copyright information and `n' will 382print the full copyright notice. 383.El 384.Sh "OPTION PRESETS" 385Any option that is not marked as \fInot presettable\fP may be preset 386by loading values from environment variables named: 387.nf 388 \fBNTPD_<option\-name>\fP or \fBNTPD\fP 389.fi 390.ad 391.Sh USAGE 392.Ss "How NTP Operates" 393The 394.Nm 395utility operates by exchanging messages with 396one or more configured servers over a range of designated poll intervals. 397When 398started, whether for the first or subsequent times, the program 399requires several exchanges from the majority of these servers so 400the signal processing and mitigation algorithms can accumulate and 401groom the data and set the clock. 402In order to protect the network 403from bursts, the initial poll interval for each server is delayed 404an interval randomized over a few seconds. 405At the default initial poll 406interval of 64s, several minutes can elapse before the clock is 407set. 408This initial delay to set the clock 409can be safely and dramatically reduced using the 410.Cm iburst 411keyword with the 412.Ic server 413configuration 414command, as described in 415.Xr ntp.conf 5 . 416.Pp 417Most operating systems and hardware of today incorporate a 418time\-of\-year (TOY) chip to maintain the time during periods when 419the power is off. 420When the machine is booted, the chip is used to 421initialize the operating system time. 422After the machine has 423synchronized to a NTP server, the operating system corrects the 424chip from time to time. 425In the default case, if 426.Nm 427detects that the time on the host 428is more than 1000s from the server time, 429.Nm 430assumes something must be terribly wrong and the only 431reliable action is for the operator to intervene and set the clock 432by hand. 433(Reasons for this include there is no TOY chip, 434or its battery is dead, or that the TOY chip is just of poor quality.) 435This causes 436.Nm 437to exit with a panic message to 438the system log. 439The 440.Fl g 441option overrides this check and the 442clock will be set to the server time regardless of the chip time 443(up to 68 years in the past or future \(em 444this is a limitation of the NTPv4 protocol). 445However, and to protect against broken hardware, such as when the 446CMOS battery fails or the clock counter becomes defective, once the 447clock has been set an error greater than 1000s will cause 448.Nm 449to exit anyway. 450.Pp 451Under ordinary conditions, 452.Nm 453adjusts the clock in 454small steps so that the timescale is effectively continuous and 455without discontinuities. 456Under conditions of extreme network 457congestion, the roundtrip delay jitter can exceed three seconds and 458the synchronization distance, which is equal to one\-half the 459roundtrip delay plus error budget terms, can become very large. 460The 461.Nm 462algorithms discard sample offsets exceeding 128 ms, 463unless the interval during which no sample offset is less than 128 464ms exceeds 900s. 465The first sample after that, no matter what the 466offset, steps the clock to the indicated time. 467In practice this 468reduces the false alarm rate where the clock is stepped in error to 469a vanishingly low incidence. 470.Pp 471As the result of this behavior, once the clock has been set it 472very rarely strays more than 128 ms even under extreme cases of 473network path congestion and jitter. 474Sometimes, in particular when 475.Nm 476is first started without a valid drift file 477on a system with a large intrinsic drift 478the error might grow to exceed 128 ms, 479which would cause the clock to be set backwards 480if the local clock time is more than 128 s 481in the future relative to the server. 482In some applications, this behavior may be unacceptable. 483There are several solutions, however. 484If the 485.Fl x 486option is included on the command line, the clock will 487never be stepped and only slew corrections will be used. 488But this choice comes with a cost that 489should be carefully explored before deciding to use 490the 491.Fl x 492option. 493The maximum slew rate possible is limited 494to 500 parts\-per\-million (PPM) as a consequence of the correctness 495principles on which the NTP protocol and algorithm design are 496based. 497As a result, the local clock can take a long time to 498converge to an acceptable offset, about 2,000 s for each second the 499clock is outside the acceptable range. 500During this interval the 501local clock will not be consistent with any other network clock and 502the system cannot be used for distributed applications that require 503correctly synchronized network time. 504.Pp 505In spite of the above precautions, sometimes when large 506frequency errors are present the resulting time offsets stray 507outside the 128\-ms range and an eventual step or slew time 508correction is required. 509If following such a correction the 510frequency error is so large that the first sample is outside the 511acceptable range, 512.Nm 513enters the same state as when the 514.Pa ntp.drift 515file is not present. 516The intent of this behavior 517is to quickly correct the frequency and restore operation to the 518normal tracking mode. 519In the most extreme cases 520(the host 521.Cm time.ien.it 522comes to mind), there may be occasional 523step/slew corrections and subsequent frequency corrections. 524It 525helps in these cases to use the 526.Cm burst 527keyword when 528configuring the server, but 529ONLY 530when you have permission to do so from the owner of the target host. 531.Pp 532Finally, 533in the past many startup scripts would run 534.Xr ntpdate @NTPDATE_MS@ 535or 536.Xr sntp @SNTP_MS@ 537to get the system clock close to correct before starting 538.Xr ntpd @NTPD_MS@ , 539but this was never more than a mediocre hack and is no longer needed. 540If you are following the instructions in 541.Sx "Starting NTP (Best Current Practice)" 542and you still need to set the system time before starting 543.Nm , 544please open a bug report and document what is going on, 545and then look at using 546.Xr sntp @SNTP_MS@ 547if you really need to set the clock before starting 548.Nm . 549.Pp 550There is a way to start 551.Xr ntpd @NTPD_MS@ 552that often addresses all of the problems mentioned above. 553.Ss "Starting NTP (Best Current Practice)" 554First, use the 555.Cm iburst 556option on your 557.Cm server 558entries. 559.Pp 560If you can also keep a good 561.Pa ntp.drift 562file then 563.Xr ntpd @NTPD_MS@ 564will effectively "warm\-start" and your system's clock will 565be stable in under 11 seconds' time. 566.Pp 567As soon as possible in the startup sequence, start 568.Xr ntpd @NTPD_MS@ 569with at least the 570.Fl g 571and perhaps the 572.Fl N 573options. 574Then, 575start the rest of your "normal" processes. 576This will give 577.Xr ntpd @NTPD_MS@ 578as much time as possible to get the system's clock synchronized and stable. 579.Pp 580Finally, 581if you have processes like 582.Cm dovecot 583or database servers 584that require 585monotonically\-increasing time, 586run 587.Xr ntp\-wait 1ntp\-waitmdoc 588as late as possible in the boot sequence 589(perhaps with the 590.Fl v 591flag) 592and after 593.Xr ntp\-wait 1ntp\-waitmdoc 594exits successfully 595it is as safe as it will ever be to start any process that require 596stable time. 597.Ss "Frequency Discipline" 598The 599.Nm 600behavior at startup depends on whether the 601frequency file, usually 602.Pa ntp.drift , 603exists. 604This file 605contains the latest estimate of clock frequency error. 606When the 607.Nm 608is started and the file does not exist, the 609.Nm 610enters a special mode designed to quickly adapt to 611the particular system clock oscillator time and frequency error. 612This takes approximately 15 minutes, after which the time and 613frequency are set to nominal values and the 614.Nm 615enters 616normal mode, where the time and frequency are continuously tracked 617relative to the server. 618After one hour the frequency file is 619created and the current frequency offset written to it. 620When the 621.Nm 622is started and the file does exist, the 623.Nm 624frequency is initialized from the file and enters normal mode 625immediately. 626After that the current frequency offset is written to 627the file at hourly intervals. 628.Ss "Operating Modes" 629The 630.Nm 631utility can operate in any of several modes, including 632symmetric active/passive, client/server broadcast/multicast and 633manycast, as described in the 634.Qq Association Management 635page 636(available as part of the HTML documentation 637provided in 638.Pa /usr/share/doc/ntp ) . 639It normally operates continuously while 640monitoring for small changes in frequency and trimming the clock 641for the ultimate precision. 642However, it can operate in a one\-time 643mode where the time is set from an external server and frequency is 644set from a previously recorded frequency file. 645A 646broadcast/multicast or manycast client can discover remote servers, 647compute server\-client propagation delay correction factors and 648configure itself automatically. 649This makes it possible to deploy a 650fleet of workstations without specifying configuration details 651specific to the local environment. 652.Pp 653By default, 654.Nm 655runs in continuous mode where each of 656possibly several external servers is polled at intervals determined 657by an intricate state machine. 658The state machine measures the 659incidental roundtrip delay jitter and oscillator frequency wander 660and determines the best poll interval using a heuristic algorithm. 661Ordinarily, and in most operating environments, the state machine 662will start with 64s intervals and eventually increase in steps to 6631024s. 664A small amount of random variation is introduced in order to 665avoid bunching at the servers. 666In addition, should a server become 667unreachable for some time, the poll interval is increased in steps 668to 1024s in order to reduce network overhead. 669.Pp 670In some cases it may not be practical for 671.Nm 672to run continuously. 673A common workaround has been to run the 674.Xr ntpdate @NTPDATE_MS@ 675or 676.Xr sntp @SNTP_MS@ 677programs from a 678.Xr cron 8 679job at designated 680times. 681However, these programs do not have the crafted signal 682processing, error checking or mitigation algorithms of 683.Nm . 684The 685.Fl q 686option is intended for this purpose. 687Setting this option will cause 688.Nm 689to exit just after 690setting the clock for the first time. 691The procedure for initially 692setting the clock is the same as in continuous mode; most 693applications will probably want to specify the 694.Cm iburst 695keyword with the 696.Ic server 697configuration command. 698With this 699keyword a volley of messages are exchanged to groom the data and 700the clock is set in about 10 s. 701If nothing is heard after a 702couple of minutes, the daemon times out and exits. 703After a suitable 704period of mourning, the 705.Xr ntpdate @NTPDATE_MS@ 706program will be 707retired. 708.Pp 709When kernel support is available to discipline the clock 710frequency, which is the case for stock Solaris, Tru64, Linux and 711.Fx , 712a useful feature is available to discipline the clock 713frequency. 714First, 715.Nm 716is run in continuous mode with 717selected servers in order to measure and record the intrinsic clock 718frequency offset in the frequency file. 719It may take some hours for 720the frequency and offset to settle down. 721Then the 722.Nm 723is 724stopped and run in one\-time mode as required. 725At each startup, the 726frequency is read from the file and initializes the kernel 727frequency. 728.Ss "Poll Interval Control" 729This version of NTP includes an intricate state machine to 730reduce the network load while maintaining a quality of 731synchronization consistent with the observed jitter and wander. 732There are a number of ways to tailor the operation in order enhance 733accuracy by reducing the interval or to reduce network overhead by 734increasing it. 735However, the user is advised to carefully consider 736the consequences of changing the poll adjustment range from the 737default minimum of 64 s to the default maximum of 1,024 s. 738The 739default minimum can be changed with the 740.Ic tinker 741.Cm minpoll 742command to a value not less than 16 s. 743This value is used for all 744configured associations, unless overridden by the 745.Cm minpoll 746option on the configuration command. 747Note that most device drivers 748will not operate properly if the poll interval is less than 64 s 749and that the broadcast server and manycast client associations will 750also use the default, unless overridden. 751.Pp 752In some cases involving dial up or toll services, it may be 753useful to increase the minimum interval to a few tens of minutes 754and maximum interval to a day or so. 755Under normal operation 756conditions, once the clock discipline loop has stabilized the 757interval will be increased in steps from the minimum to the 758maximum. 759However, this assumes the intrinsic clock frequency error 760is small enough for the discipline loop correct it. 761The capture 762range of the loop is 500 PPM at an interval of 64s decreasing by a 763factor of two for each doubling of interval. 764At a minimum of 1,024 765s, for example, the capture range is only 31 PPM. 766If the intrinsic 767error is greater than this, the drift file 768.Pa ntp.drift 769will 770have to be specially tailored to reduce the residual error below 771this limit. 772Once this is done, the drift file is automatically 773updated once per hour and is available to initialize the frequency 774on subsequent daemon restarts. 775.Ss "The huff\-n'\-puff Filter" 776In scenarios where a considerable amount of data are to be 777downloaded or uploaded over telephone modems, timekeeping quality 778can be seriously degraded. 779This occurs because the differential 780delays on the two directions of transmission can be quite large. 781In 782many cases the apparent time errors are so large as to exceed the 783step threshold and a step correction can occur during and after the 784data transfer is in progress. 785.Pp 786The huff\-n'\-puff filter is designed to correct the apparent time 787offset in these cases. 788It depends on knowledge of the propagation 789delay when no other traffic is present. 790In common scenarios this 791occurs during other than work hours. 792The filter maintains a shift 793register that remembers the minimum delay over the most recent 794interval measured usually in hours. 795Under conditions of severe 796delay, the filter corrects the apparent offset using the sign of 797the offset and the difference between the apparent delay and 798minimum delay. 799The name of the filter reflects the negative (huff) 800and positive (puff) correction, which depends on the sign of the 801offset. 802.Pp 803The filter is activated by the 804.Ic tinker 805command and 806.Cm huffpuff 807keyword, as described in 808.Xr ntp.conf 5 . 809.Sh "ENVIRONMENT" 810See \fBOPTION PRESETS\fP for configuration environment variables. 811.Sh FILES 812.Bl -tag -width /etc/ntp.drift -compact 813.It Pa /etc/ntp.conf 814the default name of the configuration file 815.It Pa /etc/ntp.drift 816the default name of the drift file 817.It Pa /etc/ntp.keys 818the default name of the key file 819.El 820.Sh "EXIT STATUS" 821One of the following exit values will be returned: 822.Bl -tag 823.It 0 " (EXIT_SUCCESS)" 824Successful program execution. 825.It 1 " (EXIT_FAILURE)" 826The operation failed or the command syntax was not valid. 827.It 70 " (EX_SOFTWARE)" 828libopts had an internal operational error. Please report 829it to autogen\-users@lists.sourceforge.net. Thank you. 830.El 831.Sh "SEE ALSO" 832.Xr ntp.conf 5 , 833.Xr ntpdate @NTPDATE_MS@ , 834.Xr ntpdc @NTPDC_MS@ , 835.Xr ntpq @NTPQ_MS@ , 836.Xr sntp @SNTP_MS@ 837.Pp 838In addition to the manual pages provided, 839comprehensive documentation is available on the world wide web 840at 841.Li http://www.ntp.org/ . 842A snapshot of this documentation is available in HTML format in 843.Pa /usr/share/doc/ntp . 844.Rs 845.%A David L. Mills 846.%T Network Time Protocol (Version 1) 847.%O RFC1059 848.Re 849.Rs 850.%A David L. Mills 851.%T Network Time Protocol (Version 2) 852.%O RFC1119 853.Re 854.Rs 855.%A David L. Mills 856.%T Network Time Protocol (Version 3) 857.%O RFC1305 858.Re 859.Rs 860.%A David L. Mills 861.%A J. Martin, Ed. 862.%A J. Burbank 863.%A W. Kasch 864.%T Network Time Protocol Version 4: Protocol and Algorithms Specification 865.%O RFC5905 866.Re 867.Rs 868.%A David L. Mills 869.%A B. Haberman, Ed. 870.%T Network Time Protocol Version 4: Autokey Specification 871.%O RFC5906 872.Re 873.Rs 874.%A H. Gerstung 875.%A C. Elliott 876.%A B. Haberman, Ed. 877.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) 878.%O RFC5907 879.Re 880.Rs 881.%A R. Gayraud 882.%A B. Lourdelet 883.%T Network Time Protocol (NTP) Server Option for DHCPv6 884.%O RFC5908 885.Re 886.Sh "AUTHORS" 887The University of Delaware and Network Time Foundation 888.Sh "COPYRIGHT" 889Copyright (C) 1992\-2016 The University of Delaware and Network Time Foundation all rights reserved. 890This program is released under the terms of the NTP license, <http://ntp.org/license>. 891.Sh BUGS 892The 893.Nm 894utility has gotten rather fat. 895While not huge, it has gotten 896larger than might be desirable for an elevated\-priority 897.Nm 898running on a workstation, particularly since many of 899the fancy features which consume the space were designed more with 900a busy primary server, rather than a high stratum workstation in 901mind. 902.Pp 903Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 904.Sh NOTES 905Portions of this document came from FreeBSD. 906.Pp 907This manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP 908option definitions. 909