diff options
Diffstat (limited to 'contrib/ntp/ntpd/ntpd-opts.def')
| -rw-r--r-- | contrib/ntp/ntpd/ntpd-opts.def | 611 |
1 files changed, 611 insertions, 0 deletions
diff --git a/contrib/ntp/ntpd/ntpd-opts.def b/contrib/ntp/ntpd/ntpd-opts.def new file mode 100644 index 0000000..dee484d --- /dev/null +++ b/contrib/ntp/ntpd/ntpd-opts.def @@ -0,0 +1,611 @@ +/* -*- Mode: Text -*- */ + +autogen definitions options; + +#include copyright.def + +prog-name = "ntpd"; +prog-title = "NTP daemon program"; +argument = "[ <server1> ... <serverN> ]"; + +#include ntpdbase-opts.def + +/* explain: Additional information whenever the usage routine is invoked */ +explain = <<- _END_EXPLAIN + _END_EXPLAIN; + +doc-section = { + ds-type = 'DESCRIPTION'; + ds-format = 'mdoc'; + ds-text = <<- _END_PROG_MDOC_DESCRIP +The +.Nm +utility 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, as defined by RFC-5905, +but also retains compatibility with +version 3, as defined by RFC-1305, and versions 1 +and 2, as defined by RFC-1059 and RFC-1119, respectively. +.Pp +The +.Nm +utility 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 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 +.Xr ntp.conf 5 +file cannot be read and no file is +specified by the +.Fl c +option. +.Pp +Various internal +.Nm +variables can be displayed and +configuration options altered while the +.Nm +is running +using the +.Xr ntpq 1ntpqmdoc +and +.Xr ntpdc 1ntpdcmdoc +utility programs. +.Pp +When +.Nm +starts it looks at the value of +.Xr umask 2 , +and if zero +.Nm +will set the +.Xr umask 2 +to 022. + _END_PROG_MDOC_DESCRIP; +}; + +doc-section = { + ds-type = 'USAGE'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_USAGE +.Ss "How NTP Operates" +The +.Nm +utility operates by exchanging messages with +one or more configured servers over a range of designated poll intervals. +When +started, whether for the first or subsequent times, the program +requires several exchanges 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 a few seconds. +At the default initial poll +interval of 64s, several minutes can elapse before the clock is +set. +This initial delay to set the clock +can be safely and dramatically 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 the default case, if +.Nm +detects that the time on the host +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. +(Reasons for this include there is no TOY chip, +or its battery is dead, or that the TOY chip is just of poor quality.) +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 +(up to 68 years in the past or future \(em +this is a limitation of the NTPv4 protocol). +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 ordinary 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 without a valid drift file +on a system with a large intrinsic drift +the error might grow to exceed 128 ms, +which would 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. +There are several solutions, however. +If the +.Fl x +option is included on the command line, the clock will +never be stepped and only slew corrections will be used. +But this choice comes with a cost that +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 +(the host +.Cm 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, but +ONLY +when you have permission to do so from the owner of the target host. +.Pp +Finally, +in the past many startup scripts would run +.Xr ntpdate 1ntpdatemdoc +to get the system clock close to correct before starting +.Xr ntpd 1ntpdmdoc , +but this was never more than a mediocre hack and is no longer needed. +If you are following the instructions in +.Sx "Starting NTP (Best Current Practice)" +and you still need to set the system time before starting +.Nm , +please open a bug report and document what is going on, +and then look at using +.Xr sntp 1sntpmdoc . +.Pp +There is a way to start +.Xr ntpd 1ntpdmdoc +that often addresses all of the problems mentioned above. +.Ss "Starting NTP (Best Current Practice)" +First, use the +.Cm iburst +option on your +.Cm server +entries. +.Pp +If you can also keep a good +.Pa ntp.drift +file then +.Xr ntpd 1ntpdmdoc +will effectively "warm-start" and your system's clock will +be stable in under 11 seconds' time. +.Pp +As soon as possible in the startup sequence, start +.Xr ntpd 1ntpdmdoc +with at least the +.Fl g +and perhaps the +.Fl N +options. +Then, +start the rest of your "normal" processes. +This will give +.Xr ntpd 1ntpdmdoc +as much time as possible to get the system's clock synchronized and stable. +.Pp +Finally, +if you have processes like +.Cm dovecot +or database servers +that require +monotonically-increasing time, +run +.Xr ntp-wait 1ntp-waitmdoc +as late as possible in the boot sequence +(perhaps with the +.Fl v +flag) +and after +.Xr ntp-wait 1ntp-waitmdoc +exits successfully +it is as safe as it will ever be to start any process that require +stable time. +.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" +The +.Nm +utility 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 1ntpdatemdoc +or +.Xr sntp 1sntpmdoc +programs from a +.Xr cron 8 +job at designated +times. +However, these programs do not have the crafted signal +processing, error checking or 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 10 s. +If nothing is heard after a +couple of minutes, the daemon times out and exits. +After a suitable +period of mourning, the +.Xr ntpdate 1ntpdatemdoc +program will 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 consequences 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 overridden 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 overridden. +.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 minimum 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 . + _END_MDOC_USAGE; +}; + +doc-section = { + ds-type = 'FILES'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_FILES +.Bl -tag -width /etc/ntp.drift -compact +.It Pa /etc/ntp.conf +the default name of the configuration file +.It Pa /etc/ntp.drift +the default name of the drift file +.It Pa /etc/ntp.keys +the default name of the key file +.El + _END_MDOC_FILES; +}; + +doc-section = { + ds-type = 'SEE ALSO'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_SEE_ALSO +.Xr ntp.conf 5 , +.Xr ntpdate 1ntpdatemdoc , +.Xr ntpdc 1ntpdcmdoc , +.Xr ntpq 1ntpqmdoc , +.Xr sntp 1sntpmdoc +.Pp +In addition to the manual pages provided, +comprehensive documentation is available on the world wide web +at +.Li http://www.ntp.org/ . +A snapshot of this documentation is available in HTML format in +.Pa /usr/share/doc/ntp . +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 1) +.%O RFC1059 +.Re +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 2) +.%O RFC1119 +.Re +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Rs +.%A David L. Mills +.%A J. Martin, Ed. +.%A J. Burbank +.%A W. Kasch +.%T Network Time Protocol Version 4: Protocol and Algorithms Specification +.%O RFC5905 +.Re +.Rs +.%A David L. Mills +.%A B. Haberman, Ed. +.%T Network Time Protocol Version 4: Autokey Specification +.%O RFC5906 +.Re +.Rs +.%A H. Gerstung +.%A C. Elliott +.%A B. Haberman, Ed. +.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) +.%O RFC5907 +.Re +.Rs +.%A R. Gayraud +.%A B. Lourdelet +.%T Network Time Protocol (NTP) Server Option for DHCPv6 +.%O RFC5908 +.Re + _END_MDOC_SEE_ALSO; +}; + +doc-section = { + ds-type = 'BUGS'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_BUGS +The +.Nm +utility has gotten rather fat. +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. + _END_MDOC_BUGS; +}; + +doc-section = { + ds-type = 'NOTES'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_NOTES +Portions of this document came from FreeBSD. + _END_MDOC_NOTES; +}; |
