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