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