"Fossies" - the Fresh Open Source Software Archive 
"Fossies" - the Fresh Open Source Software Archive 
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 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 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 621 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 633 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 642 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 657 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 732 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 751 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 792 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 837 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 873 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 892 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[]. 899 .SH "ENVIRONMENT" 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 916 .SH "EXIT STATUS" 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 937 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 948 949 David L. Mills, 950 \fINetwork Time Protocol (Version 2)\fR, 951 RFC1119 952 .PP 953 954 David L. Mills, 955 \fINetwork Time Protocol (Version 3)\fR, 956 RFC1305 957 .PP 958 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 963 964 David L. Mills and B. Haberman, Ed., 965 \fINetwork Time Protocol Version 4: Autokey Specification\fR, 966 RFC5906 967 .PP 968 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 973 974 R. Gayraud and B. Lourdelet, 975 \fINetwork Time Protocol (NTP) Server Option for DHCPv6\fR, 976 RFC5908 977 .PP 978 979 .SH "AUTHORS" 980 The University of Delaware and Network Time Foundation 981 .SH "COPYRIGHT" 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 997 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 1003 1004 This manual page was \fIAutoGen\fP-erated from the \fBntpd\fP 1005 option definitions.