"Fossies" - the Fresh Open Source Software Archive

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