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