diff options
Diffstat (limited to 'usr.sbin/ntp/doc/ntpd.8')
| -rw-r--r-- | usr.sbin/ntp/doc/ntpd.8 | 594 |
1 files changed, 464 insertions, 130 deletions
diff --git a/usr.sbin/ntp/doc/ntpd.8 b/usr.sbin/ntp/doc/ntpd.8 index cef5366..8fe9dda 100644 --- a/usr.sbin/ntp/doc/ntpd.8 +++ b/usr.sbin/ntp/doc/ntpd.8 @@ -1,7 +1,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 10, 2000 +.Dd August 2, 2001 .Dt NTPD 8 .Os .Sh NAME @@ -9,94 +9,88 @@ .Nd Network Time Protocol (NTP) daemon .Sh SYNOPSIS .Nm -.Op Fl aAbdgmx +.Op Fl aAbdgLmnPqx .Op Fl c Ar conffile +.Op Fl D Ar level .Op Fl f Ar driftfile .Op Fl k Ar keyfile .Op Fl l Ar logfile +.Op Fl N Cm high .Op Fl p Ar pidfile .Op Fl r Ar broadcastdelay .Op Fl s Ar statsdir -.Op Fl t Ar trustedkey +.Op Fl t Ar key .Op Fl v Ar variable .Op Fl V Ar variable .Sh DESCRIPTION +The .Nm -is an operating system daemon -which sets and maintains the system time-of-day -in synchronism with Internet standard time servers. -.Nm -is a complete implementation of the Network Time Protocol (NTP) -version 4, -but also retains compatibility with version 3, -as defined by RFC 1305, -and version 1 and 2, -as defined by RFC 1059 and RFC 1119, -respectively. -.Nm -does most computations in 64-bit floating point arithmetic -and does relatively clumsy 64-bit fixed point operations -only when necessary to preserve the ultimate precision, -about 232 picoseconds. -While the ultimate precision is not achievable -with ordinary workstations and networks of today, -it may be required with future nanosecond CPU clocks and gigabit LANs. -.Pp -The daemon can operate in any of several modes, -including symmetric active/passive, -client/server broadcast/multicast and manycast. -A broadcast/multicast or manycast client can discover remote servers, -compute server-client propagation delay correction factors -and configure itself automatically. -This makes it possible to deploy a fleet of workstations -without specifying configuration details -specific to the local environment. +program is an operating system daemon which sets +and maintains the system time of day in synchronism with Internet +standard time servers. +It is a complete implementation of the +Network Time Protocol (NTP) version 4, but also retains +compatibility with version 3, as defined by RFC-1305, and version 1 +and 2, as defined by RFC-1059 and RFC-1119, respectively. +.Pp +.Nm +does most computations in 64-bit floating point +arithmetic and does relatively clumsy 64-bit fixed point operations +only when necessary to preserve the ultimate precision, about 232 +picoseconds. +While the ultimate precision, is not achievable with +ordinary workstations and networks of today, it may be required +with future gigahertz CPU clocks and gigabit LANs. .Pp Ordinarily, .Nm reads the .Xr ntp.conf 5 -configuration file at startup time -in order to determine the synchronization sources and operating modes. -It is also possible to specify a working, although limited, -configuration entirely on the command line, -obviating the need for a configuration file. -This may be particularly appropriate -when the local host is to be configured -as a broadcast/multicast client or manycast client, -with all peers being determined -by listening to broadcasts at run time. +configuration file at startup time in order to determine the +synchronization sources and operating modes. +It is also possible to +specify a working, although limited, configuration entirely on the +command line, obviating the need for a configuration file. +This may +be particularly useful when the local host is to be configured as a +broadcast/multicast client, with all peers being determined by +listening to broadcasts at run time. .Pp If NetInfo support is built into .Nm , then .Nm -will attempt to read its configuration from the NetInfo -if the default configuration file cannot be read -and no file is specified by the +will attempt to read its configuration from the +NetInfo if the default +.Xr ntp.conf 5 +file cannot be read and no file is +specified by the .Fl c option. .Pp -Various -internal +Various internal .Nm -variables can be displayed and configuration options altered -while the daemon is running -through use of the +variables can be displayed and +configuration options altered while the +.Nm +is running +using the .Xr ntpq 8 and .Xr ntpdc 8 -programs. +utility programs. .Pp When .Nm starts it looks at the value of -.Xr umask 2 -and if it is zero, +.Xr umask 2 , +and if zero .Nm -will set it to 022. +will set the +.Xr umask 2 +to 022. .Pp -The following command line options are available: +The following options are available: .Bl -tag -width indent .It Fl a Enable authentication mode (default). @@ -106,6 +100,8 @@ Disable authentication mode. Synchronize using NTP broadcast messages. .It Fl c Ar conffile Specify the name and path of the configuration file. +(Disable +netinfo?) .It Fl d Specify debugging mode. This flag may occur multiple times, @@ -115,33 +111,69 @@ Specify debugging level directly. .It Fl f Ar driftfile Specify the name and path of the drift file. .It Fl g -Normally, the daemon exits -if the offset exceeds a 1000 s sanity limit. -This option overrides this limit -and allows the time to be set to any value without restriction; -however, this can happen only once. +Normally, +.Nm +exits if the offset exceeds the sanity +limit, which is 1000 s by default. +If the sanity limit is set to +zero, no sanity checking is performed and any offset is acceptable. +This option overrides the limit and allows the time to be set to +any value without restriction; however, this can happen only once. After that, -the daemon will exit if the limit is exceeded. +.Nm +will exit if the limit is exceeded. +This +option can be used with the +.Fl q +option. .It Fl k Ar keyfile -Specify the name and path of the file -containing the NTP authentication keys. +Specify the name and path of the file containing the NTP +authentication keys. .It Fl l Ar logfile Specify the name and path of the log file. -The default is the system log facility. +The default is the +system log facility. +.It Fl L +Listen to virtual IPs. .It Fl m -Synchronize using NTP multicast messages -on the IP multicast group address 224.0.1.1 -(requires multicast kernel). +Synchronize using NTP multicast messages on the IP multicast +group address 224.0.1.1 (requires multicast kernel). +.It Fl n +Don't fork. +.It Fl N Ar priority +To the extent permitted by the operating system, run the +.Nm +at a high priority. .It Fl p Ar pidfile -Specify the name and path to record the daemon's process ID. +Specify the name and path to record the +.Nm Ns 's +process +ID. .It Fl P Override the priority limit set by the operating system. -Not recommended for sissies. +Not +recommended for sissies. +.It Fl q +Exit the +.Nm +just after the first time the clock is +set. +This behavior mimics that of the +.Xr ntpdate 8 +program, +which is to be retired. +The +.Fl g +and +.Fl x +options can +be used with this option. .It Fl r Ar broadcastdelay -Specify the default propagation delay -between the broadcast/multicast server and this computer. +Specify the default propagation delay from the +broadcast/multicast server and this computer. This is necessary -only if the delay cannot be computed automatically by the protocol. +only if the delay cannot be computed automatically by the +protocol. .It Fl s Ar statsdir Specify the directory path for files created by the statistics facility. @@ -151,53 +183,360 @@ Add a key number to the trusted key list. .It Fl V Ar variable Add a system variable listed by default. .It Fl x -Ordinarily, if the time is to be adjusted more than 128 ms, -it is stepped, not gradually slewed. -This option forces the time to be slewed in all cases. -Note: since the slew rate is limited to 0.5 ms/s, -each second of adjustment requires an amortization interval of 2000 s. -Thus, an adjustment of many seconds can take hours or days to amortize. -.El -.Ss Variables -Most variables used by the NTP protocol -can be examined with -.Xr ntpdc 8 -(mode 7 messages) and -.Xr ntpq 8 -(mode 6 messages). -Currently, very few variables can be modified via mode 6 messages. -These variables are either created with the -.Ic setvar -directive -(described in the -.Qq Miscellaneous Options -section of the -.Xr ntp.conf 5 -page) -or the leap warning bits. -The leap warning bits can be set in the -.Va leapwarning -variable up to one month ahead. -Both the -.Va leapwarning -and -.Va leapindication -variables have a slightly different encoding -than the usual leap bits interpretation: -.Pp -.Bl -tag -width indent -compact -.It 00 -The daemon passes the leap bits of its synchronization source -(usual mode of operation). -.It 01 -.It 10 -A leap second is added/deleted (operator forced leap second). -.It 11 -Leap information from the synchronizations source is ignored -(thus -.Dv LEAP_NOWARNING -is passed on). +Normally, the time is slewed if the offset is less than the +step threshold, which is 128 ms by default, and stepped if above +the threshold. +This option forces the time to be slewed in all +cases. +If the step threshold is set to zero, all offsets are +stepped, regardless of value and regardless of the +.Fl x +option. +In general, this is not a good idea, as it bypasses the +clock state machine which is designed to cope with large time and +frequency errors Note: Since the slew rate is limited to 0.5 ms/s, +each second of adjustment requires an amortization interval of 2000 +s. +Thus, an adjustment of many seconds can take hours or days to +amortize. +This option can be used with the +.Fl q +option. .El +.Ss "How NTP Operates" +The +.Nm +program operates by exchanging messages with +one or more configured servers at designated poll intervals. +When +started, whether for the first or subsequent times, the program +requires several exahanges from the majority of these servers so +the signal processing and mitigation algorithms can accumulate and +groom the data and set the clock. +In order to protect the network +from bursts, the initial poll interval for each server is delayed +an interval randomized over 0-16s. +At the default initial poll +interval of 64s, several minutes can elapse before the clock is +set. +The initial delay to set the clock can be reduced using the +.Cm iburst +keyword with the +.Ic server +configuration +command, as described in +.Xr ntp.conf 5 . +.Pp +Most operating systems and hardware of today incorporate a +time-of-year (TOY) chip to maintain the time during periods when +the power is off. +When the machine is booted, the chip is used to +initialize the operating system time. +After the machine has +synchronized to a NTP server, the operating system corrects the +chip from time to time. +In case there is no TOY chip or for some +reason its time is more than 1000s from the server time, +.Nm +assumes something must be terribly wrong and the only +reliable action is for the operator to intervene and set the clock +by hand. +This causes +.Nm +to exit with a panic message to +the system log. +The +.Fl g +option overrides this check and the +clock will be set to the server time regardless of the chip time. +However, and to protect against broken hardware, such as when the +CMOS battery fails or the clock counter becomes defective, once the +clock has been set, an error greater than 1000s will cause +.Nm +to exit anyway. +.Pp +Under ordinariy conditions, +.Nm +adjusts the clock in +small steps so that the timescale is effectively continuous and +without discontinuities. +Under conditions of extreme network +congestion, the roundtrip delay jitter can exceed three seconds and +the synchronization distance, which is equal to one-half the +roundtrip delay plus error budget terms, can become very large. +The +.Nm +algorithms discard sample offsets exceeding 128 ms, +unless the interval during which no sample offset is less than 128 +ms exceeds 900s. +The first sample after that, no matter what the +offset, steps the clock to the indicated time. +In practice this +reduces the false alarm rate where the clock is stepped in error to +a vanishingly low incidence. +.Pp +As the result of this behavior, once the clock has been set, it +very rarely strays more than 128 ms, even under extreme cases of +network path congestion and jitter. +Sometimes, in particular when +.Nm +is first started, the error might exceed 128 ms. +This +may on occasion cause the clock to be set backwards if the local +clock time is more than 128 s in the future relative to the server. +In some applications, this behavior may be unacceptable. +If the +.Fl x +option is included on the command line, the clock will +never be stepped and only slew corrections will be used. +.Pp +The issues should be carefully explored before deciding to use +the +.Fl x +option. +The maximum slew rate possible is limited +to 500 parts-per-million (PPM) as a consequence of the correctness +principles on which the NTP protocol and algorithm design are +based. +As a result, the local clock can take a long time to +converge to an acceptable offset, about 2,000 s for each second the +clock is outside the acceptable range. +During this interval the +local clock will not be consistent with any other network clock and +the system cannot be used for distributed applications that require +correctly synchronized network time. +.Pp +In spite of the above precautions, sometimes when large +frequency errors are present the resulting time offsets stray +outside the 128-ms range and an eventual step or slew time +correction is required. +If following such a correction the +frequency error is so large that the first sample is outside the +acceptable range, +.Nm +enters the same state as when the +.Pa ntp.drift +file is not present. +The intent of this behavior +is to quickly correct the frequency and restore operation to the +normal tracking mode. +In the most extreme cases +(time.ien.it comes to mind), there may be occasional +step/slew corrections and subsequent frequency corrections. +It +helps in these cases to use the +.Cm burst +keyword when +configuring the server. +.Ss "Frequency Discipline" +The +.Nm +behavior at startup depends on whether the +frequency file, usually +.Pa ntp.drift , +exists. +This file +contains the latest estimate of clock frequency error. +When the +.Nm +is started and the file does not exist, the +.Nm +enters a special mode designed to quickly adapt to +the particular system clock oscillator time and frequency error. +This takes approximately 15 minutes, after which the time and +frequency are set to nominal values and the +.Nm +enters +normal mode, where the time and frequency are continuously tracked +relative to the server. +After one hour the frequency file is +created and the current frequency offset written to it. +When the +.Nm +is started and the file does exist, the +.Nm +frequency is initialized from the file and enters normal mode +immediately. +After that the current frequency offset is written to +the file at hourly intervals. +.Ss "Operating Modes" +.Nm +can operate in any of several modes, including +symmetric active/passive, client/server broadcast/multicast and +manycast, as described in the +.Qq Association Management +page +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) . +It normally operates continuously while +monitoring for small changes in frequency and trimming the clock +for the ultimate precision. +However, it can operate in a one-time +mode where the time is set from an external server and frequency is +set from a previously recorded frequency file. +A +broadcast/multicast or manycast client can discover remote servers, +compute server-client propagation delay correction factors and +configure itself automatically. +This makes it possible to deploy a +fleet of workstations without specifying configuration details +specific to the local environment. +.Pp +By default, +.Nm +runs in continuous mode where each of +possibly several external servers is polled at intervals determined +by an intricate state machine. +The state machine measures the +incidental roundtrip delay jitter and oscillator frequency wander +and determines the best poll interval using a heuristic algorithm. +Ordinarily, and in most operating environments, the state machine +will start with 64s intervals and eventually increase in steps to +1024s. +A small amount of random variation is introduced in order to +avoid bunching at the servers. +In addition, should a server become +unreachable for some time, the poll interval is increased in steps +to 1024s in order to reduce network overhead. +.Pp +In some cases it may not be practical for +.Nm +to run +continuously. +A common workaround has been to run the +.Xr ntpdate 8 +program from a +.Xr cron 8 +job at designated +times. +However, this program does not have the crafted signal +processing, error checking and mitigation algorithms of +.Nm . +The +.Fl q +option is intended for this purpose. +Setting this option will cause +.Nm +to exit just after +setting the clock for the first time. +The procedure for initially +setting the clock is the same as in continuous mode; most +applications will probably want to specify the +.Cm iburst +keyword with the +.Ic server +configuration command. +With this +keyword a volley of messages are exchanged to groom the data and +the clock is set in about a minute. +If nothing is heard after a +couple of minutes, the daemon times out and exits. +After a suitable +period of mourning, the +.Xr ntpdate 8 +program may be +retired. +.Pp +When kernel support is available to discipline the clock +frequency, which is the case for stock Solaris, Tru64, Linux and +.Fx , +a useful feature is available to discipline the clock +frequency. +First, +.Nm +is run in continuous mode with +selected servers in order to measure and record the intrinsic clock +frequency offset in the frequency file. +It may take some hours for +the frequency and offset to settle down. +Then the +.Nm +is +stopped and run in one-time mode as required. +At each startup, the +frequency is read from the file and initializes the kernel +frequency. +.Ss "Poll Interval Control" +This version of NTP includes an intricate state machine to +reduce the network load while maintaining a quality of +synchronization consistent with the observed jitter and wander. +There are a number of ways to tailor the operation in order enhance +accuracy by reducing the interval or to reduce network overhead by +increasing it. +However, the user is advised to carefully consider +the consequenses of changing the poll adjustment range from the +default minimum of 64 s to the default maximum of 1,024 s. +The +default minimum can be changed with the +.Ic tinker +.Cm minpoll +command to a value not less than 16 s. +This value is used for all +configured associations, unless overriden by the +.Cm minpoll +option on the configuration command. +Note that most device drivers +will not operate properly if the poll interval is less than 64 s +and that the broadcast server and manycast client associations will +also use the default, unless overriden. +.Pp +In some cases involving dial up or toll services, it may be +useful to increase the minimum interval to a few tens of minutes +and maximum interval to a day or so. +Under normal operation +conditions, once the clock discipline loop has stabilized the +interval will be increased in steps from the minumum to the +maximum. +However, this assumes the intrinsic clock frequency error +is small enough for the discipline loop correct it. +The capture +range of the loop is 500 PPM at an interval of 64s decreasing by a +factor of two for each doubling of interval. +At a minimum of 1,024 +s, for example, the capture range is only 31 PPM. +If the intrinsic +error is greater than this, the drift file +.Pa ntp.drift +will +have to be specially tailored to reduce the residual error below +this limit. +Once this is done, the drift file is automatically +updated once per hour and is available to initialize the frequency +on subsequent daemon restarts. +.Ss "The huff-n'-puff filter" +In scenarios where a considerable amount of data are to be +downloaded or uploaded over telephone modems, timekeeping quality +can be seriously degraded. +This occurs because the differential +delays on the two directions of transmission can be quite large. +In +many cases the apparent time errors are so large as to exceed the +step threshold and a step correction can occur during and after the +data transfer is in progress. +.Pp +The huff-n'-puff filter is designed to correct the apparent time +offset in these cases. +It depends on knowledge of the propagation +delay when no other traffic is present. +In common scenarios this +occurs during other than work hours. +The filter maintains a shift +register that remembers the minimum delay over the most recent +interval measured usually in hours. +Under conditions of severe +delay, the filter corrects the apparent offset using the sign of +the offset and the difference between the apparent delay and +minimum delay. +The name of the filter reflects the negative (huff) +and positive (puff) correction, which depends on the sign of the +offset. +.Pp +The filter is activated by the +.Ic tinker command and +.Cm huffpuff +keyword, as described in +.Xr ntp.conf 5 . .Sh FILES .Bl -tag -width /etc/ntp.drift -compact .It Pa /etc/ntp.conf @@ -234,18 +573,13 @@ A snapshot of this documentation is available in HTML format in .%T Network Time Protocol (Version 3) .%O RFC1305 .Re -.Sh HISTORY -Written by -.An Dennis Ferguson -at the University of Toronto. -Text amended by -.An David Mills -at the University of Delaware. .Sh BUGS .Nm has gotten rather fat. -While not huge, it has gotten larger than might -be desireable for an elevated-priority daemon running on a workstation, -particularly since many of the fancy features which consume the space -were designed more with a busy primary server, rather than a high -stratum workstation, in mind. +While not huge, it has gotten +larger than might be desirable for an elevated-priority +.Nm +running on a workstation, particularly since many of +the fancy features which consume the space were designed more with +a busy primary server, rather than a high stratum workstation in +mind. |
