contrib/ntp/ntpd/ntpd.1ntpdman

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