"Fossies" - the Fresh Open Source Software Archive

Member "ntp-4.2.8p15/ntpd/ntpd.1ntpdmdoc" (23 Jun 2020, 29770 Bytes) of package /linux/misc/ntp-4.2.8p15.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "ntpd.1ntpdmdoc": 4.2.8p14_vs_4.2.8p15.

A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.

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