xref: /freebsd/contrib/ntp/ntpd/ntpd.mdoc.in (revision f5f40dd63bc7acbb5312b26ac1ea1103c12352a6)
1.Dd May 25 2024
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  May 25, 2024 at 12:03:54 AM by AutoGen 5.18.16
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\-2024 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: https://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