contrib/ntp/ntpd/ntpd.man.in

   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@ "29 Jun 2015" "4.2.8p3" "User Commands"
  14 .\"
  15 .\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-LZaapD/ag-XZa4nD)
  16 .\"
  17 .\" It has been AutoGen-ed June 29, 2015 at 04:30:24 PM 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
  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\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
  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\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
  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\f[]\fR(@NTPQ_MS@)\f[]
  97 and
  98 \fCntpdc\f[]\fR(@NTPDC_MS@)\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\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
 444 .SH "OPTION PRESETS"
 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
 478
 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
 514
 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
 536
 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
 572
 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
 601
 602 Finally,
 603 in the past many startup scripts would run
 604 \fCntpdate\f[]\fR(@NTPDATE_MS@)\f[]
 605 to get the system clock close to correct before starting
 606 \fCntpd\f[]\fR(@NTPD_MS@)\f[],
 607 but this was never more than a mediocre hack and is no longer needed.
 608 If you are following the instructions in
 609 \fIStarting NTP (Best Current Practice)\f[]
 610 and you still need to set the system time before starting
 611 \f\*[B-Font]ntpd\fP,
 612 please open a bug report and document what is going on,
 613 and then look at using
 614 \fCsntp\f[]\fR(@SNTP_MS@)\f[].
 615 .sp \n(Ppu
 616 .ne 2
 617
 618 There is a way to start
 619 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
 620 that often addresses all of the problems mentioned above.
 621 .SS "Starting NTP (Best Current Practice)"
 622 First, use the
 623 \f\*[B-Font]iburst\f[]
 624 option on your
 625 \f\*[B-Font]server\f[]
 626 entries.
 627 .sp \n(Ppu
 628 .ne 2
 629
 630 If you can also keep a good
 631 \fIntp.drift\f[]
 632 file then
 633 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
 634 will effectively "warm-start" and your system's clock will
 635 be stable in under 11 seconds' time.
 636 .sp \n(Ppu
 637 .ne 2
 638
 639 As soon as possible in the startup sequence, start
 640 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
 641 with at least the
 642 \f\*[B-Font]\-g\f[]
 643 and perhaps the
 644 \f\*[B-Font]\-N\f[]
 645 options.
 646 Then,
 647 start the rest of your "normal" processes.
 648 This will give
 649 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
 650 as much time as possible to get the system's clock synchronized and stable.
 651 .sp \n(Ppu
 652 .ne 2
 653
 654 Finally,
 655 if you have processes like
 656 \f\*[B-Font]dovecot\f[]
 657 or database servers
 658 that require
 659 monotonically-increasing time,
 660 run
 661 \fCntp-wait\f[]\fR(@NTP_WAIT_MS@)\f[]
 662 as late as possible in the boot sequence
 663 (perhaps with the
 664 \f\*[B-Font]\-v\f[]
 665 flag)
 666 and after
 667 \fCntp-wait\f[]\fR(@NTP_WAIT_MS@)\f[]
 668 exits successfully
 669 it is as safe as it will ever be to start any process that require
 670 stable time.
 671 .SS "Frequency Discipline"
 672 The
 673 \f\*[B-Font]ntpd\fP
 674 behavior at startup depends on whether the
 675 frequency file, usually
 676 \fIntp.drift\f[],
 677 exists.
 678 This file
 679 contains the latest estimate of clock frequency error.
 680 When the
 681 \f\*[B-Font]ntpd\fP
 682 is started and the file does not exist, the
 683 \f\*[B-Font]ntpd\fP
 684 enters a special mode designed to quickly adapt to
 685 the particular system clock oscillator time and frequency error.
 686 This takes approximately 15 minutes, after which the time and
 687 frequency are set to nominal values and the
 688 \f\*[B-Font]ntpd\fP
 689 enters
 690 normal mode, where the time and frequency are continuously tracked
 691 relative to the server.
 692 After one hour the frequency file is
 693 created and the current frequency offset written to it.
 694 When the
 695 \f\*[B-Font]ntpd\fP
 696 is started and the file does exist, the
 697 \f\*[B-Font]ntpd\fP
 698 frequency is initialized from the file and enters normal mode
 699 immediately.
 700 After that the current frequency offset is written to
 701 the file at hourly intervals.
 702 .SS "Operating Modes"
 703 The
 704 \f\*[B-Font]ntpd\fP
 705 utility can operate in any of several modes, including
 706 symmetric active/passive, client/server broadcast/multicast and
 707 manycast, as described in the
 708 "Association Management"
 709 page
 710 (available as part of the HTML documentation
 711 provided in
 712 \fI/usr/share/doc/ntp\f[]).
 713 It normally operates continuously while
 714 monitoring for small changes in frequency and trimming the clock
 715 for the ultimate precision.
 716 However, it can operate in a one-time
 717 mode where the time is set from an external server and frequency is
 718 set from a previously recorded frequency file.
 719 A
 720 broadcast/multicast or manycast client can discover remote servers,
 721 compute server-client propagation delay correction factors and
 722 configure itself automatically.
 723 This makes it possible to deploy a
 724 fleet of workstations without specifying configuration details
 725 specific to the local environment.
 726 .sp \n(Ppu
 727 .ne 2
 728
 729 By default,
 730 \f\*[B-Font]ntpd\fP
 731 runs in continuous mode where each of
 732 possibly several external servers is polled at intervals determined
 733 by an intricate state machine.
 734 The state machine measures the
 735 incidental roundtrip delay jitter and oscillator frequency wander
 736 and determines the best poll interval using a heuristic algorithm.
 737 Ordinarily, and in most operating environments, the state machine
 738 will start with 64s intervals and eventually increase in steps to
 739 1024s.
 740 A small amount of random variation is introduced in order to
 741 avoid bunching at the servers.
 742 In addition, should a server become
 743 unreachable for some time, the poll interval is increased in steps
 744 to 1024s in order to reduce network overhead.
 745 .sp \n(Ppu
 746 .ne 2
 747
 748 In some cases it may not be practical for
 749 \f\*[B-Font]ntpd\fP
 750 to run continuously.
 751 A common workaround has been to run the
 752 \fCntpdate\f[]\fR(@NTPDATE_MS@)\f[]
 753 or
 754 \fCsntp\f[]\fR(@SNTP_MS@)\f[]
 755 programs from a
 756 \fCcron\f[]\fR(8)\f[]
 757 job at designated
 758 times.
 759 However, these programs do not have the crafted signal
 760 processing, error checking or mitigation algorithms of
 761 \f\*[B-Font]ntpd\fP.
 762 The
 763 \f\*[B-Font]\-q\f[]
 764 option is intended for this purpose.
 765 Setting this option will cause
 766 \f\*[B-Font]ntpd\fP
 767 to exit just after
 768 setting the clock for the first time.
 769 The procedure for initially
 770 setting the clock is the same as in continuous mode; most
 771 applications will probably want to specify the
 772 \f\*[B-Font]iburst\f[]
 773 keyword with the
 774 \f\*[B-Font]server\f[]
 775 configuration command.
 776 With this
 777 keyword a volley of messages are exchanged to groom the data and
 778 the clock is set in about 10 s.
 779 If nothing is heard after a
 780 couple of minutes, the daemon times out and exits.
 781 After a suitable
 782 period of mourning, the
 783 \fCntpdate\f[]\fR(@NTPDATE_MS@)\f[]
 784 program will be
 785 retired.
 786 .sp \n(Ppu
 787 .ne 2
 788
 789 When kernel support is available to discipline the clock
 790 frequency, which is the case for stock Solaris, Tru64, Linux and
 791 FreeBSD,
 792 a useful feature is available to discipline the clock
 793 frequency.
 794 First,
 795 \f\*[B-Font]ntpd\fP
 796 is run in continuous mode with
 797 selected servers in order to measure and record the intrinsic clock
 798 frequency offset in the frequency file.
 799 It may take some hours for
 800 the frequency and offset to settle down.
 801 Then the
 802 \f\*[B-Font]ntpd\fP
 803 is
 804 stopped and run in one-time mode as required.
 805 At each startup, the
 806 frequency is read from the file and initializes the kernel
 807 frequency.
 808 .SS "Poll Interval Control"
 809 This version of NTP includes an intricate state machine to
 810 reduce the network load while maintaining a quality of
 811 synchronization consistent with the observed jitter and wander.
 812 There are a number of ways to tailor the operation in order enhance
 813 accuracy by reducing the interval or to reduce network overhead by
 814 increasing it.
 815 However, the user is advised to carefully consider
 816 the consequences of changing the poll adjustment range from the
 817 default minimum of 64 s to the default maximum of 1,024 s.
 818 The
 819 default minimum can be changed with the
 820 \f\*[B-Font]tinker\f[]
 821 \f\*[B-Font]minpoll\f[]
 822 command to a value not less than 16 s.
 823 This value is used for all
 824 configured associations, unless overridden by the
 825 \f\*[B-Font]minpoll\f[]
 826 option on the configuration command.
 827 Note that most device drivers
 828 will not operate properly if the poll interval is less than 64 s
 829 and that the broadcast server and manycast client associations will
 830 also use the default, unless overridden.
 831 .sp \n(Ppu
 832 .ne 2
 833
 834 In some cases involving dial up or toll services, it may be
 835 useful to increase the minimum interval to a few tens of minutes
 836 and maximum interval to a day or so.
 837 Under normal operation
 838 conditions, once the clock discipline loop has stabilized the
 839 interval will be increased in steps from the minimum to the
 840 maximum.
 841 However, this assumes the intrinsic clock frequency error
 842 is small enough for the discipline loop correct it.
 843 The capture
 844 range of the loop is 500 PPM at an interval of 64s decreasing by a
 845 factor of two for each doubling of interval.
 846 At a minimum of 1,024
 847 s, for example, the capture range is only 31 PPM.
 848 If the intrinsic
 849 error is greater than this, the drift file
 850 \fIntp.drift\f[]
 851 will
 852 have to be specially tailored to reduce the residual error below
 853 this limit.
 854 Once this is done, the drift file is automatically
 855 updated once per hour and is available to initialize the frequency
 856 on subsequent daemon restarts.
 857 .SS "The huff-n'-puff Filter"
 858 In scenarios where a considerable amount of data are to be
 859 downloaded or uploaded over telephone modems, timekeeping quality
 860 can be seriously degraded.
 861 This occurs because the differential
 862 delays on the two directions of transmission can be quite large.
 863 In
 864 many cases the apparent time errors are so large as to exceed the
 865 step threshold and a step correction can occur during and after the
 866 data transfer is in progress.
 867 .sp \n(Ppu
 868 .ne 2
 869
 870 The huff-n'-puff filter is designed to correct the apparent time
 871 offset in these cases.
 872 It depends on knowledge of the propagation
 873 delay when no other traffic is present.
 874 In common scenarios this
 875 occurs during other than work hours.
 876 The filter maintains a shift
 877 register that remembers the minimum delay over the most recent
 878 interval measured usually in hours.
 879 Under conditions of severe
 880 delay, the filter corrects the apparent offset using the sign of
 881 the offset and the difference between the apparent delay and
 882 minimum delay.
 883 The name of the filter reflects the negative (huff)
 884 and positive (puff) correction, which depends on the sign of the
 885 offset.
 886 .sp \n(Ppu
 887 .ne 2
 888
 889 The filter is activated by the
 890 \f\*[B-Font]tinker\f[]
 891 command and
 892 \f\*[B-Font]huffpuff\f[]
 893 keyword, as described in
 894 \fCntp.conf\f[]\fR(5)\f[].
 895 .SH "ENVIRONMENT"
 896 See \fBOPTION PRESETS\fP for configuration environment variables.
 897 .SH FILES
 898 .TP 15
 899 .NOP \fI/etc/ntp.conf\f[]
 900 the default name of the configuration file
 901 .br
 902 .ns
 903 .TP 15
 904 .NOP \fI/etc/ntp.drift\f[]
 905 the default name of the drift file
 906 .br
 907 .ns
 908 .TP 15
 909 .NOP \fI/etc/ntp.keys\f[]
 910 the default name of the key file
 911 .PP
 912 .SH "EXIT STATUS"
 913 One of the following exit values will be returned:
 914 .TP
 915 .NOP 0 " (EXIT_SUCCESS)"
 916 Successful program execution.
 917 .TP
 918 .NOP 1 " (EXIT_FAILURE)"
 919 The operation failed or the command syntax was not valid.
 920 .TP
 921 .NOP 70 " (EX_SOFTWARE)"
 922 libopts had an internal operational error.  Please report
 923 it to autogen-users@lists.sourceforge.net.  Thank you.
 924 .PP
 925 .SH "SEE ALSO"
 926 \fCntp.conf\f[]\fR(5)\f[],
 927 \fCntpdate\f[]\fR(@NTPDATE_MS@)\f[],
 928 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[],
 929 \fCntpq\f[]\fR(@NTPQ_MS@)\f[],
 930 \fCsntp\f[]\fR(@SNTP_MS@)\f[]
 931 .sp \n(Ppu
 932 .ne 2
 933
 934 In addition to the manual pages provided,
 935 comprehensive documentation is available on the world wide web
 936 at
 937 \f[C]http://www.ntp.org/\f[].
 938 A snapshot of this documentation is available in HTML format in
 939 \fI/usr/share/doc/ntp\f[].
 940 David L. Mills,
 941 \fINetwork Time Protocol (Version 1)\fR,
 942 RFC1059
 943 .PP
 944
 945 David L. Mills,
 946 \fINetwork Time Protocol (Version 2)\fR,
 947 RFC1119
 948 .PP
 949
 950 David L. Mills,
 951 \fINetwork Time Protocol (Version 3)\fR,
 952 RFC1305
 953 .PP
 954
 955 David L. Mills and J. Martin, Ed. and J. Burbank and W. Kasch,
 956 \fINetwork Time Protocol Version 4: Protocol and Algorithms Specification\fR,
 957 RFC5905
 958 .PP
 959
 960 David L. Mills and B. Haberman, Ed.,
 961 \fINetwork Time Protocol Version 4: Autokey Specification\fR,
 962 RFC5906
 963 .PP
 964
 965 H. Gerstung and C. Elliott and B. Haberman, Ed.,
 966 \fIDefinitions of Managed Objects for Network Time Protocol Version 4: (NTPv4)\fR,
 967 RFC5907
 968 .PP
 969
 970 R. Gayraud and B. Lourdelet,
 971 \fINetwork Time Protocol (NTP) Server Option for DHCPv6\fR,
 972 RFC5908
 973 .PP
 974
 975 .SH "AUTHORS"
 976 The University of Delaware and Network Time Foundation
 977 .SH "COPYRIGHT"
 978 Copyright (C) 1992-2015 The University of Delaware and Network Time Foundation all rights reserved.
 979 This program is released under the terms of the NTP license, <http://ntp.org/license>.
 980 .SH BUGS
 981 The
 982 \f\*[B-Font]ntpd\fP
 983 utility has gotten rather fat.
 984 While not huge, it has gotten
 985 larger than might be desirable for an elevated-priority
 986 \f\*[B-Font]ntpd\fP
 987 running on a workstation, particularly since many of
 988 the fancy features which consume the space were designed more with
 989 a busy primary server, rather than a high stratum workstation in
 990 mind.
 991 .sp \n(Ppu
 992 .ne 2
 993
 994 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
 995 .SH NOTES
 996 Portions of this document came from FreeBSD.
 997 .sp \n(Ppu
 998 .ne 2
 999
1000 This manual page was \fIAutoGen\fP-erated from the \fBntpd\fP
1001 option definitions.