From: Harlan Stenn Date: Thu, 23 Jun 2011 03:14:06 +0000 (-0400) Subject: generated man page updates X-Git-Tag: NTP_4_2_7P186~4^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4d15d252a390d2f3187b0d6f2ff6edcf603b9b05;p=thirdparty%2Fntp.git generated man page updates bk: 4e02af7e9Czk8qOisjQMyRiJIxM4yg --- diff --git a/bootstrap b/bootstrap index aec07cd19..c65ffa106 100755 --- a/bootstrap +++ b/bootstrap @@ -90,7 +90,7 @@ do for i in `ls -1 $f*` do case "$i" in - *.c|*.h|*.1|*.texi|*.menu) + *.c|*.h|*.1*man|*.1*mdoc|*.man.in|*.mdoc.in|*.texi|*.menu) l="$l $i" ;; *.html) diff --git a/ntpd/ntpd.1ntpdman b/ntpd/ntpd.1ntpdman new file mode 100644 index 000000000..b0c531a93 --- /dev/null +++ b/ntpd/ntpd.1ntpdman @@ -0,0 +1,909 @@ +.TH ntpd 1ntpdman "22 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:43:11 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpd-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntpd \- NTP daemon program +.SH SYNOPSIS +.B ntpd +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ ... ] +.PP +.SH DESCRIPTION +The +.B +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 +.B +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, +.B +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 +.B , +then +.B +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 +c +option. +.PP +Various internal +.B +variables can be displayed and +configuration options altered while the +.B +is running +using the +.Xr ntpq 8 +and +.Xr ntpdc 8 +utility programs. +.PP +When +.B +starts it looks at the value of +.Xr umask 2 , +and if zero +.B +will set the +.Xr umask 2 +to 022. +.SH "OPTIONS" +.TP +.BR \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.TP +.BR \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.TP +.BR \-a ", " -\-authreq +Require crypto authentication. +This option must not appear in combination with any of the following options: +authnoreq. +.sp +Require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is the default. +.TP +.BR \-A ", " -\-authnoreq +Do not require crypto authentication. +This option must not appear in combination with any of the following options: +authreq. +.sp +Do not require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is almost never a good idea. +.TP +.BR \-b ", " -\-bcastsync +Allow us to sync to broadcast servers. +.sp +.TP +.BR \-c " \fIstring\fP, " \-\-configfile "=" \fIstring\fP +configuration file name. +.sp +The name and path of the configuration file, +/etc/ntp.conf +by default. +.TP +.BR \-d ", " -\-debug\-level +Increase output debug message level. +This option may appear an unlimited number of times. +.sp +Increase the debugging message output level. +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the output debug message level. +This option may appear an unlimited number of times. +.sp +Set the output debugging level. Can be supplied multiple times, +but each overrides the previous value(s). +.TP +.BR \-f " \fIstring\fP, " \-\-driftfile "=" \fIstring\fP +frequency drift file name. +.sp +The name and path of the frequency file, +/etc/ntp.drift +by default. +This is the same operation as the +driftfile driftfile +configuration specification in the +/etc/ntp.conf +file. +.TP +.BR \-g ", " -\-panicgate +Allow the first adjustment to be Big. +This option may appear an unlimited number of times. +.sp +Normally, +ntpd +exits 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, +ntpd +will exit with a message to the system log. This option can be used with the +-q +and +-x +options. +See the +tinker +configuration file directive for other options. +.TP +.BR \-i " \fIstring\fP, " \-\-jaildir "=" \fIstring\fP +Jail directory. +.sp +Chroot the server to the directory +jaildir +. +This option also implies that the server attempts to drop root privileges at startup. +You may need to also specify a +-u +option. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +--enable-clockctl +) and Linux (configure with +--enable-linuxcaps +). +.TP +.BR \-I " \fIiface\fP, " \-\-interface "=" \fIiface\fP +Listen on an interface name or address. +This option may appear an unlimited number of times. +.sp +Open the network address given, or all the addresses associated with the +given interface name. This option may appear multiple times. This option +also implies not opening other addresses, except wildcard and localhost. +This option is deprecated. Please consider using the configuration file +interface command, which is more versatile. +.TP +.BR \-k " \fIstring\fP, " \-\-keyfile "=" \fIstring\fP +path to symmetric keys. +.sp +Specify the name and path of the symmetric key file. +/etc/ntp.keys +is the default. +This is the same operation as the +keys keyfile +configuration file directive. +.TP +.BR \-l " \fIstring\fP, " \-\-logfile "=" \fIstring\fP +path to the log file. +.sp +Specify the name and path of the log file. +The default is the system log file. +This is the same operation as the +logfile logfile +configuration file directive. +.TP +.BR \-L ", " -\-novirtualips +Do not listen to virtual interfaces. +.sp +Do not listen to virtual interfaces, defined as those with +names containing a colon. This option is deprecated. Please +consider using the configuration file interface command, which +is more versatile. +.TP +.BR \-M ", " -\-modifymmtimer +Modify Multimedia Timer (Windows only). +.sp +Set the Windows Multimedia Timer to highest resolution. This +ensures the resolution does not change while ntpd is running, +avoiding timekeeping glitches associated with changes. +.TP +.BR \-n ", " -\-nofork +Do not fork. +This option must not appear in combination with any of the following options: +wait-sync. +.sp +.TP +.BR \-N ", " -\-nice +Run at high priority. +.sp +To the extent permitted by the operating system, run +ntpd +at the highest priority. +.TP +.BR \-p " \fIstring\fP, " \-\-pidfile "=" \fIstring\fP +path to the PID file. +.sp +Specify the name and path of the file used to record +ntpd's +process ID. +This is the same operation as the +pidfile pidfile +configuration file directive. +.TP +.BR \-P " \fInumber\fP, " \-\-priority "=" \fInumber\fP +Process priority. +This option takes an integer number as its argument. +.sp +To the extent permitted by the operating system, run +ntpd +at the specified +sched_setscheduler(SCHED_FIFO) +priority. +.TP +.BR \-q ", " -\-quit +Set the time and quit. +This option must not appear in combination with any of the following options: +saveconfigquit, wait-sync. +.sp +ntpd +will not daemonize and will exit after the clock is first +synchronized. This behavior mimics that of the +ntpdate +program, which will soon be replaced with a shell script. +The +-g +and +-x +options can be used with this option. +Note: The kernel time discipline is disabled with this option. +.TP +.BR \-r " \fIstring\fP, " \-\-propagationdelay "=" \fIstring\fP +Broadcast/propagation delay. +.sp +Specify 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. +.TP +.BR \-\-saveconfigquit "=\fIstring\fP" +Save parsed configuration and quit. +This option must not appear in combination with any of the following options: +quit, wait-sync. +.sp +Cause ntpd to parse its startup configuration file and save an +equivalent to the given filename and exit. This option was +designed for automated testing. +.TP +.BR \-s " \fIstring\fP, " \-\-statsdir "=" \fIstring\fP +Statistics file location. +.sp +Specify the directory path for files created by the statistics facility. +This is the same operation as the +statsdir statsdir +configuration file directive. +.TP +.BR \-t " \fItkey\fP, " \-\-trustedkey "=" \fItkey\fP +Trusted key number. +This option may appear an unlimited number of times. +.sp +Add a key number to the trusted key list. +.TP +.BR \-u " \fIstring\fP, " \-\-user "=" \fIstring\fP +Run as userid (or userid:groupid). +.sp +Specify a user, and optionally a group, to switch to. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +--enable-clockctl +) and Linux (configure with +--enable-linuxcaps +). +.TP +.BR \-U " \fInumber\fP, " \-\-updateinterval "=" \fInumber\fP +interval in seconds between scans for new or dropped interfaces. +This option takes an integer number as its argument. +.sp +Give the time in seconds between two scans for new or dropped interfaces. +For systems with routing socket support the scans will be performed shortly after the interface change +has been detected by the system. +Use 0 to disable scanning. 60 seconds is the minimum time between scans. +.TP +.BR \-\-var "=\fInvar\fP" +make ARG an ntp variable (RW). +This option may appear an unlimited number of times. +.sp +.TP +.BR \-\-dvar "=\fIndvar\fP" +make ARG an ntp variable (RW|DEF). +This option may appear an unlimited number of times. +.sp +.TP +.BR \-w " \fInumber\fP, " \-\-wait\-sync "=" \fInumber\fP +Seconds to wait for first clock sync. +This option must not appear in combination with any of the following options: +nofork, quit, saveconfigquit. +This option takes an integer number as its argument. +.sp +If greater than zero, alters ntpd behavior when forking to +daemonize. Instead of exiting with status 0 immediately after +the fork, the parent waits up to the specified number of +seconds for the child to first synchronize the clock. The exit +status is zero (success) if the clock was synchronized, +otherwise it is ETIMEDOUT. +This provides the option for a script starting ntpd to easily +wait for the first set of the clock before proceeding. +.TP +.BR \-x ", " -\-slew +Slew up to 600 seconds. +.sp +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 sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. +Note: 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. +Thus, an adjustment as much as 600 s will take almost 14 days to complete. +This option can be used with the +-g +and +-q +options. +See the +tinker +configuration file directive for other options. +Note: The kernel time discipline is disabled with this option. +.TP +.BR \-\-usepcc +Use CPU cycle counter (Windows only). +.sp +Attempt to substitute the CPU counter for QueryPerformanceCounter. +The CPU counter and QueryPerformanceCounter are compared, and if +they have the same frequency, the CPU counter (RDTSC on x86) is +used directly, saving the overhead of a system call. +.TP +.BR \-\-pccfreq "=\fIstring\fP" +Force CPU cycle counter use (Windows only). +.sp +Force substitution the CPU counter for QueryPerformanceCounter. +The CPU counter (RDTSC on x86) is used unconditionally with the +given frequency (in Hz). +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTPD_\fP or \fBNTPD\fP +.fi +.ad +.SH USAGE +.Ss "How NTP Operates" +The +.B +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 +.B +detects that the time on the host +is more than 1000s from the server time, +.B +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 +.B +to exit with a panic message to +the system log. +The +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 +.B +to exit anyway. +.PP +Under ordinary conditions, +.B +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 +.B +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 +.B +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 +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 +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, +.B +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 8 +to get the system clock close to correct before starting +.Xr ntpd 8 , +but this was never more than a mediocre hack and is no longer needed. +.PP +There is a way to start +.Xr ntpd 8 +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 8 +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 8 +with at least the +g +and perhaps the +N +options. +Then, +start the rest of your "normal" processes. +This will give +.Xr ntpd 8 +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 8 +as late as possible in the boot sequence +(perhaps with the +v +flag) +and after +.Xr ntp-wait 8 +exits successfully +it is as safe as it will ever be to start any process that require +stable time. +.Ss "Frequency Discipline" +The +.B +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 +.B +is started and the file does not exist, the +.B +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 +.B +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 +.B +is started and the file does exist, the +.B +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 +.B +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, +.B +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 +.B +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 +.B . +The +q +option is intended for this purpose. +Setting this option will cause +.B +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 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, +.B +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 +.B +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 . +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH FILES +.TP +.BR Pa /etc/ntp.conf +the default name of the configuration file +.TP +.BR Pa /etc/ntp.drift +the default name of the drift file +.TP +.BR Pa /etc/ntp.keys +the default name of the key file +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH "SEE ALSO" +.Xr ntp.conf 5 , +.Xr ntpdate 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.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 +.SH "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH BUGS +The +.B +utility has gotten rather fat. +While not huge, it has gotten +larger than might be desirable for an elevated-priority +.B +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. +.SH NOTES +Portions of this document came from FreeBSD. +.PP +This manual page was \fIAutoGen\fP-erated from the \fBntpd\fP +option definitions. diff --git a/ntpd/ntpd.1ntpdmdoc b/ntpd/ntpd.1ntpdmdoc new file mode 100644 index 000000000..2ff9a4ea5 --- /dev/null +++ b/ntpd/ntpd.1ntpdmdoc @@ -0,0 +1,878 @@ +.Dd June 22 2011 +.Dt NTPD 1ntpdmdoc User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:57:43 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpd-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpd +.Nd NTP daemon program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +[ ... ] +.Pp +.Sh DESCRIPTION +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 8 +and +.Xr ntpdc 8 +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. +.Sh "OPTIONS" +.Bl -tag +.It \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.It \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.It \-a ", " -\-authreq +Require crypto authentication. +This option must not appear in combination with any of the following options: +authnoreq. +.sp +Require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is the default. +.It \-A ", " -\-authnoreq +Do not require crypto authentication. +This option must not appear in combination with any of the following options: +authreq. +.sp +Do not require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is almost never a good idea. +.It \-b ", " -\-bcastsync +Allow us to sync to broadcast servers. +.sp +.It \-c " \fIstring\fP, " \-\-configfile "=" \fIstring\fP +configuration file name. +.sp +The name and path of the configuration file, +/etc/ntp.conf +by default. +.It \-d ", " -\-debug\-level +Increase output debug message level. +This option may appear an unlimited number of times. +.sp +Increase the debugging message output level. +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the output debug message level. +This option may appear an unlimited number of times. +.sp +Set the output debugging level. Can be supplied multiple times, +but each overrides the previous value(s). +.It \-f " \fIstring\fP, " \-\-driftfile "=" \fIstring\fP +frequency drift file name. +.sp +The name and path of the frequency file, +/etc/ntp.drift +by default. +This is the same operation as the +driftfile driftfile +configuration specification in the +/etc/ntp.conf +file. +.It \-g ", " -\-panicgate +Allow the first adjustment to be Big. +This option may appear an unlimited number of times. +.sp +Normally, +ntpd +exits 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, +ntpd +will exit with a message to the system log. This option can be used with the +-q +and +-x +options. +See the +tinker +configuration file directive for other options. +.It \-i " \fIstring\fP, " \-\-jaildir "=" \fIstring\fP +Jail directory. +.sp +Chroot the server to the directory +jaildir +. +This option also implies that the server attempts to drop root privileges at startup. +You may need to also specify a +-u +option. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +--enable-clockctl +) and Linux (configure with +--enable-linuxcaps +). +.It \-I " \fIiface\fP, " \-\-interface "=" \fIiface\fP +Listen on an interface name or address. +This option may appear an unlimited number of times. +.sp +Open the network address given, or all the addresses associated with the +given interface name. This option may appear multiple times. This option +also implies not opening other addresses, except wildcard and localhost. +This option is deprecated. Please consider using the configuration file +interface command, which is more versatile. +.It \-k " \fIstring\fP, " \-\-keyfile "=" \fIstring\fP +path to symmetric keys. +.sp +Specify the name and path of the symmetric key file. +/etc/ntp.keys +is the default. +This is the same operation as the +keys keyfile +configuration file directive. +.It \-l " \fIstring\fP, " \-\-logfile "=" \fIstring\fP +path to the log file. +.sp +Specify the name and path of the log file. +The default is the system log file. +This is the same operation as the +logfile logfile +configuration file directive. +.It \-L ", " -\-novirtualips +Do not listen to virtual interfaces. +.sp +Do not listen to virtual interfaces, defined as those with +names containing a colon. This option is deprecated. Please +consider using the configuration file interface command, which +is more versatile. +.It \-M ", " -\-modifymmtimer +Modify Multimedia Timer (Windows only). +.sp +Set the Windows Multimedia Timer to highest resolution. This +ensures the resolution does not change while ntpd is running, +avoiding timekeeping glitches associated with changes. +.It \-n ", " -\-nofork +Do not fork. +This option must not appear in combination with any of the following options: +wait-sync. +.sp +.It \-N ", " -\-nice +Run at high priority. +.sp +To the extent permitted by the operating system, run +ntpd +at the highest priority. +.It \-p " \fIstring\fP, " \-\-pidfile "=" \fIstring\fP +path to the PID file. +.sp +Specify the name and path of the file used to record +ntpd's +process ID. +This is the same operation as the +pidfile pidfile +configuration file directive. +.It \-P " \fInumber\fP, " \-\-priority "=" \fInumber\fP +Process priority. +This option takes an integer number as its argument. +.sp +To the extent permitted by the operating system, run +ntpd +at the specified +sched_setscheduler(SCHED_FIFO) +priority. +.It \-q ", " -\-quit +Set the time and quit. +This option must not appear in combination with any of the following options: +saveconfigquit, wait-sync. +.sp +ntpd +will not daemonize and will exit after the clock is first +synchronized. This behavior mimics that of the +ntpdate +program, which will soon be replaced with a shell script. +The +-g +and +-x +options can be used with this option. +Note: The kernel time discipline is disabled with this option. +.It \-r " \fIstring\fP, " \-\-propagationdelay "=" \fIstring\fP +Broadcast/propagation delay. +.sp +Specify 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. +.It \-\-saveconfigquit "=\fIstring\fP" +Save parsed configuration and quit. +This option must not appear in combination with any of the following options: +quit, wait-sync. +.sp +Cause ntpd to parse its startup configuration file and save an +equivalent to the given filename and exit. This option was +designed for automated testing. +.It \-s " \fIstring\fP, " \-\-statsdir "=" \fIstring\fP +Statistics file location. +.sp +Specify the directory path for files created by the statistics facility. +This is the same operation as the +statsdir statsdir +configuration file directive. +.It \-t " \fItkey\fP, " \-\-trustedkey "=" \fItkey\fP +Trusted key number. +This option may appear an unlimited number of times. +.sp +Add a key number to the trusted key list. +.It \-u " \fIstring\fP, " \-\-user "=" \fIstring\fP +Run as userid (or userid:groupid). +.sp +Specify a user, and optionally a group, to switch to. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +--enable-clockctl +) and Linux (configure with +--enable-linuxcaps +). +.It \-U " \fInumber\fP, " \-\-updateinterval "=" \fInumber\fP +interval in seconds between scans for new or dropped interfaces. +This option takes an integer number as its argument. +.sp +Give the time in seconds between two scans for new or dropped interfaces. +For systems with routing socket support the scans will be performed shortly after the interface change +has been detected by the system. +Use 0 to disable scanning. 60 seconds is the minimum time between scans. +.It \-\-var "=\fInvar\fP" +make ARG an ntp variable (RW). +This option may appear an unlimited number of times. +.sp +.It \-\-dvar "=\fIndvar\fP" +make ARG an ntp variable (RW|DEF). +This option may appear an unlimited number of times. +.sp +.It \-w " \fInumber\fP, " \-\-wait\-sync "=" \fInumber\fP +Seconds to wait for first clock sync. +This option must not appear in combination with any of the following options: +nofork, quit, saveconfigquit. +This option takes an integer number as its argument. +.sp +If greater than zero, alters ntpd behavior when forking to +daemonize. Instead of exiting with status 0 immediately after +the fork, the parent waits up to the specified number of +seconds for the child to first synchronize the clock. The exit +status is zero (success) if the clock was synchronized, +otherwise it is ETIMEDOUT. +This provides the option for a script starting ntpd to easily +wait for the first set of the clock before proceeding. +.It \-x ", " -\-slew +Slew up to 600 seconds. +.sp +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 sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. +Note: 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. +Thus, an adjustment as much as 600 s will take almost 14 days to complete. +This option can be used with the +-g +and +-q +options. +See the +tinker +configuration file directive for other options. +Note: The kernel time discipline is disabled with this option. +.It \-\-usepcc +Use CPU cycle counter (Windows only). +.sp +Attempt to substitute the CPU counter for QueryPerformanceCounter. +The CPU counter and QueryPerformanceCounter are compared, and if +they have the same frequency, the CPU counter (RDTSC on x86) is +used directly, saving the overhead of a system call. +.It \-\-pccfreq "=\fIstring\fP" +Force CPU cycle counter use (Windows only). +.sp +Force substitution the CPU counter for QueryPerformanceCounter. +The CPU counter (RDTSC on x86) is used unconditionally with the +given frequency (in Hz). +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTPD_\fP or \fBNTPD\fP +.fi +.ad +.Sh 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 8 +to get the system clock close to correct before starting +.Xr ntpd 8 , +but this was never more than a mediocre hack and is no longer needed. +.Pp +There is a way to start +.Xr ntpd 8 +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 8 +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 8 +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 8 +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 8 +as late as possible in the boot sequence +(perhaps with the +.Fl v +flag) +and after +.Xr ntp-wait 8 +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 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 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 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 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 . +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh 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 +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh "SEE ALSO" +.Xr ntp.conf 5 , +.Xr ntpdate 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.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 +.Sh "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh 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. +.Sh NOTES +Portions of this document came from FreeBSD. +.Pp +This manual page was \fIAutoGen\fP-erated from the \fBntpd\fP +option definitions. diff --git a/ntpd/ntpd.man.in b/ntpd/ntpd.man.in new file mode 100644 index 000000000..622b3bd45 --- /dev/null +++ b/ntpd/ntpd.man.in @@ -0,0 +1,909 @@ +.TH ntpd @NTPD_MS@ "22 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:43:11 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpd-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntpd \- NTP daemon program +.SH SYNOPSIS +.B ntpd +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ ... ] +.PP +.SH DESCRIPTION +The +.B +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 +.B +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, +.B +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 +.B , +then +.B +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 +c +option. +.PP +Various internal +.B +variables can be displayed and +configuration options altered while the +.B +is running +using the +.Xr ntpq 8 +and +.Xr ntpdc 8 +utility programs. +.PP +When +.B +starts it looks at the value of +.Xr umask 2 , +and if zero +.B +will set the +.Xr umask 2 +to 022. +.SH "OPTIONS" +.TP +.BR \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.TP +.BR \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.TP +.BR \-a ", " -\-authreq +Require crypto authentication. +This option must not appear in combination with any of the following options: +authnoreq. +.sp +Require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is the default. +.TP +.BR \-A ", " -\-authnoreq +Do not require crypto authentication. +This option must not appear in combination with any of the following options: +authreq. +.sp +Do not require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is almost never a good idea. +.TP +.BR \-b ", " -\-bcastsync +Allow us to sync to broadcast servers. +.sp +.TP +.BR \-c " \fIstring\fP, " \-\-configfile "=" \fIstring\fP +configuration file name. +.sp +The name and path of the configuration file, +/etc/ntp.conf +by default. +.TP +.BR \-d ", " -\-debug\-level +Increase output debug message level. +This option may appear an unlimited number of times. +.sp +Increase the debugging message output level. +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the output debug message level. +This option may appear an unlimited number of times. +.sp +Set the output debugging level. Can be supplied multiple times, +but each overrides the previous value(s). +.TP +.BR \-f " \fIstring\fP, " \-\-driftfile "=" \fIstring\fP +frequency drift file name. +.sp +The name and path of the frequency file, +/etc/ntp.drift +by default. +This is the same operation as the +driftfile driftfile +configuration specification in the +/etc/ntp.conf +file. +.TP +.BR \-g ", " -\-panicgate +Allow the first adjustment to be Big. +This option may appear an unlimited number of times. +.sp +Normally, +ntpd +exits 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, +ntpd +will exit with a message to the system log. This option can be used with the +-q +and +-x +options. +See the +tinker +configuration file directive for other options. +.TP +.BR \-i " \fIstring\fP, " \-\-jaildir "=" \fIstring\fP +Jail directory. +.sp +Chroot the server to the directory +jaildir +. +This option also implies that the server attempts to drop root privileges at startup. +You may need to also specify a +-u +option. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +--enable-clockctl +) and Linux (configure with +--enable-linuxcaps +). +.TP +.BR \-I " \fIiface\fP, " \-\-interface "=" \fIiface\fP +Listen on an interface name or address. +This option may appear an unlimited number of times. +.sp +Open the network address given, or all the addresses associated with the +given interface name. This option may appear multiple times. This option +also implies not opening other addresses, except wildcard and localhost. +This option is deprecated. Please consider using the configuration file +interface command, which is more versatile. +.TP +.BR \-k " \fIstring\fP, " \-\-keyfile "=" \fIstring\fP +path to symmetric keys. +.sp +Specify the name and path of the symmetric key file. +/etc/ntp.keys +is the default. +This is the same operation as the +keys keyfile +configuration file directive. +.TP +.BR \-l " \fIstring\fP, " \-\-logfile "=" \fIstring\fP +path to the log file. +.sp +Specify the name and path of the log file. +The default is the system log file. +This is the same operation as the +logfile logfile +configuration file directive. +.TP +.BR \-L ", " -\-novirtualips +Do not listen to virtual interfaces. +.sp +Do not listen to virtual interfaces, defined as those with +names containing a colon. This option is deprecated. Please +consider using the configuration file interface command, which +is more versatile. +.TP +.BR \-M ", " -\-modifymmtimer +Modify Multimedia Timer (Windows only). +.sp +Set the Windows Multimedia Timer to highest resolution. This +ensures the resolution does not change while ntpd is running, +avoiding timekeeping glitches associated with changes. +.TP +.BR \-n ", " -\-nofork +Do not fork. +This option must not appear in combination with any of the following options: +wait-sync. +.sp +.TP +.BR \-N ", " -\-nice +Run at high priority. +.sp +To the extent permitted by the operating system, run +ntpd +at the highest priority. +.TP +.BR \-p " \fIstring\fP, " \-\-pidfile "=" \fIstring\fP +path to the PID file. +.sp +Specify the name and path of the file used to record +ntpd's +process ID. +This is the same operation as the +pidfile pidfile +configuration file directive. +.TP +.BR \-P " \fInumber\fP, " \-\-priority "=" \fInumber\fP +Process priority. +This option takes an integer number as its argument. +.sp +To the extent permitted by the operating system, run +ntpd +at the specified +sched_setscheduler(SCHED_FIFO) +priority. +.TP +.BR \-q ", " -\-quit +Set the time and quit. +This option must not appear in combination with any of the following options: +saveconfigquit, wait-sync. +.sp +ntpd +will not daemonize and will exit after the clock is first +synchronized. This behavior mimics that of the +ntpdate +program, which will soon be replaced with a shell script. +The +-g +and +-x +options can be used with this option. +Note: The kernel time discipline is disabled with this option. +.TP +.BR \-r " \fIstring\fP, " \-\-propagationdelay "=" \fIstring\fP +Broadcast/propagation delay. +.sp +Specify 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. +.TP +.BR \-\-saveconfigquit "=\fIstring\fP" +Save parsed configuration and quit. +This option must not appear in combination with any of the following options: +quit, wait-sync. +.sp +Cause ntpd to parse its startup configuration file and save an +equivalent to the given filename and exit. This option was +designed for automated testing. +.TP +.BR \-s " \fIstring\fP, " \-\-statsdir "=" \fIstring\fP +Statistics file location. +.sp +Specify the directory path for files created by the statistics facility. +This is the same operation as the +statsdir statsdir +configuration file directive. +.TP +.BR \-t " \fItkey\fP, " \-\-trustedkey "=" \fItkey\fP +Trusted key number. +This option may appear an unlimited number of times. +.sp +Add a key number to the trusted key list. +.TP +.BR \-u " \fIstring\fP, " \-\-user "=" \fIstring\fP +Run as userid (or userid:groupid). +.sp +Specify a user, and optionally a group, to switch to. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +--enable-clockctl +) and Linux (configure with +--enable-linuxcaps +). +.TP +.BR \-U " \fInumber\fP, " \-\-updateinterval "=" \fInumber\fP +interval in seconds between scans for new or dropped interfaces. +This option takes an integer number as its argument. +.sp +Give the time in seconds between two scans for new or dropped interfaces. +For systems with routing socket support the scans will be performed shortly after the interface change +has been detected by the system. +Use 0 to disable scanning. 60 seconds is the minimum time between scans. +.TP +.BR \-\-var "=\fInvar\fP" +make ARG an ntp variable (RW). +This option may appear an unlimited number of times. +.sp +.TP +.BR \-\-dvar "=\fIndvar\fP" +make ARG an ntp variable (RW|DEF). +This option may appear an unlimited number of times. +.sp +.TP +.BR \-w " \fInumber\fP, " \-\-wait\-sync "=" \fInumber\fP +Seconds to wait for first clock sync. +This option must not appear in combination with any of the following options: +nofork, quit, saveconfigquit. +This option takes an integer number as its argument. +.sp +If greater than zero, alters ntpd behavior when forking to +daemonize. Instead of exiting with status 0 immediately after +the fork, the parent waits up to the specified number of +seconds for the child to first synchronize the clock. The exit +status is zero (success) if the clock was synchronized, +otherwise it is ETIMEDOUT. +This provides the option for a script starting ntpd to easily +wait for the first set of the clock before proceeding. +.TP +.BR \-x ", " -\-slew +Slew up to 600 seconds. +.sp +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 sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. +Note: 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. +Thus, an adjustment as much as 600 s will take almost 14 days to complete. +This option can be used with the +-g +and +-q +options. +See the +tinker +configuration file directive for other options. +Note: The kernel time discipline is disabled with this option. +.TP +.BR \-\-usepcc +Use CPU cycle counter (Windows only). +.sp +Attempt to substitute the CPU counter for QueryPerformanceCounter. +The CPU counter and QueryPerformanceCounter are compared, and if +they have the same frequency, the CPU counter (RDTSC on x86) is +used directly, saving the overhead of a system call. +.TP +.BR \-\-pccfreq "=\fIstring\fP" +Force CPU cycle counter use (Windows only). +.sp +Force substitution the CPU counter for QueryPerformanceCounter. +The CPU counter (RDTSC on x86) is used unconditionally with the +given frequency (in Hz). +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTPD_\fP or \fBNTPD\fP +.fi +.ad +.SH USAGE +.Ss "How NTP Operates" +The +.B +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 +.B +detects that the time on the host +is more than 1000s from the server time, +.B +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 +.B +to exit with a panic message to +the system log. +The +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 +.B +to exit anyway. +.PP +Under ordinary conditions, +.B +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 +.B +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 +.B +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 +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 +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, +.B +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 8 +to get the system clock close to correct before starting +.Xr ntpd 8 , +but this was never more than a mediocre hack and is no longer needed. +.PP +There is a way to start +.Xr ntpd 8 +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 8 +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 8 +with at least the +g +and perhaps the +N +options. +Then, +start the rest of your "normal" processes. +This will give +.Xr ntpd 8 +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 8 +as late as possible in the boot sequence +(perhaps with the +v +flag) +and after +.Xr ntp-wait 8 +exits successfully +it is as safe as it will ever be to start any process that require +stable time. +.Ss "Frequency Discipline" +The +.B +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 +.B +is started and the file does not exist, the +.B +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 +.B +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 +.B +is started and the file does exist, the +.B +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 +.B +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, +.B +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 +.B +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 +.B . +The +q +option is intended for this purpose. +Setting this option will cause +.B +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 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, +.B +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 +.B +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 . +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH FILES +.TP +.BR Pa /etc/ntp.conf +the default name of the configuration file +.TP +.BR Pa /etc/ntp.drift +the default name of the drift file +.TP +.BR Pa /etc/ntp.keys +the default name of the key file +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH "SEE ALSO" +.Xr ntp.conf 5 , +.Xr ntpdate 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.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 +.SH "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH BUGS +The +.B +utility has gotten rather fat. +While not huge, it has gotten +larger than might be desirable for an elevated-priority +.B +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. +.SH NOTES +Portions of this document came from FreeBSD. +.PP +This manual page was \fIAutoGen\fP-erated from the \fBntpd\fP +option definitions. diff --git a/ntpd/ntpd.mdoc.in b/ntpd/ntpd.mdoc.in new file mode 100644 index 000000000..f1e46c9c0 --- /dev/null +++ b/ntpd/ntpd.mdoc.in @@ -0,0 +1,878 @@ +.Dd June 22 2011 +.Dt NTPD @NTPD_MS@ User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:57:43 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpd-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpd +.Nd NTP daemon program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +[ ... ] +.Pp +.Sh DESCRIPTION +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 8 +and +.Xr ntpdc 8 +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. +.Sh "OPTIONS" +.Bl -tag +.It \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.It \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.It \-a ", " -\-authreq +Require crypto authentication. +This option must not appear in combination with any of the following options: +authnoreq. +.sp +Require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is the default. +.It \-A ", " -\-authnoreq +Do not require crypto authentication. +This option must not appear in combination with any of the following options: +authreq. +.sp +Do not require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is almost never a good idea. +.It \-b ", " -\-bcastsync +Allow us to sync to broadcast servers. +.sp +.It \-c " \fIstring\fP, " \-\-configfile "=" \fIstring\fP +configuration file name. +.sp +The name and path of the configuration file, +/etc/ntp.conf +by default. +.It \-d ", " -\-debug\-level +Increase output debug message level. +This option may appear an unlimited number of times. +.sp +Increase the debugging message output level. +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the output debug message level. +This option may appear an unlimited number of times. +.sp +Set the output debugging level. Can be supplied multiple times, +but each overrides the previous value(s). +.It \-f " \fIstring\fP, " \-\-driftfile "=" \fIstring\fP +frequency drift file name. +.sp +The name and path of the frequency file, +/etc/ntp.drift +by default. +This is the same operation as the +driftfile driftfile +configuration specification in the +/etc/ntp.conf +file. +.It \-g ", " -\-panicgate +Allow the first adjustment to be Big. +This option may appear an unlimited number of times. +.sp +Normally, +ntpd +exits 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, +ntpd +will exit with a message to the system log. This option can be used with the +-q +and +-x +options. +See the +tinker +configuration file directive for other options. +.It \-i " \fIstring\fP, " \-\-jaildir "=" \fIstring\fP +Jail directory. +.sp +Chroot the server to the directory +jaildir +. +This option also implies that the server attempts to drop root privileges at startup. +You may need to also specify a +-u +option. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +--enable-clockctl +) and Linux (configure with +--enable-linuxcaps +). +.It \-I " \fIiface\fP, " \-\-interface "=" \fIiface\fP +Listen on an interface name or address. +This option may appear an unlimited number of times. +.sp +Open the network address given, or all the addresses associated with the +given interface name. This option may appear multiple times. This option +also implies not opening other addresses, except wildcard and localhost. +This option is deprecated. Please consider using the configuration file +interface command, which is more versatile. +.It \-k " \fIstring\fP, " \-\-keyfile "=" \fIstring\fP +path to symmetric keys. +.sp +Specify the name and path of the symmetric key file. +/etc/ntp.keys +is the default. +This is the same operation as the +keys keyfile +configuration file directive. +.It \-l " \fIstring\fP, " \-\-logfile "=" \fIstring\fP +path to the log file. +.sp +Specify the name and path of the log file. +The default is the system log file. +This is the same operation as the +logfile logfile +configuration file directive. +.It \-L ", " -\-novirtualips +Do not listen to virtual interfaces. +.sp +Do not listen to virtual interfaces, defined as those with +names containing a colon. This option is deprecated. Please +consider using the configuration file interface command, which +is more versatile. +.It \-M ", " -\-modifymmtimer +Modify Multimedia Timer (Windows only). +.sp +Set the Windows Multimedia Timer to highest resolution. This +ensures the resolution does not change while ntpd is running, +avoiding timekeeping glitches associated with changes. +.It \-n ", " -\-nofork +Do not fork. +This option must not appear in combination with any of the following options: +wait-sync. +.sp +.It \-N ", " -\-nice +Run at high priority. +.sp +To the extent permitted by the operating system, run +ntpd +at the highest priority. +.It \-p " \fIstring\fP, " \-\-pidfile "=" \fIstring\fP +path to the PID file. +.sp +Specify the name and path of the file used to record +ntpd's +process ID. +This is the same operation as the +pidfile pidfile +configuration file directive. +.It \-P " \fInumber\fP, " \-\-priority "=" \fInumber\fP +Process priority. +This option takes an integer number as its argument. +.sp +To the extent permitted by the operating system, run +ntpd +at the specified +sched_setscheduler(SCHED_FIFO) +priority. +.It \-q ", " -\-quit +Set the time and quit. +This option must not appear in combination with any of the following options: +saveconfigquit, wait-sync. +.sp +ntpd +will not daemonize and will exit after the clock is first +synchronized. This behavior mimics that of the +ntpdate +program, which will soon be replaced with a shell script. +The +-g +and +-x +options can be used with this option. +Note: The kernel time discipline is disabled with this option. +.It \-r " \fIstring\fP, " \-\-propagationdelay "=" \fIstring\fP +Broadcast/propagation delay. +.sp +Specify 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. +.It \-\-saveconfigquit "=\fIstring\fP" +Save parsed configuration and quit. +This option must not appear in combination with any of the following options: +quit, wait-sync. +.sp +Cause ntpd to parse its startup configuration file and save an +equivalent to the given filename and exit. This option was +designed for automated testing. +.It \-s " \fIstring\fP, " \-\-statsdir "=" \fIstring\fP +Statistics file location. +.sp +Specify the directory path for files created by the statistics facility. +This is the same operation as the +statsdir statsdir +configuration file directive. +.It \-t " \fItkey\fP, " \-\-trustedkey "=" \fItkey\fP +Trusted key number. +This option may appear an unlimited number of times. +.sp +Add a key number to the trusted key list. +.It \-u " \fIstring\fP, " \-\-user "=" \fIstring\fP +Run as userid (or userid:groupid). +.sp +Specify a user, and optionally a group, to switch to. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +--enable-clockctl +) and Linux (configure with +--enable-linuxcaps +). +.It \-U " \fInumber\fP, " \-\-updateinterval "=" \fInumber\fP +interval in seconds between scans for new or dropped interfaces. +This option takes an integer number as its argument. +.sp +Give the time in seconds between two scans for new or dropped interfaces. +For systems with routing socket support the scans will be performed shortly after the interface change +has been detected by the system. +Use 0 to disable scanning. 60 seconds is the minimum time between scans. +.It \-\-var "=\fInvar\fP" +make ARG an ntp variable (RW). +This option may appear an unlimited number of times. +.sp +.It \-\-dvar "=\fIndvar\fP" +make ARG an ntp variable (RW|DEF). +This option may appear an unlimited number of times. +.sp +.It \-w " \fInumber\fP, " \-\-wait\-sync "=" \fInumber\fP +Seconds to wait for first clock sync. +This option must not appear in combination with any of the following options: +nofork, quit, saveconfigquit. +This option takes an integer number as its argument. +.sp +If greater than zero, alters ntpd behavior when forking to +daemonize. Instead of exiting with status 0 immediately after +the fork, the parent waits up to the specified number of +seconds for the child to first synchronize the clock. The exit +status is zero (success) if the clock was synchronized, +otherwise it is ETIMEDOUT. +This provides the option for a script starting ntpd to easily +wait for the first set of the clock before proceeding. +.It \-x ", " -\-slew +Slew up to 600 seconds. +.sp +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 sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. +Note: 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. +Thus, an adjustment as much as 600 s will take almost 14 days to complete. +This option can be used with the +-g +and +-q +options. +See the +tinker +configuration file directive for other options. +Note: The kernel time discipline is disabled with this option. +.It \-\-usepcc +Use CPU cycle counter (Windows only). +.sp +Attempt to substitute the CPU counter for QueryPerformanceCounter. +The CPU counter and QueryPerformanceCounter are compared, and if +they have the same frequency, the CPU counter (RDTSC on x86) is +used directly, saving the overhead of a system call. +.It \-\-pccfreq "=\fIstring\fP" +Force CPU cycle counter use (Windows only). +.sp +Force substitution the CPU counter for QueryPerformanceCounter. +The CPU counter (RDTSC on x86) is used unconditionally with the +given frequency (in Hz). +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTPD_\fP or \fBNTPD\fP +.fi +.ad +.Sh 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 8 +to get the system clock close to correct before starting +.Xr ntpd 8 , +but this was never more than a mediocre hack and is no longer needed. +.Pp +There is a way to start +.Xr ntpd 8 +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 8 +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 8 +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 8 +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 8 +as late as possible in the boot sequence +(perhaps with the +.Fl v +flag) +and after +.Xr ntp-wait 8 +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 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 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 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 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 . +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh 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 +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh "SEE ALSO" +.Xr ntp.conf 5 , +.Xr ntpdate 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.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 +.Sh "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh 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. +.Sh NOTES +Portions of this document came from FreeBSD. +.Pp +This manual page was \fIAutoGen\fP-erated from the \fBntpd\fP +option definitions. diff --git a/ntpdc/ntpdc.1ntpdcman b/ntpdc/ntpdc.1ntpdcman new file mode 100644 index 000000000..e6936e762 --- /dev/null +++ b/ntpdc/ntpdc.1ntpdcman @@ -0,0 +1,569 @@ +.TH ntpdc 1ntpdcman "22 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:57:51 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpdc-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntpdc \- vendor-specific NTPD control program +.SH SYNOPSIS +.B ntpdc +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ host ...] +.PP +.SH DESCRIPTION +.B +is a utility program used to query +.Xr ntpd 8 +about its +current state and to request changes in that state. +It uses NTP mode 7 control message formats described in the source code. +The program may +be run either in interactive mode or controlled using command line +arguments. +Extensive state and statistics information is available +through the +.B +interface. +In addition, nearly all the +configuration options which can be specified at startup using +ntpd's configuration file may also be specified at run time using +.B . +.SH "OPTIONS" +.TP +.BR \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.TP +.BR \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.TP +.BR \-c " \fIcmd\fP, " \-\-command "=" \fIcmd\fP +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.TP +.BR \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-i ", " -\-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, listpeers, peers, showpeers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.TP +.BR \-l ", " -\-listpeers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary of +their state. This is equivalent to the 'listpeers' interactive command. +.TP +.BR \-n ", " -\-numeric +numeric host addresses. +.sp +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.TP +.BR \-p ", " -\-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +.TP +.BR \-s ", " -\-showpeers +Show a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'dmpeers' interactive command. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPDC_\fP or \fBNTPDC\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH USAGE +If one or more request options are included on the command line +when +.B +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.B +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.B +utility will prompt for +commands if the standard input is a terminal device. +.PP +The +.B +utility uses NTP mode 7 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.B +utility makes +no attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +.PP +The operation of +.B +are specific to the particular +implementation of the +.Xr ntpd 8 +daemon and can be expected to +work only with this and maybe some previous versions of the daemon. +Requests from a remote +.B +utility which affect the +state of the local server must be authenticated, which requires +both the remote program and local server share a common key and key +identifier. +.PP +Note that in contexts where a host name is expected, a +4 +qualifier preceding the host name forces DNS resolution to the IPv4 namespace, +while a +6 +qualifier forces DNS resolution to the IPv6 namespace. +Specifying a command line option other than +i +or +n +will cause the specified query (queries) to be sent to +the indicated host(s) immediately. +Otherwise, +.B +will +attempt to read interactive format commands from the standard +input. +.Ss "Interactive Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +The output of a +command is normally sent to the standard output, but optionally the +output of individual commands may be sent to a file by appending a +.Ql \&> , +followed by a file name, to the command line. +.PP +A number of interactive format commands are executed entirely +within the +.B +utility itself and do not result in NTP +mode 7 requests being sent to a server. +These are described +following. +.TP +.BR Ic \&? Ar command_keyword +.TP +.BR Ic help Ar command_keyword +A +.Sq Ic \&? +will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Sq Ic \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Xr ntpq 8 +than this manual +page. +.TP +.BR Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.TP +.BR Ic host Ar hostname +Set the host to which future queries will be sent. +Hostname may +be either a host name or a numeric address. +.TP +.BR Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +n +switch. +.TP +.BR Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.TP +.BR Ic quit +Exit +.Nm . +.TP +.BR Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.TP +.BR Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 8000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.Ss "Control Message Commands" +Query commands result in NTP mode 7 packets containing requests for +information being sent to the server. +These are read-only commands +in that they make no modification of the server configuration +state. +.TP +.BR Ic listpeers +Obtains and prints a brief list of the peers for which the +server is maintaining state. +These should include all configured +peer associations as well as those peers whose stratum is such that +they are considered by the server to be possible future +synchronization candidates. +.TP +.BR Ic peers +Obtains a list of peers for which the server is maintaining +state, along with a summary of that state. +Summary information +includes the address of the remote peer, the local interface +address (0.0.0.0 if a local address has yet to be determined), the +stratum of the remote peer (a stratum of 16 indicates the remote +peer is unsynchronized), the polling interval, in seconds, the +reachability register, in octal, and the current estimated delay, +offset and dispersion of the peer, all in seconds. +.PP +The character in the left margin indicates the mode this peer +entry is operating in. +A +.Ql \&+ +denotes symmetric active, a +.Ql \&- +indicates symmetric passive, a +.Ql \&= +means the +remote server is being polled in client mode, a +.Ql \&^ +indicates that the server is broadcasting to this address, a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&* +marks the peer the server is currently synchronizing +to. +.PP +The contents of the host field may be one of four forms. +It may +be a host name, an IP address, a reference clock implementation +name with its parameter or +.Fn REFCLK "implementation_number" "parameter" . +On +.Ic hostnames +.Cm no +only IP-addresses +will be displayed. +.TP +.BR Ic dmpeers +A slightly different peer summary list. +Identical to the output +of the +.Ic peers +command, except for the character in the +leftmost column. +Characters only appear beside peers which were +included in the final stage of the clock selection algorithm. +A +.Ql \&. +indicates that this peer was cast off in the falseticker +detection, while a +.Ql \&+ +indicates that the peer made it +through. +A +.Ql \&* +denotes the peer the server is currently +synchronizing with. +.TP +.BR Ic showpeer Ar peer_address Oo Ar ... Oc +Shows a detailed display of the current peer variables for one +or more peers. +Most of these values are described in the NTP +Version 2 specification. +.TP +.BR Ic pstats Ar peer_address Oo Ar ... Oc +Show per-peer statistic counters associated with the specified +peer(s). +.TP +.BR Ic clockinfo Ar clock_peer_address Oo Ar ... Oc +Obtain and print information concerning a peer clock. +The +values obtained provide information on the setting of fudge factors +and other clock performance information. +.TP +.BR Ic kerninfo +Obtain and print kernel phase-lock loop operating parameters. +This information is available only if the kernel has been specially +modified for a precision timekeeping function. +.TP +.BR Ic loopinfo Op Cm oneline | Cm multiline +Print the values of selected loop filter variables. +The loop +filter is the part of NTP which deals with adjusting the local +system clock. +The +.Sq offset +is the last offset given to the +loop filter by the packet processing code. +The +.Sq frequency +is the frequency error of the local clock in parts-per-million +(ppm). +The +.Sq time_const +controls the stiffness of the +phase-lock loop and thus the speed at which it can adapt to +oscillator drift. +The +.Sq watchdog timer +value is the number +of seconds which have elapsed since the last sample offset was +given to the loop filter. +The +.Cm oneline +and +.Cm multiline +options specify the format in which this +information is to be printed, with +.Cm multiline +as the +default. +.TP +.BR Ic sysinfo +Print a variety of system state variables, i.e., state related +to the local server. +All except the last four lines are described +in the NTP Version 3 specification, RFC-1305. +.PP +The +.Sq system flags +show various system flags, some of +which can be set and cleared by the +.Ic enable +and +.Ic disable +configuration commands, respectively. +These are +the +.Cm auth , +.Cm bclient , +.Cm monitor , +.Cm pll , +.Cm pps +and +.Cm stats +flags. +See the +.Xr ntpd 8 +documentation for the meaning of these flags. +There +are two additional flags which are read only, the +.Cm kernel_pll +and +.Cm kernel_pps . +These flags indicate +the synchronization status when the precision time kernel +modifications are in use. +The +.Sq kernel_pll +indicates that +the local clock is being disciplined by the kernel, while the +.Sq kernel_pps +indicates the kernel discipline is provided by the PPS +signal. +.PP +The +.Sq stability +is the residual frequency error remaining +after the system frequency correction is applied and is intended for +maintenance and debugging. +In most architectures, this value will +initially decrease from as high as 500 ppm to a nominal value in +the range .01 to 0.1 ppm. +If it remains high for some time after +starting the daemon, something may be wrong with the local clock, +or the value of the kernel variable +.Va kern.clockrate.tick +may be +incorrect. +.PP +The +.Sq broadcastdelay +shows the default broadcast delay, +as set by the +.Ic broadcastdelay +configuration command. +.PP +The +.Sq authdelay +shows the default authentication delay, +as set by the +.Ic authdelay +configuration command. +.TP +.BR Ic sysstats +Print statistics counters maintained in the protocol +module. +.TP +.BR Ic memstats +Print statistics counters related to memory allocation +code. +.TP +.BR Ic iostats +Print statistics counters maintained in the input-output +module. +.TP +.BR Ic timerstats +Print statistics counters maintained in the timer/event queue +support code. +.TP +.BR Ic reslist +Obtain and print the server's restriction list. +This list is +(usually) printed in sorted order and may help to understand how +the restrictions are applied. +.TP +.BR Ic monlist Op Ar version +Obtain and print traffic counts collected and maintained by the +monitor facility. +The version number should not normally need to be +specified. +.TP +.BR Ic clkbug Ar clock_peer_address Oo Ar ... Oc +Obtain debugging information for a reference clock driver. +This +information is provided only by some clock drivers and is mostly +undecodable without a copy of the driver source in hand. +.Ss "Runtime Configuration Requests" +All requests which cause state changes in the server are +authenticated by the server using a configured NTP key (the +facility can also be disabled by the server by not configuring a +key). +The key number and the corresponding key must also be made +known to +.B . +This can be done using the +.Ic keyid +and +.Ic passwd +commands, the latter of which will prompt at the terminal for a +password to use as the encryption key. +You will also be prompted +automatically for both the key number and password the first time a +command which would result in an authenticated request to the +server is given. +Authentication not only provides verification that +the requester has permission to make such changes, but also gives +an extra degree of protection again transmission errors. +.PP +Authenticated requests always include a timestamp in the packet +data, which is included in the computation of the authentication +code. +This timestamp is compared by the server to its receive time +stamp. +If they differ by more than a small amount the request is +rejected. +This is done for two reasons. +First, it makes simple +replay attacks on the server, by someone who might be able to diff --git a/ntpdc/ntpdc.1ntpdcmdoc b/ntpdc/ntpdc.1ntpdcmdoc new file mode 100644 index 000000000..ab3f0042a --- /dev/null +++ b/ntpdc/ntpdc.1ntpdcmdoc @@ -0,0 +1,793 @@ +.Dd June 22 2011 +.Dt NTPDC 1ntpdcmdoc User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:58:17 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpdc-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpdc +.Nd vendor-specific NTPD control program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +[ host ...] +.Pp +.Sh DESCRIPTION +.Nm +is a utility program used to query +.Xr ntpd 8 +about its +current state and to request changes in that state. +It uses NTP mode 7 control message formats described in the source code. +The program may +be run either in interactive mode or controlled using command line +arguments. +Extensive state and statistics information is available +through the +.Nm +interface. +In addition, nearly all the +configuration options which can be specified at startup using +ntpd's configuration file may also be specified at run time using +.Nm . +.Sh "OPTIONS" +.Bl -tag +.It \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.It \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.It \-c " \fIcmd\fP, " \-\-command "=" \fIcmd\fP +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.It \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-i ", " -\-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, listpeers, peers, showpeers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.It \-l ", " -\-listpeers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary of +their state. This is equivalent to the 'listpeers' interactive command. +.It \-n ", " -\-numeric +numeric host addresses. +.sp +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.It \-p ", " -\-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +.It \-s ", " -\-showpeers +Show a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'dmpeers' interactive command. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPDC_\fP or \fBNTPDC\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE +If one or more request options are included on the command line +when +.Nm +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.Nm +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.Nm +utility will prompt for +commands if the standard input is a terminal device. +.Pp +The +.Nm +utility uses NTP mode 7 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.Nm +utility makes +no attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +.Pp +The operation of +.Nm +are specific to the particular +implementation of the +.Xr ntpd 8 +daemon and can be expected to +work only with this and maybe some previous versions of the daemon. +Requests from a remote +.Nm +utility which affect the +state of the local server must be authenticated, which requires +both the remote program and local server share a common key and key +identifier. +.Pp +Note that in contexts where a host name is expected, a +.Fl 4 +qualifier preceding the host name forces DNS resolution to the IPv4 namespace, +while a +.Fl 6 +qualifier forces DNS resolution to the IPv6 namespace. +Specifying a command line option other than +.Fl i +or +.Fl n +will cause the specified query (queries) to be sent to +the indicated host(s) immediately. +Otherwise, +.Nm +will +attempt to read interactive format commands from the standard +input. +.Ss "Interactive Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +The output of a +command is normally sent to the standard output, but optionally the +output of individual commands may be sent to a file by appending a +.Ql \&> , +followed by a file name, to the command line. +.Pp +A number of interactive format commands are executed entirely +within the +.Nm +utility itself and do not result in NTP +mode 7 requests being sent to a server. +These are described +following. +.Bl -tag -width indent +.It Ic \&? Ar command_keyword +.It Ic help Ar command_keyword +A +.Sq Ic \&? +will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Sq Ic \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Xr ntpq 8 +than this manual +page. +.It Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.It Ic host Ar hostname +Set the host to which future queries will be sent. +Hostname may +be either a host name or a numeric address. +.It Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +.Fl n +switch. +.It Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.It Ic quit +Exit +.Nm . +.It Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.It Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 8000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.El +.Ss "Control Message Commands" +Query commands result in NTP mode 7 packets containing requests for +information being sent to the server. +These are read-only commands +in that they make no modification of the server configuration +state. +.Bl -tag -width indent +.It Ic listpeers +Obtains and prints a brief list of the peers for which the +server is maintaining state. +These should include all configured +peer associations as well as those peers whose stratum is such that +they are considered by the server to be possible future +synchronization candidates. +.It Ic peers +Obtains a list of peers for which the server is maintaining +state, along with a summary of that state. +Summary information +includes the address of the remote peer, the local interface +address (0.0.0.0 if a local address has yet to be determined), the +stratum of the remote peer (a stratum of 16 indicates the remote +peer is unsynchronized), the polling interval, in seconds, the +reachability register, in octal, and the current estimated delay, +offset and dispersion of the peer, all in seconds. +.Pp +The character in the left margin indicates the mode this peer +entry is operating in. +A +.Ql \&+ +denotes symmetric active, a +.Ql \&- +indicates symmetric passive, a +.Ql \&= +means the +remote server is being polled in client mode, a +.Ql \&^ +indicates that the server is broadcasting to this address, a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&* +marks the peer the server is currently synchronizing +to. +.Pp +The contents of the host field may be one of four forms. +It may +be a host name, an IP address, a reference clock implementation +name with its parameter or +.Fn REFCLK "implementation_number" "parameter" . +On +.Ic hostnames +.Cm no +only IP-addresses +will be displayed. +.It Ic dmpeers +A slightly different peer summary list. +Identical to the output +of the +.Ic peers +command, except for the character in the +leftmost column. +Characters only appear beside peers which were +included in the final stage of the clock selection algorithm. +A +.Ql \&. +indicates that this peer was cast off in the falseticker +detection, while a +.Ql \&+ +indicates that the peer made it +through. +A +.Ql \&* +denotes the peer the server is currently +synchronizing with. +.It Ic showpeer Ar peer_address Oo Ar ... Oc +Shows a detailed display of the current peer variables for one +or more peers. +Most of these values are described in the NTP +Version 2 specification. +.It Ic pstats Ar peer_address Oo Ar ... Oc +Show per-peer statistic counters associated with the specified +peer(s). +.It Ic clockinfo Ar clock_peer_address Oo Ar ... Oc +Obtain and print information concerning a peer clock. +The +values obtained provide information on the setting of fudge factors +and other clock performance information. +.It Ic kerninfo +Obtain and print kernel phase-lock loop operating parameters. +This information is available only if the kernel has been specially +modified for a precision timekeeping function. +.It Ic loopinfo Op Cm oneline | Cm multiline +Print the values of selected loop filter variables. +The loop +filter is the part of NTP which deals with adjusting the local +system clock. +The +.Sq offset +is the last offset given to the +loop filter by the packet processing code. +The +.Sq frequency +is the frequency error of the local clock in parts-per-million +(ppm). +The +.Sq time_const +controls the stiffness of the +phase-lock loop and thus the speed at which it can adapt to +oscillator drift. +The +.Sq watchdog timer +value is the number +of seconds which have elapsed since the last sample offset was +given to the loop filter. +The +.Cm oneline +and +.Cm multiline +options specify the format in which this +information is to be printed, with +.Cm multiline +as the +default. +.It Ic sysinfo +Print a variety of system state variables, i.e., state related +to the local server. +All except the last four lines are described +in the NTP Version 3 specification, RFC-1305. +.Pp +The +.Sq system flags +show various system flags, some of +which can be set and cleared by the +.Ic enable +and +.Ic disable +configuration commands, respectively. +These are +the +.Cm auth , +.Cm bclient , +.Cm monitor , +.Cm pll , +.Cm pps +and +.Cm stats +flags. +See the +.Xr ntpd 8 +documentation for the meaning of these flags. +There +are two additional flags which are read only, the +.Cm kernel_pll +and +.Cm kernel_pps . +These flags indicate +the synchronization status when the precision time kernel +modifications are in use. +The +.Sq kernel_pll +indicates that +the local clock is being disciplined by the kernel, while the +.Sq kernel_pps +indicates the kernel discipline is provided by the PPS +signal. +.Pp +The +.Sq stability +is the residual frequency error remaining +after the system frequency correction is applied and is intended for +maintenance and debugging. +In most architectures, this value will +initially decrease from as high as 500 ppm to a nominal value in +the range .01 to 0.1 ppm. +If it remains high for some time after +starting the daemon, something may be wrong with the local clock, +or the value of the kernel variable +.Va kern.clockrate.tick +may be +incorrect. +.Pp +The +.Sq broadcastdelay +shows the default broadcast delay, +as set by the +.Ic broadcastdelay +configuration command. +.Pp +The +.Sq authdelay +shows the default authentication delay, +as set by the +.Ic authdelay +configuration command. +.It Ic sysstats +Print statistics counters maintained in the protocol +module. +.It Ic memstats +Print statistics counters related to memory allocation +code. +.It Ic iostats +Print statistics counters maintained in the input-output +module. +.It Ic timerstats +Print statistics counters maintained in the timer/event queue +support code. +.It Ic reslist +Obtain and print the server's restriction list. +This list is +(usually) printed in sorted order and may help to understand how +the restrictions are applied. +.It Ic monlist Op Ar version +Obtain and print traffic counts collected and maintained by the +monitor facility. +The version number should not normally need to be +specified. +.It Ic clkbug Ar clock_peer_address Oo Ar ... Oc +Obtain debugging information for a reference clock driver. +This +information is provided only by some clock drivers and is mostly +undecodable without a copy of the driver source in hand. +.El +.Ss "Runtime Configuration Requests" +All requests which cause state changes in the server are +authenticated by the server using a configured NTP key (the +facility can also be disabled by the server by not configuring a +key). +The key number and the corresponding key must also be made +known to +.Nm . +This can be done using the +.Ic keyid +and +.Ic passwd +commands, the latter of which will prompt at the terminal for a +password to use as the encryption key. +You will also be prompted +automatically for both the key number and password the first time a +command which would result in an authenticated request to the +server is given. +Authentication not only provides verification that +the requester has permission to make such changes, but also gives +an extra degree of protection again transmission errors. +.Pp +Authenticated requests always include a timestamp in the packet +data, which is included in the computation of the authentication +code. +This timestamp is compared by the server to its receive time +stamp. +If they differ by more than a small amount the request is +rejected. +This is done for two reasons. +First, it makes simple +replay attacks on the server, by someone who might be able to +overhear traffic on your LAN, much more difficult. +Second, it makes +it more difficult to request configuration changes to your server +from topologically remote hosts. +While the reconfiguration facility +will work well with a server on the local host, and may work +adequately between time-synchronized hosts on the same LAN, it will +work very poorly for more distant hosts. +As such, if reasonable +passwords are chosen, care is taken in the distribution and +protection of keys and appropriate source address restrictions are +applied, the run time reconfiguration facility should provide an +adequate level of security. +.Pp +The following commands all make authenticated requests. +.Bl -tag -width indent +.It Xo Ic addpeer Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Add a configured peer association at the given address and +operating in symmetric active mode. +Note that an existing +association with the same peer may be deleted when this command is +executed, or may simply be converted to conform to the new +configuration, as appropriate. +If the optional +.Ar keyid +is a +nonzero integer, all outgoing packets to the remote server will +have an authentication field attached encrypted with this key. +If +the value is 0 (or not given) no authentication will be done. +The +.Ar version +can be 1, 2 or 3 and defaults to 3. +The +.Cm prefer +keyword indicates a preferred peer (and thus will +be used primarily for clock synchronisation if possible). +The +preferred peer also determines the validity of the PPS signal - if +the preferred peer is suitable for synchronisation so is the PPS +signal. +.It Xo Ic addserver Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Identical to the addpeer command, except that the operating +mode is client. +.It Xo Ic broadcast Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Identical to the addpeer command, except that the operating +mode is broadcast. +In this case a valid key identifier and key are +required. +The +.Ar peer_address +parameter can be the broadcast +address of the local network or a multicast group address assigned +to NTP. +If a multicast address, a multicast-capable kernel is +required. +.It Ic unconfig Ar peer_address Oo Ar ... Oc +This command causes the configured bit to be removed from the +specified peer(s). +In many cases this will cause the peer +association to be deleted. +When appropriate, however, the +association may persist in an unconfigured mode if the remote peer +is willing to continue on in this fashion. +.It Xo Ic fudge Ar peer_address +.Op Cm time1 +.Op Cm time2 +.Op Ar stratum +.Op Ar refid +.Xc +This command provides a way to set certain data for a reference +clock. +See the source listing for further information. +.It Xo Ic enable +.Oo +.Cm auth | Cm bclient | +.Cm calibrate | Cm kernel | +.Cm monitor | Cm ntp | +.Cm pps | Cm stats +.Oc +.Xc +.It Xo Ic disable +.Oo +.Cm auth | Cm bclient | +.Cm calibrate | Cm kernel | +.Cm monitor | Cm ntp | +.Cm pps | Cm stats +.Oc +.Xc +These commands operate in the same way as the +.Ic enable +and +.Ic disable +configuration file commands of +.Xr ntpd 8 . +.Bl -tag -width indent +.It Cm auth +Enables the server to synchronize with unconfigured peers only +if the peer has been correctly authenticated using either public key +or private key cryptography. +The default for this flag is enable. +.It Cm bclient +Enables the server to listen for a message from a broadcast or +multicast server, as in the multicastclient command with +default address. +The default for this flag is disable. +.It Cm calibrate +Enables the calibrate feature for reference clocks. +The default for this flag is disable. +.It Cm kernel +Enables the kernel time discipline, if available. +The default for this flag is enable if support is available, otherwise disable. +.It Cm monitor +Enables the monitoring facility. +See the +.Xr ntpdc 8 . +program and the monlist command or further information. +The default for this flag is enable. +.It Cm ntp +Enables time and frequency discipline. +In effect, this switch opens and closes the feedback loop, +which is useful for testing. +The default for this flag is enable. +.It Cm pps +Enables the pulse-per-second (PPS) signal when frequency +and time is disciplined by the precision time kernel modifications. +See the +.Qq A Kernel Model for Precision Timekeeping +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) +page for further information. +The default for this flag is disable. +.It Cm stats +Enables the statistics facility. +See the +.Sx Monitoring Options +section of +.Xr ntp.conf 5 +for further information. +The default for this flag is disable. +.El +.It Xo Ic restrict Ar address Ar mask +.Ar flag Oo Ar ... Oc +.Xc +This command operates in the same way as the +.Ic restrict +configuration file commands of +.Xr ntpd 8 . +.It Xo Ic unrestrict Ar address Ar mask +.Ar flag Oo Ar ... Oc +.Xc +Unrestrict the matching entry from the restrict list. +.It Xo Ic delrestrict Ar address Ar mask +.Op Cm ntpport +.Xc +Delete the matching entry from the restrict list. +.It Ic readkeys +Causes the current set of authentication keys to be purged and +a new set to be obtained by rereading the keys file (which must +have been specified in the +.Xr ntpd 8 +configuration file). +This +allows encryption keys to be changed without restarting the +server. +.It Ic trustedkey Ar keyid Oo Ar ... Oc +.It Ic untrustedkey Ar keyid Oo Ar ... Oc +These commands operate in the same way as the +.Ic trustedkey +and +.Ic untrustedkey +configuration file +commands of +.Xr ntpd 8 . +.It Ic authinfo +Returns information concerning the authentication module, +including known keys and counts of encryptions and decryptions +which have been done. +.It Ic traps +Display the traps set in the server. +See the source listing for +further information. +.It Xo Ic addtrap Ar address +.Op Ar port +.Op Ar interface +.Xc +Set a trap for asynchronous messages. +See the source listing +for further information. +.It Xo Ic clrtrap Ar address +.Op Ar port +.Op Ar interface +.Xc +Clear a trap for asynchronous messages. +See the source listing +for further information. +.It Ic reset +Clear the statistics counters in various modules of the server. +See the source listing for further information. +.El +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh "SEE ALSO" +.Xr ntp.conf 5 , +.Xr ntpd 8 +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Sh AUTHORS +The formatting directives in this document came from FreeBSD. +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh BUGS +The +.Nm +utility is a crude hack. +Much of the information it shows is +deadly boring and could only be loved by its implementer. +The +program was designed so that new (and temporary) features were easy +to hack in, at great expense to the program's ease of use. +Despite +this, the program is occasionally useful. +.Pp +Please report bugs to http://bugs.ntp.org . +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpdc\fP +option definitions. diff --git a/ntpdc/ntpdc.man.in b/ntpdc/ntpdc.man.in new file mode 100644 index 000000000..7df655f77 --- /dev/null +++ b/ntpdc/ntpdc.man.in @@ -0,0 +1,569 @@ +.TH ntpdc @NTPDC_MS@ "22 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:57:51 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpdc-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntpdc \- vendor-specific NTPD control program +.SH SYNOPSIS +.B ntpdc +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ host ...] +.PP +.SH DESCRIPTION +.B +is a utility program used to query +.Xr ntpd 8 +about its +current state and to request changes in that state. +It uses NTP mode 7 control message formats described in the source code. +The program may +be run either in interactive mode or controlled using command line +arguments. +Extensive state and statistics information is available +through the +.B +interface. +In addition, nearly all the +configuration options which can be specified at startup using +ntpd's configuration file may also be specified at run time using +.B . +.SH "OPTIONS" +.TP +.BR \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.TP +.BR \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.TP +.BR \-c " \fIcmd\fP, " \-\-command "=" \fIcmd\fP +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.TP +.BR \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-i ", " -\-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, listpeers, peers, showpeers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.TP +.BR \-l ", " -\-listpeers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary of +their state. This is equivalent to the 'listpeers' interactive command. +.TP +.BR \-n ", " -\-numeric +numeric host addresses. +.sp +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.TP +.BR \-p ", " -\-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +.TP +.BR \-s ", " -\-showpeers +Show a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'dmpeers' interactive command. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPDC_\fP or \fBNTPDC\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH USAGE +If one or more request options are included on the command line +when +.B +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.B +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.B +utility will prompt for +commands if the standard input is a terminal device. +.PP +The +.B +utility uses NTP mode 7 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.B +utility makes +no attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +.PP +The operation of +.B +are specific to the particular +implementation of the +.Xr ntpd 8 +daemon and can be expected to +work only with this and maybe some previous versions of the daemon. +Requests from a remote +.B +utility which affect the +state of the local server must be authenticated, which requires +both the remote program and local server share a common key and key +identifier. +.PP +Note that in contexts where a host name is expected, a +4 +qualifier preceding the host name forces DNS resolution to the IPv4 namespace, +while a +6 +qualifier forces DNS resolution to the IPv6 namespace. +Specifying a command line option other than +i +or +n +will cause the specified query (queries) to be sent to +the indicated host(s) immediately. +Otherwise, +.B +will +attempt to read interactive format commands from the standard +input. +.Ss "Interactive Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +The output of a +command is normally sent to the standard output, but optionally the +output of individual commands may be sent to a file by appending a +.Ql \&> , +followed by a file name, to the command line. +.PP +A number of interactive format commands are executed entirely +within the +.B +utility itself and do not result in NTP +mode 7 requests being sent to a server. +These are described +following. +.TP +.BR Ic \&? Ar command_keyword +.TP +.BR Ic help Ar command_keyword +A +.Sq Ic \&? +will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Sq Ic \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Xr ntpq 8 +than this manual +page. +.TP +.BR Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.TP +.BR Ic host Ar hostname +Set the host to which future queries will be sent. +Hostname may +be either a host name or a numeric address. +.TP +.BR Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +n +switch. +.TP +.BR Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.TP +.BR Ic quit +Exit +.Nm . +.TP +.BR Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.TP +.BR Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 8000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.Ss "Control Message Commands" +Query commands result in NTP mode 7 packets containing requests for +information being sent to the server. +These are read-only commands +in that they make no modification of the server configuration +state. +.TP +.BR Ic listpeers +Obtains and prints a brief list of the peers for which the +server is maintaining state. +These should include all configured +peer associations as well as those peers whose stratum is such that +they are considered by the server to be possible future +synchronization candidates. +.TP +.BR Ic peers +Obtains a list of peers for which the server is maintaining +state, along with a summary of that state. +Summary information +includes the address of the remote peer, the local interface +address (0.0.0.0 if a local address has yet to be determined), the +stratum of the remote peer (a stratum of 16 indicates the remote +peer is unsynchronized), the polling interval, in seconds, the +reachability register, in octal, and the current estimated delay, +offset and dispersion of the peer, all in seconds. +.PP +The character in the left margin indicates the mode this peer +entry is operating in. +A +.Ql \&+ +denotes symmetric active, a +.Ql \&- +indicates symmetric passive, a +.Ql \&= +means the +remote server is being polled in client mode, a +.Ql \&^ +indicates that the server is broadcasting to this address, a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&* +marks the peer the server is currently synchronizing +to. +.PP +The contents of the host field may be one of four forms. +It may +be a host name, an IP address, a reference clock implementation +name with its parameter or +.Fn REFCLK "implementation_number" "parameter" . +On +.Ic hostnames +.Cm no +only IP-addresses +will be displayed. +.TP +.BR Ic dmpeers +A slightly different peer summary list. +Identical to the output +of the +.Ic peers +command, except for the character in the +leftmost column. +Characters only appear beside peers which were +included in the final stage of the clock selection algorithm. +A +.Ql \&. +indicates that this peer was cast off in the falseticker +detection, while a +.Ql \&+ +indicates that the peer made it +through. +A +.Ql \&* +denotes the peer the server is currently +synchronizing with. +.TP +.BR Ic showpeer Ar peer_address Oo Ar ... Oc +Shows a detailed display of the current peer variables for one +or more peers. +Most of these values are described in the NTP +Version 2 specification. +.TP +.BR Ic pstats Ar peer_address Oo Ar ... Oc +Show per-peer statistic counters associated with the specified +peer(s). +.TP +.BR Ic clockinfo Ar clock_peer_address Oo Ar ... Oc +Obtain and print information concerning a peer clock. +The +values obtained provide information on the setting of fudge factors +and other clock performance information. +.TP +.BR Ic kerninfo +Obtain and print kernel phase-lock loop operating parameters. +This information is available only if the kernel has been specially +modified for a precision timekeeping function. +.TP +.BR Ic loopinfo Op Cm oneline | Cm multiline +Print the values of selected loop filter variables. +The loop +filter is the part of NTP which deals with adjusting the local +system clock. +The +.Sq offset +is the last offset given to the +loop filter by the packet processing code. +The +.Sq frequency +is the frequency error of the local clock in parts-per-million +(ppm). +The +.Sq time_const +controls the stiffness of the +phase-lock loop and thus the speed at which it can adapt to +oscillator drift. +The +.Sq watchdog timer +value is the number +of seconds which have elapsed since the last sample offset was +given to the loop filter. +The +.Cm oneline +and +.Cm multiline +options specify the format in which this +information is to be printed, with +.Cm multiline +as the +default. +.TP +.BR Ic sysinfo +Print a variety of system state variables, i.e., state related +to the local server. +All except the last four lines are described +in the NTP Version 3 specification, RFC-1305. +.PP +The +.Sq system flags +show various system flags, some of +which can be set and cleared by the +.Ic enable +and +.Ic disable +configuration commands, respectively. +These are +the +.Cm auth , +.Cm bclient , +.Cm monitor , +.Cm pll , +.Cm pps +and +.Cm stats +flags. +See the +.Xr ntpd 8 +documentation for the meaning of these flags. +There +are two additional flags which are read only, the +.Cm kernel_pll +and +.Cm kernel_pps . +These flags indicate +the synchronization status when the precision time kernel +modifications are in use. +The +.Sq kernel_pll +indicates that +the local clock is being disciplined by the kernel, while the +.Sq kernel_pps +indicates the kernel discipline is provided by the PPS +signal. +.PP +The +.Sq stability +is the residual frequency error remaining +after the system frequency correction is applied and is intended for +maintenance and debugging. +In most architectures, this value will +initially decrease from as high as 500 ppm to a nominal value in +the range .01 to 0.1 ppm. +If it remains high for some time after +starting the daemon, something may be wrong with the local clock, +or the value of the kernel variable +.Va kern.clockrate.tick +may be +incorrect. +.PP +The +.Sq broadcastdelay +shows the default broadcast delay, +as set by the +.Ic broadcastdelay +configuration command. +.PP +The +.Sq authdelay +shows the default authentication delay, +as set by the +.Ic authdelay +configuration command. +.TP +.BR Ic sysstats +Print statistics counters maintained in the protocol +module. +.TP +.BR Ic memstats +Print statistics counters related to memory allocation +code. +.TP +.BR Ic iostats +Print statistics counters maintained in the input-output +module. +.TP +.BR Ic timerstats +Print statistics counters maintained in the timer/event queue +support code. +.TP +.BR Ic reslist +Obtain and print the server's restriction list. +This list is +(usually) printed in sorted order and may help to understand how +the restrictions are applied. +.TP +.BR Ic monlist Op Ar version +Obtain and print traffic counts collected and maintained by the +monitor facility. +The version number should not normally need to be +specified. +.TP +.BR Ic clkbug Ar clock_peer_address Oo Ar ... Oc +Obtain debugging information for a reference clock driver. +This +information is provided only by some clock drivers and is mostly +undecodable without a copy of the driver source in hand. +.Ss "Runtime Configuration Requests" +All requests which cause state changes in the server are +authenticated by the server using a configured NTP key (the +facility can also be disabled by the server by not configuring a +key). +The key number and the corresponding key must also be made +known to +.B . +This can be done using the +.Ic keyid +and +.Ic passwd +commands, the latter of which will prompt at the terminal for a +password to use as the encryption key. +You will also be prompted +automatically for both the key number and password the first time a +command which would result in an authenticated request to the +server is given. +Authentication not only provides verification that +the requester has permission to make such changes, but also gives +an extra degree of protection again transmission errors. +.PP +Authenticated requests always include a timestamp in the packet +data, which is included in the computation of the authentication +code. +This timestamp is compared by the server to its receive time +stamp. +If they differ by more than a small amount the request is +rejected. +This is done for two reasons. +First, it makes simple +replay attacks on the server, by someone who might be able to diff --git a/ntpdc/ntpdc.mdoc.in b/ntpdc/ntpdc.mdoc.in new file mode 100644 index 000000000..7a32a43ee --- /dev/null +++ b/ntpdc/ntpdc.mdoc.in @@ -0,0 +1,793 @@ +.Dd June 22 2011 +.Dt NTPDC @NTPDC_MS@ User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:58:17 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpdc-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpdc +.Nd vendor-specific NTPD control program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +[ host ...] +.Pp +.Sh DESCRIPTION +.Nm +is a utility program used to query +.Xr ntpd 8 +about its +current state and to request changes in that state. +It uses NTP mode 7 control message formats described in the source code. +The program may +be run either in interactive mode or controlled using command line +arguments. +Extensive state and statistics information is available +through the +.Nm +interface. +In addition, nearly all the +configuration options which can be specified at startup using +ntpd's configuration file may also be specified at run time using +.Nm . +.Sh "OPTIONS" +.Bl -tag +.It \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.It \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.It \-c " \fIcmd\fP, " \-\-command "=" \fIcmd\fP +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.It \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-i ", " -\-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, listpeers, peers, showpeers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.It \-l ", " -\-listpeers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary of +their state. This is equivalent to the 'listpeers' interactive command. +.It \-n ", " -\-numeric +numeric host addresses. +.sp +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.It \-p ", " -\-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +.It \-s ", " -\-showpeers +Show a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'dmpeers' interactive command. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPDC_\fP or \fBNTPDC\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE +If one or more request options are included on the command line +when +.Nm +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.Nm +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.Nm +utility will prompt for +commands if the standard input is a terminal device. +.Pp +The +.Nm +utility uses NTP mode 7 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.Nm +utility makes +no attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +.Pp +The operation of +.Nm +are specific to the particular +implementation of the +.Xr ntpd 8 +daemon and can be expected to +work only with this and maybe some previous versions of the daemon. +Requests from a remote +.Nm +utility which affect the +state of the local server must be authenticated, which requires +both the remote program and local server share a common key and key +identifier. +.Pp +Note that in contexts where a host name is expected, a +.Fl 4 +qualifier preceding the host name forces DNS resolution to the IPv4 namespace, +while a +.Fl 6 +qualifier forces DNS resolution to the IPv6 namespace. +Specifying a command line option other than +.Fl i +or +.Fl n +will cause the specified query (queries) to be sent to +the indicated host(s) immediately. +Otherwise, +.Nm +will +attempt to read interactive format commands from the standard +input. +.Ss "Interactive Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +The output of a +command is normally sent to the standard output, but optionally the +output of individual commands may be sent to a file by appending a +.Ql \&> , +followed by a file name, to the command line. +.Pp +A number of interactive format commands are executed entirely +within the +.Nm +utility itself and do not result in NTP +mode 7 requests being sent to a server. +These are described +following. +.Bl -tag -width indent +.It Ic \&? Ar command_keyword +.It Ic help Ar command_keyword +A +.Sq Ic \&? +will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Sq Ic \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Xr ntpq 8 +than this manual +page. +.It Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.It Ic host Ar hostname +Set the host to which future queries will be sent. +Hostname may +be either a host name or a numeric address. +.It Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +.Fl n +switch. +.It Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.It Ic quit +Exit +.Nm . +.It Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.It Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 8000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.El +.Ss "Control Message Commands" +Query commands result in NTP mode 7 packets containing requests for +information being sent to the server. +These are read-only commands +in that they make no modification of the server configuration +state. +.Bl -tag -width indent +.It Ic listpeers +Obtains and prints a brief list of the peers for which the +server is maintaining state. +These should include all configured +peer associations as well as those peers whose stratum is such that +they are considered by the server to be possible future +synchronization candidates. +.It Ic peers +Obtains a list of peers for which the server is maintaining +state, along with a summary of that state. +Summary information +includes the address of the remote peer, the local interface +address (0.0.0.0 if a local address has yet to be determined), the +stratum of the remote peer (a stratum of 16 indicates the remote +peer is unsynchronized), the polling interval, in seconds, the +reachability register, in octal, and the current estimated delay, +offset and dispersion of the peer, all in seconds. +.Pp +The character in the left margin indicates the mode this peer +entry is operating in. +A +.Ql \&+ +denotes symmetric active, a +.Ql \&- +indicates symmetric passive, a +.Ql \&= +means the +remote server is being polled in client mode, a +.Ql \&^ +indicates that the server is broadcasting to this address, a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&* +marks the peer the server is currently synchronizing +to. +.Pp +The contents of the host field may be one of four forms. +It may +be a host name, an IP address, a reference clock implementation +name with its parameter or +.Fn REFCLK "implementation_number" "parameter" . +On +.Ic hostnames +.Cm no +only IP-addresses +will be displayed. +.It Ic dmpeers +A slightly different peer summary list. +Identical to the output +of the +.Ic peers +command, except for the character in the +leftmost column. +Characters only appear beside peers which were +included in the final stage of the clock selection algorithm. +A +.Ql \&. +indicates that this peer was cast off in the falseticker +detection, while a +.Ql \&+ +indicates that the peer made it +through. +A +.Ql \&* +denotes the peer the server is currently +synchronizing with. +.It Ic showpeer Ar peer_address Oo Ar ... Oc +Shows a detailed display of the current peer variables for one +or more peers. +Most of these values are described in the NTP +Version 2 specification. +.It Ic pstats Ar peer_address Oo Ar ... Oc +Show per-peer statistic counters associated with the specified +peer(s). +.It Ic clockinfo Ar clock_peer_address Oo Ar ... Oc +Obtain and print information concerning a peer clock. +The +values obtained provide information on the setting of fudge factors +and other clock performance information. +.It Ic kerninfo +Obtain and print kernel phase-lock loop operating parameters. +This information is available only if the kernel has been specially +modified for a precision timekeeping function. +.It Ic loopinfo Op Cm oneline | Cm multiline +Print the values of selected loop filter variables. +The loop +filter is the part of NTP which deals with adjusting the local +system clock. +The +.Sq offset +is the last offset given to the +loop filter by the packet processing code. +The +.Sq frequency +is the frequency error of the local clock in parts-per-million +(ppm). +The +.Sq time_const +controls the stiffness of the +phase-lock loop and thus the speed at which it can adapt to +oscillator drift. +The +.Sq watchdog timer +value is the number +of seconds which have elapsed since the last sample offset was +given to the loop filter. +The +.Cm oneline +and +.Cm multiline +options specify the format in which this +information is to be printed, with +.Cm multiline +as the +default. +.It Ic sysinfo +Print a variety of system state variables, i.e., state related +to the local server. +All except the last four lines are described +in the NTP Version 3 specification, RFC-1305. +.Pp +The +.Sq system flags +show various system flags, some of +which can be set and cleared by the +.Ic enable +and +.Ic disable +configuration commands, respectively. +These are +the +.Cm auth , +.Cm bclient , +.Cm monitor , +.Cm pll , +.Cm pps +and +.Cm stats +flags. +See the +.Xr ntpd 8 +documentation for the meaning of these flags. +There +are two additional flags which are read only, the +.Cm kernel_pll +and +.Cm kernel_pps . +These flags indicate +the synchronization status when the precision time kernel +modifications are in use. +The +.Sq kernel_pll +indicates that +the local clock is being disciplined by the kernel, while the +.Sq kernel_pps +indicates the kernel discipline is provided by the PPS +signal. +.Pp +The +.Sq stability +is the residual frequency error remaining +after the system frequency correction is applied and is intended for +maintenance and debugging. +In most architectures, this value will +initially decrease from as high as 500 ppm to a nominal value in +the range .01 to 0.1 ppm. +If it remains high for some time after +starting the daemon, something may be wrong with the local clock, +or the value of the kernel variable +.Va kern.clockrate.tick +may be +incorrect. +.Pp +The +.Sq broadcastdelay +shows the default broadcast delay, +as set by the +.Ic broadcastdelay +configuration command. +.Pp +The +.Sq authdelay +shows the default authentication delay, +as set by the +.Ic authdelay +configuration command. +.It Ic sysstats +Print statistics counters maintained in the protocol +module. +.It Ic memstats +Print statistics counters related to memory allocation +code. +.It Ic iostats +Print statistics counters maintained in the input-output +module. +.It Ic timerstats +Print statistics counters maintained in the timer/event queue +support code. +.It Ic reslist +Obtain and print the server's restriction list. +This list is +(usually) printed in sorted order and may help to understand how +the restrictions are applied. +.It Ic monlist Op Ar version +Obtain and print traffic counts collected and maintained by the +monitor facility. +The version number should not normally need to be +specified. +.It Ic clkbug Ar clock_peer_address Oo Ar ... Oc +Obtain debugging information for a reference clock driver. +This +information is provided only by some clock drivers and is mostly +undecodable without a copy of the driver source in hand. +.El +.Ss "Runtime Configuration Requests" +All requests which cause state changes in the server are +authenticated by the server using a configured NTP key (the +facility can also be disabled by the server by not configuring a +key). +The key number and the corresponding key must also be made +known to +.Nm . +This can be done using the +.Ic keyid +and +.Ic passwd +commands, the latter of which will prompt at the terminal for a +password to use as the encryption key. +You will also be prompted +automatically for both the key number and password the first time a +command which would result in an authenticated request to the +server is given. +Authentication not only provides verification that +the requester has permission to make such changes, but also gives +an extra degree of protection again transmission errors. +.Pp +Authenticated requests always include a timestamp in the packet +data, which is included in the computation of the authentication +code. +This timestamp is compared by the server to its receive time +stamp. +If they differ by more than a small amount the request is +rejected. +This is done for two reasons. +First, it makes simple +replay attacks on the server, by someone who might be able to +overhear traffic on your LAN, much more difficult. +Second, it makes +it more difficult to request configuration changes to your server +from topologically remote hosts. +While the reconfiguration facility +will work well with a server on the local host, and may work +adequately between time-synchronized hosts on the same LAN, it will +work very poorly for more distant hosts. +As such, if reasonable +passwords are chosen, care is taken in the distribution and +protection of keys and appropriate source address restrictions are +applied, the run time reconfiguration facility should provide an +adequate level of security. +.Pp +The following commands all make authenticated requests. +.Bl -tag -width indent +.It Xo Ic addpeer Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Add a configured peer association at the given address and +operating in symmetric active mode. +Note that an existing +association with the same peer may be deleted when this command is +executed, or may simply be converted to conform to the new +configuration, as appropriate. +If the optional +.Ar keyid +is a +nonzero integer, all outgoing packets to the remote server will +have an authentication field attached encrypted with this key. +If +the value is 0 (or not given) no authentication will be done. +The +.Ar version +can be 1, 2 or 3 and defaults to 3. +The +.Cm prefer +keyword indicates a preferred peer (and thus will +be used primarily for clock synchronisation if possible). +The +preferred peer also determines the validity of the PPS signal - if +the preferred peer is suitable for synchronisation so is the PPS +signal. +.It Xo Ic addserver Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Identical to the addpeer command, except that the operating +mode is client. +.It Xo Ic broadcast Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Identical to the addpeer command, except that the operating +mode is broadcast. +In this case a valid key identifier and key are +required. +The +.Ar peer_address +parameter can be the broadcast +address of the local network or a multicast group address assigned +to NTP. +If a multicast address, a multicast-capable kernel is +required. +.It Ic unconfig Ar peer_address Oo Ar ... Oc +This command causes the configured bit to be removed from the +specified peer(s). +In many cases this will cause the peer +association to be deleted. +When appropriate, however, the +association may persist in an unconfigured mode if the remote peer +is willing to continue on in this fashion. +.It Xo Ic fudge Ar peer_address +.Op Cm time1 +.Op Cm time2 +.Op Ar stratum +.Op Ar refid +.Xc +This command provides a way to set certain data for a reference +clock. +See the source listing for further information. +.It Xo Ic enable +.Oo +.Cm auth | Cm bclient | +.Cm calibrate | Cm kernel | +.Cm monitor | Cm ntp | +.Cm pps | Cm stats +.Oc +.Xc +.It Xo Ic disable +.Oo +.Cm auth | Cm bclient | +.Cm calibrate | Cm kernel | +.Cm monitor | Cm ntp | +.Cm pps | Cm stats +.Oc +.Xc +These commands operate in the same way as the +.Ic enable +and +.Ic disable +configuration file commands of +.Xr ntpd 8 . +.Bl -tag -width indent +.It Cm auth +Enables the server to synchronize with unconfigured peers only +if the peer has been correctly authenticated using either public key +or private key cryptography. +The default for this flag is enable. +.It Cm bclient +Enables the server to listen for a message from a broadcast or +multicast server, as in the multicastclient command with +default address. +The default for this flag is disable. +.It Cm calibrate +Enables the calibrate feature for reference clocks. +The default for this flag is disable. +.It Cm kernel +Enables the kernel time discipline, if available. +The default for this flag is enable if support is available, otherwise disable. +.It Cm monitor +Enables the monitoring facility. +See the +.Xr ntpdc 8 . +program and the monlist command or further information. +The default for this flag is enable. +.It Cm ntp +Enables time and frequency discipline. +In effect, this switch opens and closes the feedback loop, +which is useful for testing. +The default for this flag is enable. +.It Cm pps +Enables the pulse-per-second (PPS) signal when frequency +and time is disciplined by the precision time kernel modifications. +See the +.Qq A Kernel Model for Precision Timekeeping +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) +page for further information. +The default for this flag is disable. +.It Cm stats +Enables the statistics facility. +See the +.Sx Monitoring Options +section of +.Xr ntp.conf 5 +for further information. +The default for this flag is disable. +.El +.It Xo Ic restrict Ar address Ar mask +.Ar flag Oo Ar ... Oc +.Xc +This command operates in the same way as the +.Ic restrict +configuration file commands of +.Xr ntpd 8 . +.It Xo Ic unrestrict Ar address Ar mask +.Ar flag Oo Ar ... Oc +.Xc +Unrestrict the matching entry from the restrict list. +.It Xo Ic delrestrict Ar address Ar mask +.Op Cm ntpport +.Xc +Delete the matching entry from the restrict list. +.It Ic readkeys +Causes the current set of authentication keys to be purged and +a new set to be obtained by rereading the keys file (which must +have been specified in the +.Xr ntpd 8 +configuration file). +This +allows encryption keys to be changed without restarting the +server. +.It Ic trustedkey Ar keyid Oo Ar ... Oc +.It Ic untrustedkey Ar keyid Oo Ar ... Oc +These commands operate in the same way as the +.Ic trustedkey +and +.Ic untrustedkey +configuration file +commands of +.Xr ntpd 8 . +.It Ic authinfo +Returns information concerning the authentication module, +including known keys and counts of encryptions and decryptions +which have been done. +.It Ic traps +Display the traps set in the server. +See the source listing for +further information. +.It Xo Ic addtrap Ar address +.Op Ar port +.Op Ar interface +.Xc +Set a trap for asynchronous messages. +See the source listing +for further information. +.It Xo Ic clrtrap Ar address +.Op Ar port +.Op Ar interface +.Xc +Clear a trap for asynchronous messages. +See the source listing +for further information. +.It Ic reset +Clear the statistics counters in various modules of the server. +See the source listing for further information. +.El +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh "SEE ALSO" +.Xr ntp.conf 5 , +.Xr ntpd 8 +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Sh AUTHORS +The formatting directives in this document came from FreeBSD. +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh BUGS +The +.Nm +utility is a crude hack. +Much of the information it shows is +deadly boring and could only be loved by its implementer. +The +program was designed so that new (and temporary) features were easy +to hack in, at great expense to the program's ease of use. +Despite +this, the program is occasionally useful. +.Pp +Please report bugs to http://bugs.ntp.org . +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpdc\fP +option definitions. diff --git a/ntpq/ntpq.1ntpqman b/ntpq/ntpq.1ntpqman new file mode 100644 index 000000000..442fb2551 --- /dev/null +++ b/ntpq/ntpq.1ntpqman @@ -0,0 +1,397 @@ +.TH ntpq 1ntpqman "22 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntpq-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:58:33 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpq-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntpq \- standard NTP query program +.SH SYNOPSIS +.B ntpq +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ host ...] +.SH DESCRIPTION +The +.B +utility program is used to query NTP servers which +implement the standard NTP mode 6 control message formats defined +in Appendix B of the NTPv3 specification RFC1305, requesting +information about current state and/or changes in that state. +The same formats are used in NTPv4, although some of the +variables have changed and new ones added. The description on this +page is for the NTPv4 variables. +The program may be run either in interactive mode or controlled using +command line arguments. +Requests to read and write arbitrary +variables can be assembled, with raw and pretty-printed output +options being available. +The +.B +utility can also obtain and print a +list of peers in a common format by sending multiple queries to the +server. +If one or more request options is included on the command line +when +.B +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.B +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.B +utility will prompt for +commands if the standard input is a terminal device. +.B +uses NTP mode 6 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.B +utility makes +one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +Specifying a +command line option other than +i +or +n +will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. +Otherwise, +.B +will attempt to read +interactive format commands from the standard input. +.Ss "Internal Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +A +number of interactive format commands are executed entirely within +the +.B +utility itself and do not result in NTP mode 6 +requests being sent to a server. +These are described following. +.TP +.BR Ic ? Op Ar command_keyword +.TP +.BR Ic help Op Ar command_keyword +A +.Ql \&? +by itself will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Ql \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Nm +than this manual +page. +.TP +.BR Ic addvars Ar variable_name Xo Op Ic =value +.Ic ... +.Xc +.TP +.BR Ic rmvars Ar variable_name Ic ... +.TP +.BR Ic clearvars +The data carried by NTP mode 6 messages consists of a list of +items of the form +.Ql variable_name=value , +where the +.Ql =value +is ignored, and can be omitted, +in requests to the server to read variables. +The +.Nm +utility maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +.Ic readlist +and +.Ic writelist +commands described below. +The +.Ic addvars +command allows variables and their optional values to be added to +the list. +If more than one variable is to be added, the list should +be comma-separated and not contain white space. +The +.Ic rmvars +command can be used to remove individual variables from the list, +while the +.Ic clearlist +command removes all variables from the +list. +.TP +.BR Ic authenticate Op yes | no +Normally +.Nm +does not authenticate requests unless +they are write requests. +The command +.Ql authenticate yes +causes +.Nm +to send authentication with all requests it +makes. +Authenticated requests causes some servers to handle +requests slightly differently, and can occasionally melt the CPU in +fuzzballs if you turn authentication on before doing a +.Ic peer +display. +The command +.Ql authenticate +causes +.Nm +to display whether or not +.Nm +is currently autheinticating requests. +.TP +.BR Ic cooked +Causes output from query commands to be "cooked", so that +variables which are recognized by +.Nm +will have their +values reformatted for human consumption. +Variables which +.Nm +thinks should have a decodable value but didn't are +marked with a trailing +.Ql \&? . +.TP +.BR Xo +.Ic debug +.Oo +.Cm more | +.Cm less | +.Cm off +.Oc +.Xc +With no argument, displays the current debug level. +Otherwise, the debug level is changed to the indicated level. +.TP +.BR Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.TP +.BR Ic host Ar hostname +Set the host to which future queries will be sent. +\fIhostname\fR +may be either a host name or a numeric address. +.TP +.BR Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +n +switch. +.TP +.BR Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.TP +.BR Ic ntpversion Xo Oo +.Cm 1 | +.Cm 2 | +.Cm 3 | +.Cm 4 +.Oc +.Xc +Sets the NTP version number which +.Nm +claims in +packets. +Defaults to 3, and note that mode 6 control messages (and +modes, for that matter) didn't exist in NTP version 1. +There appear +to be no servers left which demand version 1. +With no argument, displays the current NTP version that will be used +when communicating with servers. +.TP +.BR Ic quit +Exit +.Nm +.TP +.BR Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.TP +.BR Ic raw +Causes all output from query commands is printed as received +from the remote server. +The only formating/interpretation done on +the data is to transform nonascii data into a printable (but barely +understandable) form. +.TP +.BR Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 5000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.SH "OPTIONS" +.TP +.BR \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.TP +.BR \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.TP +.BR \-c " \fIcmd\fP, " \-\-command "=" \fIcmd\fP +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.TP +.BR \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-p ", " -\-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +interactive. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +.TP +.BR \-i ", " -\-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, peers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.TP +.BR \-n ", " -\-numeric +numeric host addresses. +.sp +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.TP +.BR \-\-old\-rv +Always output status line with readvar. +.sp +By default, ntpq now suppresses the associd=... line that +precedes the output of "readvar" (alias "rv") when a single +variable is requested, such as ntpq -c "rv 0 offset". This +option causes ntpq to include both lines of output for a +single-variable readvar. Using an environment variable to +preset this option in a script will enable both older and +newer ntpq to behave identically in this regard. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPQ_\fP or \fBNTPQ\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpq\fP +option definitions. diff --git a/ntpq/ntpq.1ntpqmdoc b/ntpq/ntpq.1ntpqmdoc new file mode 100644 index 000000000..dfc2e1bcc --- /dev/null +++ b/ntpq/ntpq.1ntpqmdoc @@ -0,0 +1,375 @@ +.Dd June 22 2011 +.Dt NTPQ 1ntpqmdoc User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntpq-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:58:38 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpq-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpq +.Nd standard NTP query program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +[ host ...] +.Pp +.Sh DESCRIPTION +The +.Nm +utility program is used to query NTP servers which +implement the standard NTP mode 6 control message formats defined +in Appendix B of the NTPv3 specification RFC1305, requesting +information about current state and/or changes in that state. +The same formats are used in NTPv4, although some of the +variables have changed and new ones added. The description on this +page is for the NTPv4 variables. +The program may be run either in interactive mode or controlled using +command line arguments. +Requests to read and write arbitrary +variables can be assembled, with raw and pretty-printed output +options being available. +The +.Nm +utility can also obtain and print a +list of peers in a common format by sending multiple queries to the +server. +If one or more request options is included on the command line +when +.Nm +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.Nm +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.Nm +utility will prompt for +commands if the standard input is a terminal device. +.Nm +uses NTP mode 6 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.Nm +utility makes +one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +Specifying a +command line option other than +.Fl i +or +.Fl n +will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. +Otherwise, +.Nm +will attempt to read +interactive format commands from the standard input. +.Ss "Internal Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +A +number of interactive format commands are executed entirely within +the +.Nm +utility itself and do not result in NTP mode 6 +requests being sent to a server. +These are described following. +.Bl -tag -width "? [command_keyword]" -compact -offset indent +.It Ic ? Op Ar command_keyword +.It Ic help Op Ar command_keyword +A +.Ql \&? +by itself will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Ql \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Nm +than this manual +page. +.It Ic addvars Ar variable_name Xo Op Ic =value +.Ic ... +.Xc +.It Ic rmvars Ar variable_name Ic ... +.It Ic clearvars +The data carried by NTP mode 6 messages consists of a list of +items of the form +.Ql variable_name=value , +where the +.Ql =value +is ignored, and can be omitted, +in requests to the server to read variables. +The +.Nm +utility maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +.Ic readlist +and +.Ic writelist +commands described below. +The +.Ic addvars +command allows variables and their optional values to be added to +the list. +If more than one variable is to be added, the list should +be comma-separated and not contain white space. +The +.Ic rmvars +command can be used to remove individual variables from the list, +while the +.Ic clearlist +command removes all variables from the +list. +.It Ic authenticate Op yes | no +Normally +.Nm +does not authenticate requests unless +they are write requests. +The command +.Ql authenticate yes +causes +.Nm +to send authentication with all requests it +makes. +Authenticated requests causes some servers to handle +requests slightly differently, and can occasionally melt the CPU in +fuzzballs if you turn authentication on before doing a +.Ic peer +display. +The command +.Ql authenticate +causes +.Nm +to display whether or not +.Nm +is currently autheinticating requests. +.It Ic cooked +Causes output from query commands to be "cooked", so that +variables which are recognized by +.Nm +will have their +values reformatted for human consumption. +Variables which +.Nm +thinks should have a decodable value but didn't are +marked with a trailing +.Ql \&? . +.It Xo +.Ic debug +.Oo +.Cm more | +.Cm less | +.Cm off +.Oc +.Xc +With no argument, displays the current debug level. +Otherwise, the debug level is changed to the indicated level. +.It Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.It Ic host Ar hostname +Set the host to which future queries will be sent. +.Ar hostname +may be either a host name or a numeric address. +.It Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +.Fl n +switch. +.It Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.It Ic ntpversion Xo Oo +.Cm 1 | +.Cm 2 | +.Cm 3 | +.Cm 4 +.Oc +.Xc +Sets the NTP version number which +.Nm +claims in +packets. +Defaults to 3, and note that mode 6 control messages (and +modes, for that matter) didn't exist in NTP version 1. +There appear +to be no servers left which demand version 1. +With no argument, displays the current NTP version that will be used +when communicating with servers. +.It Ic quit +Exit +.Nm +.It Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.It Ic raw +Causes all output from query commands is printed as received +from the remote server. +The only formating/interpretation done on +the data is to transform nonascii data into a printable (but barely +understandable) form. +.It Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 5000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.El +.Sh "OPTIONS" +.Bl -tag +.It \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.It \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.It \-c " \fIcmd\fP, " \-\-command "=" \fIcmd\fP +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.It \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-p ", " -\-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +interactive. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +.It \-i ", " -\-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, peers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.It \-n ", " -\-numeric +numeric host addresses. +.sp +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.It \-\-old\-rv +Always output status line with readvar. +.sp +By default, ntpq now suppresses the associd=... line that +precedes the output of "readvar" (alias "rv") when a single +variable is requested, such as ntpq -c "rv 0 offset". This +option causes ntpq to include both lines of output for a +single-variable readvar. Using an environment variable to +preset this option in a script will enable both older and +newer ntpq to behave identically in this regard. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPQ_\fP or \fBNTPQ\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpq\fP +option definitions. diff --git a/ntpq/ntpq.man.in b/ntpq/ntpq.man.in new file mode 100644 index 000000000..cec4bd978 --- /dev/null +++ b/ntpq/ntpq.man.in @@ -0,0 +1,397 @@ +.TH ntpq @NTPQ_MS@ "22 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntpq-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:58:33 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpq-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntpq \- standard NTP query program +.SH SYNOPSIS +.B ntpq +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ host ...] +.SH DESCRIPTION +The +.B +utility program is used to query NTP servers which +implement the standard NTP mode 6 control message formats defined +in Appendix B of the NTPv3 specification RFC1305, requesting +information about current state and/or changes in that state. +The same formats are used in NTPv4, although some of the +variables have changed and new ones added. The description on this +page is for the NTPv4 variables. +The program may be run either in interactive mode or controlled using +command line arguments. +Requests to read and write arbitrary +variables can be assembled, with raw and pretty-printed output +options being available. +The +.B +utility can also obtain and print a +list of peers in a common format by sending multiple queries to the +server. +If one or more request options is included on the command line +when +.B +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.B +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.B +utility will prompt for +commands if the standard input is a terminal device. +.B +uses NTP mode 6 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.B +utility makes +one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +Specifying a +command line option other than +i +or +n +will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. +Otherwise, +.B +will attempt to read +interactive format commands from the standard input. +.Ss "Internal Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +A +number of interactive format commands are executed entirely within +the +.B +utility itself and do not result in NTP mode 6 +requests being sent to a server. +These are described following. +.TP +.BR Ic ? Op Ar command_keyword +.TP +.BR Ic help Op Ar command_keyword +A +.Ql \&? +by itself will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Ql \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Nm +than this manual +page. +.TP +.BR Ic addvars Ar variable_name Xo Op Ic =value +.Ic ... +.Xc +.TP +.BR Ic rmvars Ar variable_name Ic ... +.TP +.BR Ic clearvars +The data carried by NTP mode 6 messages consists of a list of +items of the form +.Ql variable_name=value , +where the +.Ql =value +is ignored, and can be omitted, +in requests to the server to read variables. +The +.Nm +utility maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +.Ic readlist +and +.Ic writelist +commands described below. +The +.Ic addvars +command allows variables and their optional values to be added to +the list. +If more than one variable is to be added, the list should +be comma-separated and not contain white space. +The +.Ic rmvars +command can be used to remove individual variables from the list, +while the +.Ic clearlist +command removes all variables from the +list. +.TP +.BR Ic authenticate Op yes | no +Normally +.Nm +does not authenticate requests unless +they are write requests. +The command +.Ql authenticate yes +causes +.Nm +to send authentication with all requests it +makes. +Authenticated requests causes some servers to handle +requests slightly differently, and can occasionally melt the CPU in +fuzzballs if you turn authentication on before doing a +.Ic peer +display. +The command +.Ql authenticate +causes +.Nm +to display whether or not +.Nm +is currently autheinticating requests. +.TP +.BR Ic cooked +Causes output from query commands to be "cooked", so that +variables which are recognized by +.Nm +will have their +values reformatted for human consumption. +Variables which +.Nm +thinks should have a decodable value but didn't are +marked with a trailing +.Ql \&? . +.TP +.BR Xo +.Ic debug +.Oo +.Cm more | +.Cm less | +.Cm off +.Oc +.Xc +With no argument, displays the current debug level. +Otherwise, the debug level is changed to the indicated level. +.TP +.BR Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.TP +.BR Ic host Ar hostname +Set the host to which future queries will be sent. +\fIhostname\fR +may be either a host name or a numeric address. +.TP +.BR Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +n +switch. +.TP +.BR Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.TP +.BR Ic ntpversion Xo Oo +.Cm 1 | +.Cm 2 | +.Cm 3 | +.Cm 4 +.Oc +.Xc +Sets the NTP version number which +.Nm +claims in +packets. +Defaults to 3, and note that mode 6 control messages (and +modes, for that matter) didn't exist in NTP version 1. +There appear +to be no servers left which demand version 1. +With no argument, displays the current NTP version that will be used +when communicating with servers. +.TP +.BR Ic quit +Exit +.Nm +.TP +.BR Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.TP +.BR Ic raw +Causes all output from query commands is printed as received +from the remote server. +The only formating/interpretation done on +the data is to transform nonascii data into a printable (but barely +understandable) form. +.TP +.BR Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 5000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.SH "OPTIONS" +.TP +.BR \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.TP +.BR \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.TP +.BR \-c " \fIcmd\fP, " \-\-command "=" \fIcmd\fP +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.TP +.BR \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-p ", " -\-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +interactive. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +.TP +.BR \-i ", " -\-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, peers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.TP +.BR \-n ", " -\-numeric +numeric host addresses. +.sp +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.TP +.BR \-\-old\-rv +Always output status line with readvar. +.sp +By default, ntpq now suppresses the associd=... line that +precedes the output of "readvar" (alias "rv") when a single +variable is requested, such as ntpq -c "rv 0 offset". This +option causes ntpq to include both lines of output for a +single-variable readvar. Using an environment variable to +preset this option in a script will enable both older and +newer ntpq to behave identically in this regard. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPQ_\fP or \fBNTPQ\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpq\fP +option definitions. diff --git a/ntpq/ntpq.mdoc.in b/ntpq/ntpq.mdoc.in new file mode 100644 index 000000000..96355c895 --- /dev/null +++ b/ntpq/ntpq.mdoc.in @@ -0,0 +1,375 @@ +.Dd June 22 2011 +.Dt NTPQ @NTPQ_MS@ User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntpq-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:58:38 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpq-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpq +.Nd standard NTP query program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +[ host ...] +.Pp +.Sh DESCRIPTION +The +.Nm +utility program is used to query NTP servers which +implement the standard NTP mode 6 control message formats defined +in Appendix B of the NTPv3 specification RFC1305, requesting +information about current state and/or changes in that state. +The same formats are used in NTPv4, although some of the +variables have changed and new ones added. The description on this +page is for the NTPv4 variables. +The program may be run either in interactive mode or controlled using +command line arguments. +Requests to read and write arbitrary +variables can be assembled, with raw and pretty-printed output +options being available. +The +.Nm +utility can also obtain and print a +list of peers in a common format by sending multiple queries to the +server. +If one or more request options is included on the command line +when +.Nm +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.Nm +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.Nm +utility will prompt for +commands if the standard input is a terminal device. +.Nm +uses NTP mode 6 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.Nm +utility makes +one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +Specifying a +command line option other than +.Fl i +or +.Fl n +will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. +Otherwise, +.Nm +will attempt to read +interactive format commands from the standard input. +.Ss "Internal Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +A +number of interactive format commands are executed entirely within +the +.Nm +utility itself and do not result in NTP mode 6 +requests being sent to a server. +These are described following. +.Bl -tag -width "? [command_keyword]" -compact -offset indent +.It Ic ? Op Ar command_keyword +.It Ic help Op Ar command_keyword +A +.Ql \&? +by itself will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Ql \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Nm +than this manual +page. +.It Ic addvars Ar variable_name Xo Op Ic =value +.Ic ... +.Xc +.It Ic rmvars Ar variable_name Ic ... +.It Ic clearvars +The data carried by NTP mode 6 messages consists of a list of +items of the form +.Ql variable_name=value , +where the +.Ql =value +is ignored, and can be omitted, +in requests to the server to read variables. +The +.Nm +utility maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +.Ic readlist +and +.Ic writelist +commands described below. +The +.Ic addvars +command allows variables and their optional values to be added to +the list. +If more than one variable is to be added, the list should +be comma-separated and not contain white space. +The +.Ic rmvars +command can be used to remove individual variables from the list, +while the +.Ic clearlist +command removes all variables from the +list. +.It Ic authenticate Op yes | no +Normally +.Nm +does not authenticate requests unless +they are write requests. +The command +.Ql authenticate yes +causes +.Nm +to send authentication with all requests it +makes. +Authenticated requests causes some servers to handle +requests slightly differently, and can occasionally melt the CPU in +fuzzballs if you turn authentication on before doing a +.Ic peer +display. +The command +.Ql authenticate +causes +.Nm +to display whether or not +.Nm +is currently autheinticating requests. +.It Ic cooked +Causes output from query commands to be "cooked", so that +variables which are recognized by +.Nm +will have their +values reformatted for human consumption. +Variables which +.Nm +thinks should have a decodable value but didn't are +marked with a trailing +.Ql \&? . +.It Xo +.Ic debug +.Oo +.Cm more | +.Cm less | +.Cm off +.Oc +.Xc +With no argument, displays the current debug level. +Otherwise, the debug level is changed to the indicated level. +.It Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.It Ic host Ar hostname +Set the host to which future queries will be sent. +.Ar hostname +may be either a host name or a numeric address. +.It Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +.Fl n +switch. +.It Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.It Ic ntpversion Xo Oo +.Cm 1 | +.Cm 2 | +.Cm 3 | +.Cm 4 +.Oc +.Xc +Sets the NTP version number which +.Nm +claims in +packets. +Defaults to 3, and note that mode 6 control messages (and +modes, for that matter) didn't exist in NTP version 1. +There appear +to be no servers left which demand version 1. +With no argument, displays the current NTP version that will be used +when communicating with servers. +.It Ic quit +Exit +.Nm +.It Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.It Ic raw +Causes all output from query commands is printed as received +from the remote server. +The only formating/interpretation done on +the data is to transform nonascii data into a printable (but barely +understandable) form. +.It Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 5000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.El +.Sh "OPTIONS" +.Bl -tag +.It \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.It \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.It \-c " \fIcmd\fP, " \-\-command "=" \fIcmd\fP +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.It \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-p ", " -\-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +interactive. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +.It \-i ", " -\-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, peers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.It \-n ", " -\-numeric +numeric host addresses. +.sp +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.It \-\-old\-rv +Always output status line with readvar. +.sp +By default, ntpq now suppresses the associd=... line that +precedes the output of "readvar" (alias "rv") when a single +variable is requested, such as ntpq -c "rv 0 offset". This +option causes ntpq to include both lines of output for a +single-variable readvar. Using an environment variable to +preset this option in a script will enable both older and +newer ntpq to behave identically in this regard. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPQ_\fP or \fBNTPQ\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpq\fP +option definitions. diff --git a/ntpsnmpd/ntpsnmpd.1ntpsnmpdman b/ntpsnmpd/ntpsnmpd.1ntpsnmpdman new file mode 100644 index 000000000..e6274fae0 --- /dev/null +++ b/ntpsnmpd/ntpsnmpd.1ntpsnmpdman @@ -0,0 +1,92 @@ +.TH ntpsnmpd 1ntpsnmpdman "22 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntpsnmpd-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:59:33 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpsnmpd-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntpsnmpd \- NTP SNMP MIB agent +.SH SYNOPSIS +.B ntpsnmpd +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." +.PP +All arguments must be options. +.PP +.SH DESCRIPTION +.SH "OPTIONS" +.TP +.BR \-n ", " -\-nofork +Do not fork. +.sp +.TP +.BR \-p ", " -\-syslog +Log to syslog(). +.sp +.TP +.BR \-\-agentxsocket "=\fIstring\fP" +The socket address ntpsnmpd uses to connect to net-snmpd. +The default \fIstring\fP for this option is: +.ti +4 + unix:/var/agentx/master +.sp +[:] +The default is the Unix Domain socket "unix:/var/agentx/master". Another common alternative is tcp:localhost:705. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPSNMPD_\fP or \fBNTPSNMPD\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH AUTHORS +.An "Heiko Gerstung" +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpsnmpd\fP +option definitions. diff --git a/ntpsnmpd/ntpsnmpd.1ntpsnmpdmdoc b/ntpsnmpd/ntpsnmpd.1ntpsnmpdmdoc new file mode 100644 index 000000000..9efd1bab7 --- /dev/null +++ b/ntpsnmpd/ntpsnmpd.1ntpsnmpdmdoc @@ -0,0 +1,89 @@ +.Dd June 22 2011 +.Dt NTPSNMPD 1ntpsnmpdmdoc User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntpsnmpd-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:59:38 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpsnmpd-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpsnmpd +.Nd NTP SNMP MIB agent +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +.Pp +All arguments must be options. +.Pp +.Sh DESCRIPTION +.Sh "OPTIONS" +.Bl -tag +.It \-n ", " -\-nofork +Do not fork. +.sp +.It \-p ", " -\-syslog +Log to syslog(). +.sp +.It \-\-agentxsocket "=\fIstring\fP" +The socket address ntpsnmpd uses to connect to net-snmpd. +The default \fIstring\fP for this option is: +.ti +4 + unix:/var/agentx/master +.sp +[:] +The default is the Unix Domain socket "unix:/var/agentx/master". Another common alternative is tcp:localhost:705. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPSNMPD_\fP or \fBNTPSNMPD\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh AUTHORS +.An "Heiko Gerstung" +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpsnmpd\fP +option definitions. diff --git a/ntpsnmpd/ntpsnmpd.man.in b/ntpsnmpd/ntpsnmpd.man.in new file mode 100644 index 000000000..d0d80d719 --- /dev/null +++ b/ntpsnmpd/ntpsnmpd.man.in @@ -0,0 +1,92 @@ +.TH ntpsnmpd @NTPSNMPD_MS@ "22 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntpsnmpd-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:59:33 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpsnmpd-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntpsnmpd \- NTP SNMP MIB agent +.SH SYNOPSIS +.B ntpsnmpd +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." +.PP +All arguments must be options. +.PP +.SH DESCRIPTION +.SH "OPTIONS" +.TP +.BR \-n ", " -\-nofork +Do not fork. +.sp +.TP +.BR \-p ", " -\-syslog +Log to syslog(). +.sp +.TP +.BR \-\-agentxsocket "=\fIstring\fP" +The socket address ntpsnmpd uses to connect to net-snmpd. +The default \fIstring\fP for this option is: +.ti +4 + unix:/var/agentx/master +.sp +[:] +The default is the Unix Domain socket "unix:/var/agentx/master". Another common alternative is tcp:localhost:705. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPSNMPD_\fP or \fBNTPSNMPD\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH AUTHORS +.An "Heiko Gerstung" +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpsnmpd\fP +option definitions. diff --git a/ntpsnmpd/ntpsnmpd.mdoc.in b/ntpsnmpd/ntpsnmpd.mdoc.in new file mode 100644 index 000000000..ef1f13e8a --- /dev/null +++ b/ntpsnmpd/ntpsnmpd.mdoc.in @@ -0,0 +1,89 @@ +.Dd June 22 2011 +.Dt NTPSNMPD @NTPSNMPD_MS@ User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntpsnmpd-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:59:38 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntpsnmpd-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpsnmpd +.Nd NTP SNMP MIB agent +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +.Pp +All arguments must be options. +.Pp +.Sh DESCRIPTION +.Sh "OPTIONS" +.Bl -tag +.It \-n ", " -\-nofork +Do not fork. +.sp +.It \-p ", " -\-syslog +Log to syslog(). +.sp +.It \-\-agentxsocket "=\fIstring\fP" +The socket address ntpsnmpd uses to connect to net-snmpd. +The default \fIstring\fP for this option is: +.ti +4 + unix:/var/agentx/master +.sp +[:] +The default is the Unix Domain socket "unix:/var/agentx/master". Another common alternative is tcp:localhost:705. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPSNMPD_\fP or \fBNTPSNMPD\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh AUTHORS +.An "Heiko Gerstung" +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntpsnmpd\fP +option definitions. diff --git a/scripts/ntp-wait.1ntp-waitman b/scripts/ntp-wait.1ntp-waitman new file mode 100644 index 000000000..46b2b580b --- /dev/null +++ b/scripts/ntp-wait.1ntp-waitman @@ -0,0 +1,93 @@ +.TH ntp-wait 1ntp-waitman "22 Jun 2011" "ntp (4.2.7p184)" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntp-wait-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:28:02 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-wait-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntp-wait \- Wait for ntpd to stabilize the system clock +.SH SYNOPSIS +.B ntp-wait +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." +.PP +All arguments must be options. +.PP +.SH DESCRIPTION +.B will send at most +\fInum-tries\fR +queries to +.Xr ntpd 8 +(sleeping for +\fIsecs-between-tries\fR +after each status return that says +.Xr ntpd 8 +has not yet produced a synchronized and stable system clock). +.PP +.B will +will do this quietly, unless the +v +flag is provided. +.SH "OPTIONS" +.TP +.BR \-n " \fInum\-tries\fP, " \-\- "=" \fInum\-tries\fP +Number of times to check ntpd. +This option takes an integer number as its argument. +.sp +The maximum number of times we will check ntpd to see if it +has been able to synchronize and stabilize the system clock. +The default is 100 times. +.TP +.BR \-s " \fIsecs\-between\-tries\fP, " \-\- "=" \fIsecs\-between\-tries\fP +How long to sleep between tries. +This option takes an integer number as its argument. +.sp +We will sleep for secs-between-tries after each query of ntpd +that returns "the time is not yet stable". +The default is 6 seconds. +.TP +.BR \-v ", " -\- +Be verbose. +.sp +By default, ntp-wait is silent. With this option, ntp-wait +will provide status information. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTP_WAIT_\fP or \fBNTP_WAIT\fP +.fi +.ad +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH AUTHORS +.An "Harlan Stenn" +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntp-wait\fP +option definitions. diff --git a/scripts/ntp-wait.1ntp-waitmdoc b/scripts/ntp-wait.1ntp-waitmdoc new file mode 100644 index 000000000..ea14a7040 --- /dev/null +++ b/scripts/ntp-wait.1ntp-waitmdoc @@ -0,0 +1,92 @@ +.Dd June 22 2011 +.Dt NTP_WAIT 1ntp-waitmdoc User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntp-wait-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:43:04 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-wait-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntp-wait +.Nd Wait for ntpd to stabilize the system clock +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +.Pp +All arguments must be options. +.Pp +.Sh DESCRIPTION +.Nm will send at most +.Ar num-tries +queries to +.Xr ntpd 8 +(sleeping for +.Ar secs-between-tries +after each status return that says +.Xr ntpd 8 +has not yet produced a synchronized and stable system clock). +.Pp +.Nm +will do this quietly, unless the +.Fl v +flag is provided. +.Sh "OPTIONS" +.Bl -tag +.It \-n " \fInum\-tries\fP, " \-\- "=" \fInum\-tries\fP +Number of times to check ntpd. +This option takes an integer number as its argument. +.sp +The maximum number of times we will check ntpd to see if it +has been able to synchronize and stabilize the system clock. +The default is 100 times. +.It \-s " \fIsecs\-between\-tries\fP, " \-\- "=" \fIsecs\-between\-tries\fP +How long to sleep between tries. +This option takes an integer number as its argument. +.sp +We will sleep for secs-between-tries after each query of ntpd +that returns "the time is not yet stable". +The default is 6 seconds. +.It \-v ", " -\- +Be verbose. +.sp +By default, ntp-wait is silent. With this option, ntp-wait +will provide status information. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTP_WAIT_\fP or \fBNTP_WAIT\fP +.fi +.ad +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh AUTHORS +.An "Harlan Stenn" +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntp-wait\fP +option definitions. diff --git a/scripts/ntp-wait.man.in b/scripts/ntp-wait.man.in new file mode 100644 index 000000000..f36948197 --- /dev/null +++ b/scripts/ntp-wait.man.in @@ -0,0 +1,93 @@ +.TH ntp-wait @NTP_WAIT_MS@ "22 Jun 2011" "ntp (4.2.7p184)" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntp-wait-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:28:02 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-wait-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntp-wait \- Wait for ntpd to stabilize the system clock +.SH SYNOPSIS +.B ntp-wait +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." +.PP +All arguments must be options. +.PP +.SH DESCRIPTION +.B will send at most +\fInum-tries\fR +queries to +.Xr ntpd 8 +(sleeping for +\fIsecs-between-tries\fR +after each status return that says +.Xr ntpd 8 +has not yet produced a synchronized and stable system clock). +.PP +.B will +will do this quietly, unless the +v +flag is provided. +.SH "OPTIONS" +.TP +.BR \-n " \fInum\-tries\fP, " \-\- "=" \fInum\-tries\fP +Number of times to check ntpd. +This option takes an integer number as its argument. +.sp +The maximum number of times we will check ntpd to see if it +has been able to synchronize and stabilize the system clock. +The default is 100 times. +.TP +.BR \-s " \fIsecs\-between\-tries\fP, " \-\- "=" \fIsecs\-between\-tries\fP +How long to sleep between tries. +This option takes an integer number as its argument. +.sp +We will sleep for secs-between-tries after each query of ntpd +that returns "the time is not yet stable". +The default is 6 seconds. +.TP +.BR \-v ", " -\- +Be verbose. +.sp +By default, ntp-wait is silent. With this option, ntp-wait +will provide status information. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTP_WAIT_\fP or \fBNTP_WAIT\fP +.fi +.ad +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH AUTHORS +.An "Harlan Stenn" +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntp-wait\fP +option definitions. diff --git a/scripts/ntp-wait.mdoc.in b/scripts/ntp-wait.mdoc.in new file mode 100644 index 000000000..98f274cc1 --- /dev/null +++ b/scripts/ntp-wait.mdoc.in @@ -0,0 +1,92 @@ +.Dd June 22 2011 +.Dt NTP_WAIT @NTP_WAIT_MS@ User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntp-wait-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 04:43:04 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-wait-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntp-wait +.Nd Wait for ntpd to stabilize the system clock +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +.Pp +All arguments must be options. +.Pp +.Sh DESCRIPTION +.Nm will send at most +.Ar num-tries +queries to +.Xr ntpd 8 +(sleeping for +.Ar secs-between-tries +after each status return that says +.Xr ntpd 8 +has not yet produced a synchronized and stable system clock). +.Pp +.Nm +will do this quietly, unless the +.Fl v +flag is provided. +.Sh "OPTIONS" +.Bl -tag +.It \-n " \fInum\-tries\fP, " \-\- "=" \fInum\-tries\fP +Number of times to check ntpd. +This option takes an integer number as its argument. +.sp +The maximum number of times we will check ntpd to see if it +has been able to synchronize and stabilize the system clock. +The default is 100 times. +.It \-s " \fIsecs\-between\-tries\fP, " \-\- "=" \fIsecs\-between\-tries\fP +How long to sleep between tries. +This option takes an integer number as its argument. +.sp +We will sleep for secs-between-tries after each query of ntpd +that returns "the time is not yet stable". +The default is 6 seconds. +.It \-v ", " -\- +Be verbose. +.sp +By default, ntp-wait is silent. With this option, ntp-wait +will provide status information. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTP_WAIT_\fP or \fBNTP_WAIT\fP +.fi +.ad +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh AUTHORS +.An "Harlan Stenn" +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntp-wait\fP +option definitions. diff --git a/sntp/include/mansec2subst.sed b/sntp/include/mansec2subst.sed new file mode 100644 index 000000000..5ea8a06ac --- /dev/null +++ b/sntp/include/mansec2subst.sed @@ -0,0 +1,26 @@ +s/1ntp-keygenman/@NTP_KEYGEN_MS@/g +s/1ntp-keygenmdoc/@NTP_KEYGEN_MS@/g +s/1ntp-waitman/@NTP_WAIT_MS@/g +s/1ntp-waitmdoc/@NTP_WAIT_MS@/g +s/1ntpdateman/@NTPDATE_MS@/g +s/1ntpdatemdoc/@NTPDATE_MS@/g +s/1ntpdcman/@NTPDC_MS@/g +s/1ntpdcmdoc/@NTPDC_MS@/g +s/1ntpdman/@NTPD_MS@/g +s/1ntpdmdoc/@NTPD_MS@/g +s/1ntpdsimman/@NTPDSIM_MS@/g +s/1ntpdsimmdoc/@NTPDSIM_MS@/g +s/1ntpqman/@NTPQ_MS@/g +s/1ntpqmdoc/@NTPQ_MS@/g +s/1ntpsnmpdman/@NTPSNMPD_MS@/g +s/1ntpsnmpdmdoc/@NTPSNMPD_MS@/g +s/1ntptimeman/@NTPTIME_MS@/g +s/1ntptimemdoc/@NTPTIME_MS@/g +s/1ntptraceman/@NTPTRACE_MS@/g +s/1ntptracemdoc/@NTPTRACE_MS@/g +s/1sntpman/@SNTP_MS@/g +s/1sntpmdoc/@SNTP_MS@/g +s/1tickadjman/@TICKADJ_MS@/g +s/1tickadjmdoc/@TICKADJ_MS@/g +s/1timetrimman/@TIMETRIM_MS@/g +s/1timetrimmdoc/@TIMETRIM_MS@/g diff --git a/sntp/sntp.1sntpman b/sntp/sntp.1sntpman new file mode 100644 index 000000000..5c8d2f0fe --- /dev/null +++ b/sntp/sntp.1sntpman @@ -0,0 +1,293 @@ +.TH sntp 1sntpman "21 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (sntp-opts.man) +.\" +.\" It has been AutoGen-ed June 21, 2011 at 03:45:41 AM by AutoGen 5.11.10pre10 +.\" From the definitions sntp-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +sntp \- standard Simple Network Time Protocol program +.SH SYNOPSIS +.B sntp +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ hostname-or-IP ...] +.PP +.SH DESCRIPTION +.B +can be used as a SNTP client to query a NTP or SNTP server and either display +the time or set the local system's time (given suitable privilege). It can be +run as an interactive command or in a +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.PP +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +and the +.Ic "'+4.567 +/- 0.089 secs'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct), +and the date/time of +'1996-10-15 20:17:25.123' +is believed to be correct to within ++/- 0.089 +seconds. +.SH "OPTIONS" +.TP +.BR \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of the following host names on the command line +to the IPv4 namespace. +.TP +.BR \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of the following host names on the command line +to the IPv6 namespace. +.TP +.BR \-a " \fIauth\-keynumber\fP, " \-\-authentication "=" \fIauth\-keynumber\fP +Enable authentication with the key auth-keynumber. +This option takes an integer number as its argument. +.sp +This option enables authentication using the key specified in this +option's argument. The argument of this option is the keyid, a +number specified in the keyfile as this key's identifier. See the +keyfile option (-k) for more details. +.TP +.BR \-B " \fIseconds\fP, " \-\-bctimeout "=" \fIseconds\fP +The number of seconds to wait for broadcasts. +This option takes an integer number as its argument. +The default \fIseconds\fP for this option is: +.ti +4 + 68 +.sp +When waiting for a broadcast packet SNTP will wait the number +of seconds specified before giving up. Default 68 seconds. +.TP +.BR \-b " \fIbroadcast\-address\fP, " \-\-broadcast "=" \fIbroadcast\-address\fP +Listen to the address specified for broadcast time sync. +This option may appear an unlimited number of times. +.sp +If specified SNTP will listen to the specified address +for NTP broadcasts. The default maximum wait time, +68 seconds, can be modified with -B. +.TP +.BR \-c " \fIhost\-name\fP, " \-\-concurrent "=" \fIhost\-name\fP +Concurrently query all IPs returned for host-name. +This option may appear an unlimited number of times. +.sp +Requests from an NTP "client" to a "server" should never be sent +more rapidly than one every 2 seconds. By default, any IPs returned +as part of a DNS lookup are assumed to be for a single instance of +ntpd, and therefore sntp will send queries to these IPs one after +another, with a 2-second gap in between each query. +The -c or --concurrent flag says that any IPs returned for the DNS +lookup of the supplied host-name are on different machines, so we +can send concurrent queries. +.TP +.BR \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-h " \fImilliseconds\fP, " \-\-headspace "=" \fImilliseconds\fP +The gap (in milliseconds) between time requests. +This option takes an integer number as its argument. +The default \fImilliseconds\fP for this option is: +.ti +4 + 10 +.sp +Since we're only going to use the first valid response we get and +there is benefit to specifying a good number of servers to query, +separate the queries we send out by the specified number of +milliseconds. +Default 10 milliseconds. +.TP +.BR \-K " \fIfile\-name\fP, " \-\-kod "=" \fIfile\-name\fP +KoD history filename. +The default \fIfile\-name\fP for this option is: +.ti +4 + /var/db/ntp-kod +.sp +Specifies the filename to be used for the persistent history of KoD +responses received from servers. The default is +/var/db/ntp-kod . +.TP +.BR \-k " \fIfile\-name\fP, " \-\-keyfile "=" \fIfile\-name\fP +Look in this file for the key specified with -a. +.sp +This option specifies the keyfile. +SNTP will search for the key specified with -a keyno in this +file. Key files follow the following format: +keyid keytype key +Where keyid is a number identifying this key +keytype is one of the following: +S Key is a 64 Bit hexadecimal number as specified in in the DES specification. +N Key is a 64 Bit hexadecimal number as specified in the NTP standard. +A Key is a 1-to-8 character ASCII string. +M Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. +For more information see ntp.keys(5). +.TP +.BR \-l " \fIfile\-name\fP, " \-\-filelog "=" \fIfile\-name\fP +Log to specified logfile. +.sp +This option causes the client to write log messages to the specified +logfile. +.TP +.BR \-M " \fInumber\fP, " \-\-steplimit "=" \fInumber\fP +Adjustments less than steplimit msec will be slewed. +This option takes an integer number as its argument. +The value of \fInumber\fP is constrained to being: +.in +4 +.nf +.na +greater than or equal to 0 +.fi +.in -4 +.sp +If the time adjustment is less than steplimit milliseconds, slew the +amount using adjtime(). Otherwise, step the correction using +settimeofday(). +.TP +.BR \-o " \fInumber\fP, " \-\-ntpversion "=" \fInumber\fP +Send as our NTP version. +This option takes an integer number as its argument. +The value of \fInumber\fP is constrained to being: +.in +4 +.nf +.na +in the range 0 through 7 +.fi +.in -4 +The default \fInumber\fP for this option is: +.ti +4 + 4 +.sp +When sending requests to a remote server, tell them we are running +NTP protocol version . +.TP +.BR \-r ", " -\-usereservedport +Use the NTP Reserved Port (port 123). +.sp +Use port 123, which is reserved for NTP, for our network +communications. +.TP +.BR \-S ", " -\-step +OK to 'step' the time with settimeofday(). +.sp +.TP +.BR \-s ", " -\-slew +OK to 'slew' the time with adjtime(). +.sp +.TP +.BR \-u " \fIseconds\fP, " \-\-uctimeout "=" \fIseconds\fP +The number of seconds to wait for unicast responses. +This option takes an integer number as its argument. +The default \fIseconds\fP for this option is: +.ti +4 + 5 +.sp +When waiting for a unicast reply, SNTP will wait the number +of seconds specified before giving up. Default 5 seconds. +.TP +.BR \-\-wait, " \fB\-\-no\-wait\fP" +Wait for pending replies (if not setting the time). +The \fIno\-wait\fP form will disable the option. +This option is enabled by default. +.sp +If we are not setting the time, wait for all pending responses. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBSNTP_\fP or \fBSNTP\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", "\fI.\fP", "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH USAGE +.TP +.BR Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.TP +.BR Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate 1ntpdatemdoc , +or +.Xr rdate 8 +commands. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH BUGS +Please report bugs to http://bugs.ntp.org . +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP +option definitions. diff --git a/sntp/sntp.1sntpmdoc b/sntp/sntp.1sntpmdoc new file mode 100644 index 000000000..5bf45ae72 --- /dev/null +++ b/sntp/sntp.1sntpmdoc @@ -0,0 +1,275 @@ +.Dd June 21 2011 +.Dt SNTP 1sntpmdoc User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (sntp-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 21, 2011 at 03:45:42 AM by AutoGen 5.11.10pre10 +.\" From the definitions sntp-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm sntp +.Nd standard Simple Network Time Protocol program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +[ hostname-or-IP ...] +.Pp +.Sh DESCRIPTION +.Nm +can be used as a SNTP client to query a NTP or SNTP server and either display +the time or set the local system's time (given suitable privilege). It can be +run as an interactive command or in a +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.PP +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +and the +.Ic "'+4.567 +/- 0.089 secs'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct), +and the date/time of +'1996-10-15 20:17:25.123' +is believed to be correct to within ++/- 0.089 +seconds. +.Sh "OPTIONS" +.Bl -tag +.It \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of the following host names on the command line +to the IPv4 namespace. +.It \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of the following host names on the command line +to the IPv6 namespace. +.It \-a " \fIauth\-keynumber\fP, " \-\-authentication "=" \fIauth\-keynumber\fP +Enable authentication with the key auth-keynumber. +This option takes an integer number as its argument. +.sp +This option enables authentication using the key specified in this +option's argument. The argument of this option is the keyid, a +number specified in the keyfile as this key's identifier. See the +keyfile option (-k) for more details. +.It \-B " \fIseconds\fP, " \-\-bctimeout "=" \fIseconds\fP +The number of seconds to wait for broadcasts. +This option takes an integer number as its argument. +The default \fIseconds\fP for this option is: +.ti +4 + 68 +.sp +When waiting for a broadcast packet SNTP will wait the number +of seconds specified before giving up. Default 68 seconds. +.It \-b " \fIbroadcast\-address\fP, " \-\-broadcast "=" \fIbroadcast\-address\fP +Listen to the address specified for broadcast time sync. +This option may appear an unlimited number of times. +.sp +If specified SNTP will listen to the specified address +for NTP broadcasts. The default maximum wait time, +68 seconds, can be modified with -B. +.It \-c " \fIhost\-name\fP, " \-\-concurrent "=" \fIhost\-name\fP +Concurrently query all IPs returned for host-name. +This option may appear an unlimited number of times. +.sp +Requests from an NTP "client" to a "server" should never be sent +more rapidly than one every 2 seconds. By default, any IPs returned +as part of a DNS lookup are assumed to be for a single instance of +ntpd, and therefore sntp will send queries to these IPs one after +another, with a 2-second gap in between each query. +The -c or --concurrent flag says that any IPs returned for the DNS +lookup of the supplied host-name are on different machines, so we +can send concurrent queries. +.It \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-h " \fImilliseconds\fP, " \-\-headspace "=" \fImilliseconds\fP +The gap (in milliseconds) between time requests. +This option takes an integer number as its argument. +The default \fImilliseconds\fP for this option is: +.ti +4 + 10 +.sp +Since we're only going to use the first valid response we get and +there is benefit to specifying a good number of servers to query, +separate the queries we send out by the specified number of +milliseconds. +Default 10 milliseconds. +.It \-K " \fIfile\-name\fP, " \-\-kod "=" \fIfile\-name\fP +KoD history filename. +The default \fIfile\-name\fP for this option is: +.ti +4 + /var/db/ntp-kod +.sp +Specifies the filename to be used for the persistent history of KoD +responses received from servers. The default is +/var/db/ntp-kod . +.It \-k " \fIfile\-name\fP, " \-\-keyfile "=" \fIfile\-name\fP +Look in this file for the key specified with -a. +.sp +This option specifies the keyfile. +SNTP will search for the key specified with -a keyno in this +file. Key files follow the following format: +keyid keytype key +Where keyid is a number identifying this key +keytype is one of the following: +S Key is a 64 Bit hexadecimal number as specified in in the DES specification. +N Key is a 64 Bit hexadecimal number as specified in the NTP standard. +A Key is a 1-to-8 character ASCII string. +M Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. +For more information see ntp.keys(5). +.It \-l " \fIfile\-name\fP, " \-\-filelog "=" \fIfile\-name\fP +Log to specified logfile. +.sp +This option causes the client to write log messages to the specified +logfile. +.It \-M " \fInumber\fP, " \-\-steplimit "=" \fInumber\fP +Adjustments less than steplimit msec will be slewed. +This option takes an integer number as its argument. +The value of \fInumber\fP is constrained to being: +.in +4 +.nf +.na +greater than or equal to 0 +.fi +.in -4 +.sp +If the time adjustment is less than steplimit milliseconds, slew the +amount using adjtime(). Otherwise, step the correction using +settimeofday(). +.It \-o " \fInumber\fP, " \-\-ntpversion "=" \fInumber\fP +Send as our NTP version. +This option takes an integer number as its argument. +The value of \fInumber\fP is constrained to being: +.in +4 +.nf +.na +in the range 0 through 7 +.fi +.in -4 +The default \fInumber\fP for this option is: +.ti +4 + 4 +.sp +When sending requests to a remote server, tell them we are running +NTP protocol version . +.It \-r ", " -\-usereservedport +Use the NTP Reserved Port (port 123). +.sp +Use port 123, which is reserved for NTP, for our network +communications. +.It \-S ", " -\-step +OK to 'step' the time with settimeofday(). +.sp +.It \-s ", " -\-slew +OK to 'slew' the time with adjtime(). +.sp +.It \-u " \fIseconds\fP, " \-\-uctimeout "=" \fIseconds\fP +The number of seconds to wait for unicast responses. +This option takes an integer number as its argument. +The default \fIseconds\fP for this option is: +.ti +4 + 5 +.sp +When waiting for a unicast reply, SNTP will wait the number +of seconds specified before giving up. Default 5 seconds. +.It \-\-wait, " \fB\-\-no\-wait\fP" +Wait for pending replies (if not setting the time). +The \fIno\-wait\fP form will disable the option. +This option is enabled by default. +.sp +If we are not setting the time, wait for all pending responses. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBSNTP_\fP or \fBSNTP\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", "\fI.\fP", "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE +.Bl -tag -width indent +.It Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.It Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate 1ntpdatemdoc , +or +.Xr rdate 8 +commands. +.El +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh BUGS +Please report bugs to http://bugs.ntp.org . +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP +option definitions. diff --git a/sntp/sntp.man.in b/sntp/sntp.man.in new file mode 100644 index 000000000..16c7d2b89 --- /dev/null +++ b/sntp/sntp.man.in @@ -0,0 +1,293 @@ +.TH sntp @SNTP_MS@ "21 Jun 2011" "4.2.7p184" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (sntp-opts.man) +.\" +.\" It has been AutoGen-ed June 21, 2011 at 03:45:41 AM by AutoGen 5.11.10pre10 +.\" From the definitions sntp-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +sntp \- standard Simple Network Time Protocol program +.SH SYNOPSIS +.B sntp +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ hostname-or-IP ...] +.PP +.SH DESCRIPTION +.B +can be used as a SNTP client to query a NTP or SNTP server and either display +the time or set the local system's time (given suitable privilege). It can be +run as an interactive command or in a +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.PP +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +and the +.Ic "'+4.567 +/- 0.089 secs'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct), +and the date/time of +'1996-10-15 20:17:25.123' +is believed to be correct to within ++/- 0.089 +seconds. +.SH "OPTIONS" +.TP +.BR \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of the following host names on the command line +to the IPv4 namespace. +.TP +.BR \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of the following host names on the command line +to the IPv6 namespace. +.TP +.BR \-a " \fIauth\-keynumber\fP, " \-\-authentication "=" \fIauth\-keynumber\fP +Enable authentication with the key auth-keynumber. +This option takes an integer number as its argument. +.sp +This option enables authentication using the key specified in this +option's argument. The argument of this option is the keyid, a +number specified in the keyfile as this key's identifier. See the +keyfile option (-k) for more details. +.TP +.BR \-B " \fIseconds\fP, " \-\-bctimeout "=" \fIseconds\fP +The number of seconds to wait for broadcasts. +This option takes an integer number as its argument. +The default \fIseconds\fP for this option is: +.ti +4 + 68 +.sp +When waiting for a broadcast packet SNTP will wait the number +of seconds specified before giving up. Default 68 seconds. +.TP +.BR \-b " \fIbroadcast\-address\fP, " \-\-broadcast "=" \fIbroadcast\-address\fP +Listen to the address specified for broadcast time sync. +This option may appear an unlimited number of times. +.sp +If specified SNTP will listen to the specified address +for NTP broadcasts. The default maximum wait time, +68 seconds, can be modified with -B. +.TP +.BR \-c " \fIhost\-name\fP, " \-\-concurrent "=" \fIhost\-name\fP +Concurrently query all IPs returned for host-name. +This option may appear an unlimited number of times. +.sp +Requests from an NTP "client" to a "server" should never be sent +more rapidly than one every 2 seconds. By default, any IPs returned +as part of a DNS lookup are assumed to be for a single instance of +ntpd, and therefore sntp will send queries to these IPs one after +another, with a 2-second gap in between each query. +The -c or --concurrent flag says that any IPs returned for the DNS +lookup of the supplied host-name are on different machines, so we +can send concurrent queries. +.TP +.BR \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-h " \fImilliseconds\fP, " \-\-headspace "=" \fImilliseconds\fP +The gap (in milliseconds) between time requests. +This option takes an integer number as its argument. +The default \fImilliseconds\fP for this option is: +.ti +4 + 10 +.sp +Since we're only going to use the first valid response we get and +there is benefit to specifying a good number of servers to query, +separate the queries we send out by the specified number of +milliseconds. +Default 10 milliseconds. +.TP +.BR \-K " \fIfile\-name\fP, " \-\-kod "=" \fIfile\-name\fP +KoD history filename. +The default \fIfile\-name\fP for this option is: +.ti +4 + /var/db/ntp-kod +.sp +Specifies the filename to be used for the persistent history of KoD +responses received from servers. The default is +/var/db/ntp-kod . +.TP +.BR \-k " \fIfile\-name\fP, " \-\-keyfile "=" \fIfile\-name\fP +Look in this file for the key specified with -a. +.sp +This option specifies the keyfile. +SNTP will search for the key specified with -a keyno in this +file. Key files follow the following format: +keyid keytype key +Where keyid is a number identifying this key +keytype is one of the following: +S Key is a 64 Bit hexadecimal number as specified in in the DES specification. +N Key is a 64 Bit hexadecimal number as specified in the NTP standard. +A Key is a 1-to-8 character ASCII string. +M Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. +For more information see ntp.keys(5). +.TP +.BR \-l " \fIfile\-name\fP, " \-\-filelog "=" \fIfile\-name\fP +Log to specified logfile. +.sp +This option causes the client to write log messages to the specified +logfile. +.TP +.BR \-M " \fInumber\fP, " \-\-steplimit "=" \fInumber\fP +Adjustments less than steplimit msec will be slewed. +This option takes an integer number as its argument. +The value of \fInumber\fP is constrained to being: +.in +4 +.nf +.na +greater than or equal to 0 +.fi +.in -4 +.sp +If the time adjustment is less than steplimit milliseconds, slew the +amount using adjtime(). Otherwise, step the correction using +settimeofday(). +.TP +.BR \-o " \fInumber\fP, " \-\-ntpversion "=" \fInumber\fP +Send as our NTP version. +This option takes an integer number as its argument. +The value of \fInumber\fP is constrained to being: +.in +4 +.nf +.na +in the range 0 through 7 +.fi +.in -4 +The default \fInumber\fP for this option is: +.ti +4 + 4 +.sp +When sending requests to a remote server, tell them we are running +NTP protocol version . +.TP +.BR \-r ", " -\-usereservedport +Use the NTP Reserved Port (port 123). +.sp +Use port 123, which is reserved for NTP, for our network +communications. +.TP +.BR \-S ", " -\-step +OK to 'step' the time with settimeofday(). +.sp +.TP +.BR \-s ", " -\-slew +OK to 'slew' the time with adjtime(). +.sp +.TP +.BR \-u " \fIseconds\fP, " \-\-uctimeout "=" \fIseconds\fP +The number of seconds to wait for unicast responses. +This option takes an integer number as its argument. +The default \fIseconds\fP for this option is: +.ti +4 + 5 +.sp +When waiting for a unicast reply, SNTP will wait the number +of seconds specified before giving up. Default 5 seconds. +.TP +.BR \-\-wait, " \fB\-\-no\-wait\fP" +Wait for pending replies (if not setting the time). +The \fIno\-wait\fP form will disable the option. +This option is enabled by default. +.sp +If we are not setting the time, wait for all pending responses. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBSNTP_\fP or \fBSNTP\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", "\fI.\fP", "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH USAGE +.TP +.BR Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.TP +.BR Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate @NTPDATE_MS@ , +or +.Xr rdate 8 +commands. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH BUGS +Please report bugs to http://bugs.ntp.org . +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP +option definitions. diff --git a/sntp/sntp.mdoc.in b/sntp/sntp.mdoc.in new file mode 100644 index 000000000..425a46708 --- /dev/null +++ b/sntp/sntp.mdoc.in @@ -0,0 +1,275 @@ +.Dd June 21 2011 +.Dt SNTP @SNTP_MS@ User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (sntp-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 21, 2011 at 03:45:42 AM by AutoGen 5.11.10pre10 +.\" From the definitions sntp-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm sntp +.Nd standard Simple Network Time Protocol program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +[ hostname-or-IP ...] +.Pp +.Sh DESCRIPTION +.Nm +can be used as a SNTP client to query a NTP or SNTP server and either display +the time or set the local system's time (given suitable privilege). It can be +run as an interactive command or in a +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.PP +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +and the +.Ic "'+4.567 +/- 0.089 secs'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct), +and the date/time of +'1996-10-15 20:17:25.123' +is believed to be correct to within ++/- 0.089 +seconds. +.Sh "OPTIONS" +.Bl -tag +.It \-4 ", " -\-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of the following host names on the command line +to the IPv4 namespace. +.It \-6 ", " -\-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of the following host names on the command line +to the IPv6 namespace. +.It \-a " \fIauth\-keynumber\fP, " \-\-authentication "=" \fIauth\-keynumber\fP +Enable authentication with the key auth-keynumber. +This option takes an integer number as its argument. +.sp +This option enables authentication using the key specified in this +option's argument. The argument of this option is the keyid, a +number specified in the keyfile as this key's identifier. See the +keyfile option (-k) for more details. +.It \-B " \fIseconds\fP, " \-\-bctimeout "=" \fIseconds\fP +The number of seconds to wait for broadcasts. +This option takes an integer number as its argument. +The default \fIseconds\fP for this option is: +.ti +4 + 68 +.sp +When waiting for a broadcast packet SNTP will wait the number +of seconds specified before giving up. Default 68 seconds. +.It \-b " \fIbroadcast\-address\fP, " \-\-broadcast "=" \fIbroadcast\-address\fP +Listen to the address specified for broadcast time sync. +This option may appear an unlimited number of times. +.sp +If specified SNTP will listen to the specified address +for NTP broadcasts. The default maximum wait time, +68 seconds, can be modified with -B. +.It \-c " \fIhost\-name\fP, " \-\-concurrent "=" \fIhost\-name\fP +Concurrently query all IPs returned for host-name. +This option may appear an unlimited number of times. +.sp +Requests from an NTP "client" to a "server" should never be sent +more rapidly than one every 2 seconds. By default, any IPs returned +as part of a DNS lookup are assumed to be for a single instance of +ntpd, and therefore sntp will send queries to these IPs one after +another, with a 2-second gap in between each query. +The -c or --concurrent flag says that any IPs returned for the DNS +lookup of the supplied host-name are on different machines, so we +can send concurrent queries. +.It \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-h " \fImilliseconds\fP, " \-\-headspace "=" \fImilliseconds\fP +The gap (in milliseconds) between time requests. +This option takes an integer number as its argument. +The default \fImilliseconds\fP for this option is: +.ti +4 + 10 +.sp +Since we're only going to use the first valid response we get and +there is benefit to specifying a good number of servers to query, +separate the queries we send out by the specified number of +milliseconds. +Default 10 milliseconds. +.It \-K " \fIfile\-name\fP, " \-\-kod "=" \fIfile\-name\fP +KoD history filename. +The default \fIfile\-name\fP for this option is: +.ti +4 + /var/db/ntp-kod +.sp +Specifies the filename to be used for the persistent history of KoD +responses received from servers. The default is +/var/db/ntp-kod . +.It \-k " \fIfile\-name\fP, " \-\-keyfile "=" \fIfile\-name\fP +Look in this file for the key specified with -a. +.sp +This option specifies the keyfile. +SNTP will search for the key specified with -a keyno in this +file. Key files follow the following format: +keyid keytype key +Where keyid is a number identifying this key +keytype is one of the following: +S Key is a 64 Bit hexadecimal number as specified in in the DES specification. +N Key is a 64 Bit hexadecimal number as specified in the NTP standard. +A Key is a 1-to-8 character ASCII string. +M Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. +For more information see ntp.keys(5). +.It \-l " \fIfile\-name\fP, " \-\-filelog "=" \fIfile\-name\fP +Log to specified logfile. +.sp +This option causes the client to write log messages to the specified +logfile. +.It \-M " \fInumber\fP, " \-\-steplimit "=" \fInumber\fP +Adjustments less than steplimit msec will be slewed. +This option takes an integer number as its argument. +The value of \fInumber\fP is constrained to being: +.in +4 +.nf +.na +greater than or equal to 0 +.fi +.in -4 +.sp +If the time adjustment is less than steplimit milliseconds, slew the +amount using adjtime(). Otherwise, step the correction using +settimeofday(). +.It \-o " \fInumber\fP, " \-\-ntpversion "=" \fInumber\fP +Send as our NTP version. +This option takes an integer number as its argument. +The value of \fInumber\fP is constrained to being: +.in +4 +.nf +.na +in the range 0 through 7 +.fi +.in -4 +The default \fInumber\fP for this option is: +.ti +4 + 4 +.sp +When sending requests to a remote server, tell them we are running +NTP protocol version . +.It \-r ", " -\-usereservedport +Use the NTP Reserved Port (port 123). +.sp +Use port 123, which is reserved for NTP, for our network +communications. +.It \-S ", " -\-step +OK to 'step' the time with settimeofday(). +.sp +.It \-s ", " -\-slew +OK to 'slew' the time with adjtime(). +.sp +.It \-u " \fIseconds\fP, " \-\-uctimeout "=" \fIseconds\fP +The number of seconds to wait for unicast responses. +This option takes an integer number as its argument. +The default \fIseconds\fP for this option is: +.ti +4 + 5 +.sp +When waiting for a unicast reply, SNTP will wait the number +of seconds specified before giving up. Default 5 seconds. +.It \-\-wait, " \fB\-\-no\-wait\fP" +Wait for pending replies (if not setting the time). +The \fIno\-wait\fP form will disable the option. +This option is enabled by default. +.sp +If we are not setting the time, wait for all pending responses. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBSNTP_\fP or \fBSNTP\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", "\fI.\fP", "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE +.Bl -tag -width indent +.It Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.It Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate @NTPDATE_MS@ , +or +.Xr rdate 8 +commands. +.El +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh BUGS +Please report bugs to http://bugs.ntp.org . +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP +option definitions. diff --git a/util/ntp-keygen.1ntp-keygenman b/util/ntp-keygen.1ntp-keygenman new file mode 100644 index 000000000..6a1b7f103 --- /dev/null +++ b/util/ntp-keygen.1ntp-keygenman @@ -0,0 +1,917 @@ +.TH ntp-keygen 1ntp-keygenman "22 Jun 2011" "ntp (4.2.7p184)" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 05:00:14 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-keygen-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntp-keygen \- Create a NTP host key +.SH SYNOPSIS +.B ntp-keygen +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." +.PP +All arguments must be options. +.PP +.SH DESCRIPTION +This program generates cryptographic data files used by the NTPv4 +authentication and identification schemes. +It generates MD5 key files used in symmetric key cryptography. +In addition, if the OpenSSL software library has been installed, +it generates keys, certificate and identity files used in public key +cryptography. +These files are used for cookie encryption, +digital signature and challenge/response identification algorithms +compatible with the Internet standard security infrastructure. +.PP +All files are in PEM-encoded printable ASCII format, +so they can be embedded as MIME attachments in mail to other sites +and certificate authorities. +By default, files are not encrypted. +.PP +The +.Xr ntpd 8 +configuration command +.Ic crypto pw Ar password +specifies the read password for previously encrypted files. +The daemon expires on the spot if the password is missing +or incorrect. +For convenience, if a file has been previously encrypted, +the default read password is the name of the host running +the program. +If the previous write password is specified as the host name, +these files can be read by that host with no explicit password. +.PP +File names begin with the prefix +.Cm ntpkey_ +and end with the postfix +\fI_hostname.filestamp ,\fR +where +\fIhostname\fR +is the owner name, usually the string returned +by the Unix gethostname() routine, and +\fIfilestamp\fR +is the NTP seconds when the file was generated, in decimal digits. +This both guarantees uniqueness and simplifies maintenance +procedures, since all files can be quickly removed +by a +.Ic rm ntpkey\&* +command or all files generated +at a specific time can be removed by a +.Ic rm +\fI\&*filestamp\fR +command. +To further reduce the risk of misconfiguration, +the first two lines of a file contain the file name +and generation date and time as comments. +.PP +All files are installed by default in the keys directory +.Pa /usr/local/etc , +which is normally in a shared filesystem +in NFS-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.PP +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.PP +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.B +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.B +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.PP +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.PP +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.PP +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.PP +Installing the keys as root might not work in NFS-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.PP +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +.PP +All files are installed by default in the keys directory +.Pa /usr/local/etc , +which is normally in a shared filesystem +in NFS-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.PP +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.PP +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.B +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.B +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.PP +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.PP +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.PP +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.PP +Installing the keys as root might not work in NFS-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.PP +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +seconds. +seconds. +s Trusted Hosts and Groups +Each cryptographic configuration involves selection of a signature scheme +and identification scheme, called a cryptotype, +as explained in the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +The default cryptotype uses RSA encryption, MD5 message digest +and TC identification. +First, configure a NTP subnet including one or more low-stratum +trusted hosts from which all other hosts derive synchronization +directly or indirectly. +Trusted hosts have trusted certificates; +all other hosts have nontrusted certificates. +These hosts will automatically and dynamically build authoritative +certificate trails to one or more trusted hosts. +A trusted group is the set of all hosts that have, directly or indirectly, +a certificate trail ending at a trusted host. +The trail is defined by static configuration file entries +or dynamic means described on the +.Sx Automatic NTP Configuration Options +section of +.Xr ntp.conf 5 . +.PP +On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +.Cm ntpkey +files. +Then run +.B +T +to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +T +flag to generate keys and nontrusted certificates. +When complete, start the NTP daemons beginning at the lowest stratum +and working up the tree. +It may take some time for Autokey to instantiate the certificate trails +throughout the subnet, but setting up the environment is completely automatic. +.PP +If it is necessary to use a different sign key or different digest/signature +scheme than the default, run +.B +with the +S Ar type +option, where +\fItype\fR +is either +.Cm RSA +or +.Cm DSA . +The most often need to do this is when a DSA-signed certificate is used. +If it is necessary to use a different certificate scheme than the default, +run +.B +with the +c Ar scheme +option and selected +\fIscheme\fR +as needed. +f +.B +is run again without these options, it generates a new certificate +using the same scheme and sign key. +.PP +After setting up the environment it is advisable to update certificates +from time to time, if only to extend the validity interval. +Simply run +.B +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +.Xr ntpd 8 +should be restarted. +When +.Xr ntpd 8 +is restarted, it loads any new files and restarts the protocol. +Other dependent hosts will continue as usual until signatures are refreshed, +at which time the protocol is restarted. +.Ss Identity Schemes +As mentioned on the Autonomous Authentication page, +the default TC identity scheme is vulnerable to a middleman attack. +However, there are more secure identity schemes available, +including PC, IFF, GQ and MV described on the +.Qq Identification Schemes +page +(maybe available at +.Li http://www.eecis.udel.edu/%7emills/keygen.html ) . +These schemes are based on a TA, one or more trusted hosts +and some number of nontrusted hosts. +Trusted hosts prove identity using values provided by the TA, +while the remaining hosts prove identity using values provided +by a trusted host and certificate trails that end on that host. +The name of a trusted host is also the name of its sugroup +and also the subject and issuer name on its trusted certificate. +The TA is not necessarily a trusted host in this sense, but often is. +.PP +In some schemes there are separate keys for servers and clients. +A server can also be a client of another server, +but a client can never be a server for another client. +In general, trusted hosts and nontrusted hosts that operate +as both server and client have parameter files that contain +both server and client keys. +Hosts that operate +only as clients have key files that contain only client keys. +.PP +The PC scheme supports only one trusted host in the group. +On trusted host alice run +.B +P +p Ar password +to generate the host key file +.Pa ntpkey_RSAkey_ Ns Ar alice.filestamp +and trusted private certificate file +.Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp . +Copy both files to all group hosts; +they replace the files which would be generated in other schemes. +On each host bob install a soft link from the generic name +.Pa ntpkey_host_ Ns Ar bob +to the host key file and soft link +.Pa ntpkey_cert_ Ns Ar bob +to the private certificate file. +Note the generic links are on bob, but point to files generated +by trusted host alice. +In this scheme it is not possible to refresh +either the keys or certificates without copying them +to all other hosts in the group. +.PP +For the IFF scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host in the group, +generate the IFF parameter file. +On trusted host alice run +.B +T +I +p Ar password +to produce her parameter file +.Pa ntpkey_IFFpar_ Ns Ar alice.filestamp , +which includes both server and client keys. +Copy this file to all group hosts that operate as both servers +and clients and install a soft link from the generic +.Pa ntpkey_iff_ Ns Ar alice +to this file. +If there are no hosts restricted to operate only as clients, +there is nothing further to do. +As the IFF scheme is independent +of keys and certificates, these files can be refreshed as needed. +.PP +If a rogue client has the parameter file, it could masquerade +as a legitimate server and present a middleman threat. +To eliminate this threat, the client keys can be extracted +from the parameter file and distributed to all restricted clients. +After generating the parameter file, on alice run +.B +e +and pipe the output to a file or mail program. +Copy or mail this file to all restricted clients. +On these clients install a soft link from the generic +.Pa ntpkey_iff_ Ns Ar alice +to this file. +To further protect the integrity of the keys, +each file can be encrypted with a secret password. +.PP +For the GQ scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host +in the group, generate the IFF parameter file. +On trusted host alice run +.B +T +G +p Ar password +to produce her parameter file +.Pa ntpkey_GQpar_ Ns Ar alice.filestamp , +which includes both server and client keys. +Copy this file to all group hosts and install a soft link +from the generic +.Pa ntpkey_gq_ Ns Ar alice +to this file. +In addition, on each host bob install a soft link +from generic +.Pa ntpkey_gq_ Ns Ar bob +to this file. +As the GQ scheme updates the GQ parameters file and certificate +at the same time, keys and certificates can be regenerated as needed. +.PP +For the MV scheme, proceed as in the TC scheme to generate keys +and certificates for all group hosts. +For illustration assume trish is the TA, alice one of several trusted hosts +and bob one of her clients. +On TA trish run +.B +V Ar n +p Ar password , +where +\fIn\fR +is the number of revokable keys (typically 5) to produce +the parameter file +.Pa ntpkeys_MVpar_ Ns Ar trish.filestamp +and client key files +.Pa ntpkeys_MVkeyd_ Ns Ar trish.filestamp +where +\fId\fR +is the key number (0 \&< +\fId\fR +\&< +\fIn ) .\fR +Copy the parameter file to alice and install a soft link +from the generic +.Pa ntpkey_mv_ Ns Ar alice +to this file. +Copy one of the client key files to alice for later distribution +to her clients. +It doesn't matter which client key file goes to alice, +since they all work the same way. +Alice copies the client key file to all of her cliens. +On client bob install a soft link from generic +.Pa ntpkey_mvkey_ Ns Ar bob +to the client key file. +As the MV scheme is independent of keys and certificates, +these files can be refreshed as needed. +.Ss Command Line Options +.TP +.BR Fl c Ar scheme +Select certificate message digest/signature encryption scheme. +The +\fIscheme\fR +can be one of the following: +. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , +or +.Cm DSA-SHA1 . +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. +The default without this option is +.Cm RSA-MD5 . +.TP +.BR Fl d +Enable debugging. +This option displays the cryptographic data produced in eye-friendly billboards. +.TP +.BR Fl e +Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +.TP +.BR Fl G +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.TP +.BR Fl g +Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +.TP +.BR Fl H +Generate new host keys, obsoleting any that may exist. +.TP +.BR Fl I +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +.TP +.BR Fl i Ar name +Set the suject name to +\fIname .\fR +This is used as the subject field in certificates +and in the file name for host and sign keys. +.TP +.BR Fl M +Generate MD5 keys, obsoleting any that may exist. +.TP +.BR Fl P +Generate a private certificate. +By default, the program generates public certificates. +.TP +.BR Fl p Ar password +Encrypt generated files containing private data with +\fIpassword\fR +and the DES-CBC algorithm. +.TP +.BR Fl q +Set the password for reading files to password. +.TP +.BR Fl S Oo Cm RSA | DSA Oc +Generate a new sign key of the designated type, +obsoleting any that may exist. +By default, the program uses the host key as the sign key. +.TP +.BR Fl s Ar name +Set the issuer name to +\fIname .\fR +This is used for the issuer field in certificates +and in the file name for identity files. +.TP +.BR Fl T +Generate a trusted certificate. +By default, the program generates a non-trusted certificate. +.TP +.BR Fl V Ar nkeys +Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. +.Ss Random Seed File +All cryptographically sound key generation schemes must have means +to randomize the entropy seed used to initialize +the internal pseudo-random number generator used +by the library routines. +The OpenSSL library uses a designated random seed file for this purpose. +The file must be available when starting the NTP daemon and +.B +program. +If a site supports OpenSSL or its companion OpenSSH, +it is very likely that means to do this are already available. +.PP +It is important to understand that entropy must be evolved +for each generation, for otherwise the random number sequence +would be predictable. +Various means dependent on external events, such as keystroke intervals, +can be used to do this and some systems have built-in entropy sources. +Suitable means are described in the OpenSSL software documentation, +but are outside the scope of this page. +.PP +The entropy seed used by the OpenSSL library is contained in a file, +usually called +.Cm .rnd , +which must be available when starting the NTP daemon +or the +.B +program. +The NTP daemon will first look for the file +using the path specified by the +.Ic randfile +subcommand of the +.Ic crypto +configuration command. +If not specified in this way, or when starting the +.B +program, +the OpenSSL library will look for the file using the path specified +by the +.Ev RANDFILE +environment variable in the user home directory, +whether root or some other user. +If the +.Ev RANDFILE +environment variable is not present, +the library will look for the +.Cm .rnd +file in the user home directory. +If the file is not available or cannot be written, +the daemon exits with a message to the system log and the program +exits with a suitable error message. +.Ss Cryptographic Data Files +All other file formats begin with two lines. +The first contains the file name, including the generated host name +and filestamp. +The second contains the datestamp in conventional Unix date format. +Lines beginning with # are considered comments and ignored by the +.B +program and +.Xr ntpd 8 +daemon. +Cryptographic values are encoded first using ASN.1 rules, +then encrypted if necessary, and finally written PEM-encoded +printable ASCII format preceded and followed by MIME content identifier lines. +.PP +The format of the symmetric keys file is somewhat different +than the other files in the interest of backward compatibility. +Since DES-CBC is deprecated in NTPv4, the only key format of interest +is MD5 alphanumeric strings. +Following hte heard the keys are +entered one per line in the format +.D1 Ar keyno type key +where +\fIkeyno\fR +is a positive integer in the range 1-65,535, +\fItype\fR +is the string MD5 defining the key format and +\fIkey\fR +is the key itself, +which is a printable ASCII string 16 characters or less in length. +Each character is chosen from the 93 printable characters +in the range 0x21 through 0x7f excluding space and the +.Ql # +character. +.PP +Note that the keys used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +programs +are checked against passwords requested by the programs +and entered by hand, so it is generally appropriate to specify these keys +in human readable ASCII format. +.PP +The +.B +program generates a MD5 symmetric keys file +.Pa ntpkey_MD5key_ Ns Ar hostname.filestamp . +Since the file contains private shared keys, +it should be visible only to root and distributed by secure means +to other subnet hosts. +The NTP daemon loads the file +.Pa ntp.keys , +so +.B +installs a soft link from this name to the generated file. +Subsequently, similar soft links must be installed by manual +or automated means on the other subnet hosts. +While this file is not used with the Autokey Version 2 protocol, +it is needed to authenticate some remote configuration commands +used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +utilities. +.SH "OPTIONS" +.TP +.BR \-c " \fIscheme\fP, " \-\-certificate "=" \fIscheme\fP +certificate scheme. +.sp +scheme is one of +RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160, +DSA-SHA, or DSA-SHA1. +Select the certificate message digest/signature encryption scheme. +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. The default without +this option is RSA-MD5. +.TP +.BR \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-e ", " -\-id\-key +Write IFF or GQ identity keys. +.sp +Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +.TP +.BR \-G ", " -\-gq\-params +Generate GQ parameters and keys. +.sp +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.TP +.BR \-H ", " -\-host\-key +generate RSA host key. +.sp +Generate new host keys, obsoleting any that may exist. +.TP +.BR \-I ", " -\-iffkey +generate IFF parameters. +.sp +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +.TP +.BR \-i " \fIissuer\-name\fP, " \-\-issuer\-name "=" \fIissuer\-name\fP +set issuer name. +.sp +Set the subject name to name. This is used as the subject field +in certificates and in the file name for host and sign keys. +.TP +.BR \-l " \fIlifetime\fP, " \-\-lifetime "=" \fIlifetime\fP +set certificate lifetime. +This option takes an integer number as its argument. +.sp +Set the certificate expiration to lifetime days from now. +.TP +.BR \-M ", " -\-md5key +generate MD5 keys. +.sp +Generate MD5 keys, obsoleting any that may exist. +.TP +.BR \-m " \fImodulus\fP, " \-\-modulus "=" \fImodulus\fP +modulus. +This option takes an integer number as its argument. +The value of \fImodulus\fP is constrained to being: +.in +4 +.nf +.na +in the range 256 through 2048 +.fi +.in -4 +.sp +The number of bits in the prime modulus. The default is 512. +.TP +.BR \-P ", " -\-pvt\-cert +generate PC private certificate. +.sp +Generate a private certificate. By default, the program generates +public certificates. +.TP +.BR \-p " \fIpasswd\fP, " \-\-pvt\-passwd "=" \fIpasswd\fP +output private password. +.sp +Encrypt generated files containing private data with the specified +password and the DES-CBC algorithm. +.TP +.BR \-q " \fIpasswd\fP, " \-\-get\-pvt\-passwd "=" \fIpasswd\fP +input private password. +.sp +Set the password for reading files to the specified password. +.TP +.BR \-S " \fIsign\fP, " \-\-sign\-key "=" \fIsign\fP +generate sign key (RSA or DSA). +.sp +Generate a new sign key of the designated type, obsoleting any +that may exist. By default, the program uses the host key as the +sign key. +.TP +.BR \-s " \fIhost\fP, " \-\-subject\-name "=" \fIhost\fP +set subject name. +.sp +Set the issuer name to name. This is used for the issuer field +in certificates and in the file name for identity files. +.TP +.BR \-T ", " -\-trusted\-cert +trusted certificate (TC scheme). +.sp +Generate a trusted certificate. By default, the program generates +a non-trusted certificate. +.TP +.BR \-V " \fInum\fP, " \-\-mv\-params "=" \fInum\fP +generate MV parameters. +This option takes an integer number as its argument. +.sp +Generate parameters and keys for the Mu-Varadharajan (MV) +identification scheme. +.TP +.BR \-v " \fInum\fP, " \-\-mv\-keys "=" \fInum\fP +update MV keys. +This option takes an integer number as its argument. +.sp +This option has not been fully documented. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTP_KEYGEN_\fP or \fBNTP_KEYGEN\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH USAGE +The +p Ar password +option specifies the write password and +q Ar password +option the read password for previously encrypted files. +The +.B +program prompts for the password if it reads an encrypted file +and the password is missing or incorrect. +If an encrypted file is read successfully and +no write password is specified, the read password is used +as the write password by default. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH BUGS +It can take quite a while to generate some cryptographic values, +from one to several minutes with modern architectures +such as UltraSPARC and up to tens of minutes to an hour +with older architectures such as SPARC IPC. +.PP +Please report bugs to http://bugs.ntp.org . +.SH NOTES +Portions of this document came from FreeBSD. +.PP +This manual page was \fIAutoGen\fP-erated from the \fBntp-keygen\fP +option definitions. diff --git a/util/ntp-keygen.1ntp-keygenmdoc b/util/ntp-keygen.1ntp-keygenmdoc new file mode 100644 index 000000000..6c167c707 --- /dev/null +++ b/util/ntp-keygen.1ntp-keygenmdoc @@ -0,0 +1,884 @@ +.Dd June 22 2011 +.Dt NTP_KEYGEN 1ntp-keygenmdoc User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 05:00:16 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-keygen-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntp-keygen +.Nd Create a NTP host key +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +.Pp +All arguments must be options. +.Pp +.Sh DESCRIPTION +This program generates cryptographic data files used by the NTPv4 +authentication and identification schemes. +It generates MD5 key files used in symmetric key cryptography. +In addition, if the OpenSSL software library has been installed, +it generates keys, certificate and identity files used in public key +cryptography. +These files are used for cookie encryption, +digital signature and challenge/response identification algorithms +compatible with the Internet standard security infrastructure. +.Pp +All files are in PEM-encoded printable ASCII format, +so they can be embedded as MIME attachments in mail to other sites +and certificate authorities. +By default, files are not encrypted. +.Pp +The +.Xr ntpd 8 +configuration command +.Ic crypto pw Ar password +specifies the read password for previously encrypted files. +The daemon expires on the spot if the password is missing +or incorrect. +For convenience, if a file has been previously encrypted, +the default read password is the name of the host running +the program. +If the previous write password is specified as the host name, +these files can be read by that host with no explicit password. +.Pp +File names begin with the prefix +.Cm ntpkey_ +and end with the postfix +.Ar _hostname.filestamp , +where +.Ar hostname +is the owner name, usually the string returned +by the Unix gethostname() routine, and +.Ar filestamp +is the NTP seconds when the file was generated, in decimal digits. +This both guarantees uniqueness and simplifies maintenance +procedures, since all files can be quickly removed +by a +.Ic rm ntpkey\&* +command or all files generated +at a specific time can be removed by a +.Ic rm +.Ar \&*filestamp +command. +To further reduce the risk of misconfiguration, +the first two lines of a file contain the file name +and generation date and time as comments. +.Pp +All files are installed by default in the keys directory +.Pa /usr/local/etc , +which is normally in a shared filesystem +in NFS-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.Pp +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.Pp +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.Nm +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.Nm +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.Pp +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.Pp +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.Pp +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.Pp +Installing the keys as root might not work in NFS-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.Pp +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +.Pp +All files are installed by default in the keys directory +.Pa /usr/local/etc , +which is normally in a shared filesystem +in NFS-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.Pp +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.Pp +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.Nm +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.Nm +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.Pp +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.Pp +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.Pp +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.Pp +Installing the keys as root might not work in NFS-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.Pp +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +seconds. +seconds. +s Trusted Hosts and Groups +Each cryptographic configuration involves selection of a signature scheme +and identification scheme, called a cryptotype, +as explained in the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +The default cryptotype uses RSA encryption, MD5 message digest +and TC identification. +First, configure a NTP subnet including one or more low-stratum +trusted hosts from which all other hosts derive synchronization +directly or indirectly. +Trusted hosts have trusted certificates; +all other hosts have nontrusted certificates. +These hosts will automatically and dynamically build authoritative +certificate trails to one or more trusted hosts. +A trusted group is the set of all hosts that have, directly or indirectly, +a certificate trail ending at a trusted host. +The trail is defined by static configuration file entries +or dynamic means described on the +.Sx Automatic NTP Configuration Options +section of +.Xr ntp.conf 5 . +.Pp +On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +.Cm ntpkey +files. +Then run +.Nm +.Fl T +to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +.Fl T +flag to generate keys and nontrusted certificates. +When complete, start the NTP daemons beginning at the lowest stratum +and working up the tree. +It may take some time for Autokey to instantiate the certificate trails +throughout the subnet, but setting up the environment is completely automatic. +.Pp +If it is necessary to use a different sign key or different digest/signature +scheme than the default, run +.Nm +with the +.Fl S Ar type +option, where +.Ar type +is either +.Cm RSA +or +.Cm DSA . +The most often need to do this is when a DSA-signed certificate is used. +If it is necessary to use a different certificate scheme than the default, +run +.Nm +with the +.Fl c Ar scheme +option and selected +.Ar scheme +as needed. +f +.Nm +is run again without these options, it generates a new certificate +using the same scheme and sign key. +.Pp +After setting up the environment it is advisable to update certificates +from time to time, if only to extend the validity interval. +Simply run +.Nm +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +.Xr ntpd 8 +should be restarted. +When +.Xr ntpd 8 +is restarted, it loads any new files and restarts the protocol. +Other dependent hosts will continue as usual until signatures are refreshed, +at which time the protocol is restarted. +.Ss Identity Schemes +As mentioned on the Autonomous Authentication page, +the default TC identity scheme is vulnerable to a middleman attack. +However, there are more secure identity schemes available, +including PC, IFF, GQ and MV described on the +.Qq Identification Schemes +page +(maybe available at +.Li http://www.eecis.udel.edu/%7emills/keygen.html ) . +These schemes are based on a TA, one or more trusted hosts +and some number of nontrusted hosts. +Trusted hosts prove identity using values provided by the TA, +while the remaining hosts prove identity using values provided +by a trusted host and certificate trails that end on that host. +The name of a trusted host is also the name of its sugroup +and also the subject and issuer name on its trusted certificate. +The TA is not necessarily a trusted host in this sense, but often is. +.Pp +In some schemes there are separate keys for servers and clients. +A server can also be a client of another server, +but a client can never be a server for another client. +In general, trusted hosts and nontrusted hosts that operate +as both server and client have parameter files that contain +both server and client keys. +Hosts that operate +only as clients have key files that contain only client keys. +.Pp +The PC scheme supports only one trusted host in the group. +On trusted host alice run +.Nm +.Fl P +.Fl p Ar password +to generate the host key file +.Pa ntpkey_RSAkey_ Ns Ar alice.filestamp +and trusted private certificate file +.Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp . +Copy both files to all group hosts; +they replace the files which would be generated in other schemes. +On each host bob install a soft link from the generic name +.Pa ntpkey_host_ Ns Ar bob +to the host key file and soft link +.Pa ntpkey_cert_ Ns Ar bob +to the private certificate file. +Note the generic links are on bob, but point to files generated +by trusted host alice. +In this scheme it is not possible to refresh +either the keys or certificates without copying them +to all other hosts in the group. +.Pp +For the IFF scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host in the group, +generate the IFF parameter file. +On trusted host alice run +.Nm +.Fl T +.Fl I +.Fl p Ar password +to produce her parameter file +.Pa ntpkey_IFFpar_ Ns Ar alice.filestamp , +which includes both server and client keys. +Copy this file to all group hosts that operate as both servers +and clients and install a soft link from the generic +.Pa ntpkey_iff_ Ns Ar alice +to this file. +If there are no hosts restricted to operate only as clients, +there is nothing further to do. +As the IFF scheme is independent +of keys and certificates, these files can be refreshed as needed. +.Pp +If a rogue client has the parameter file, it could masquerade +as a legitimate server and present a middleman threat. +To eliminate this threat, the client keys can be extracted +from the parameter file and distributed to all restricted clients. +After generating the parameter file, on alice run +.Nm +.Fl e +and pipe the output to a file or mail program. +Copy or mail this file to all restricted clients. +On these clients install a soft link from the generic +.Pa ntpkey_iff_ Ns Ar alice +to this file. +To further protect the integrity of the keys, +each file can be encrypted with a secret password. +.Pp +For the GQ scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host +in the group, generate the IFF parameter file. +On trusted host alice run +.Nm +.Fl T +.Fl G +.Fl p Ar password +to produce her parameter file +.Pa ntpkey_GQpar_ Ns Ar alice.filestamp , +which includes both server and client keys. +Copy this file to all group hosts and install a soft link +from the generic +.Pa ntpkey_gq_ Ns Ar alice +to this file. +In addition, on each host bob install a soft link +from generic +.Pa ntpkey_gq_ Ns Ar bob +to this file. +As the GQ scheme updates the GQ parameters file and certificate +at the same time, keys and certificates can be regenerated as needed. +.Pp +For the MV scheme, proceed as in the TC scheme to generate keys +and certificates for all group hosts. +For illustration assume trish is the TA, alice one of several trusted hosts +and bob one of her clients. +On TA trish run +.Nm +.Fl V Ar n +.Fl p Ar password , +where +.Ar n +is the number of revokable keys (typically 5) to produce +the parameter file +.Pa ntpkeys_MVpar_ Ns Ar trish.filestamp +and client key files +.Pa ntpkeys_MVkeyd_ Ns Ar trish.filestamp +where +.Ar d +is the key number (0 \&< +.Ar d +\&< +.Ar n ) . +Copy the parameter file to alice and install a soft link +from the generic +.Pa ntpkey_mv_ Ns Ar alice +to this file. +Copy one of the client key files to alice for later distribution +to her clients. +It doesn't matter which client key file goes to alice, +since they all work the same way. +Alice copies the client key file to all of her cliens. +On client bob install a soft link from generic +.Pa ntpkey_mvkey_ Ns Ar bob +to the client key file. +As the MV scheme is independent of keys and certificates, +these files can be refreshed as needed. +.Ss Command Line Options +.Bl -tag -width indent +.It Fl c Ar scheme +Select certificate message digest/signature encryption scheme. +The +.Ar scheme +can be one of the following: +. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , +or +.Cm DSA-SHA1 . +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. +The default without this option is +.Cm RSA-MD5 . +.It Fl d +Enable debugging. +This option displays the cryptographic data produced in eye-friendly billboards. +.It Fl e +Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +.It Fl G +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.It Fl g +Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +.It Fl H +Generate new host keys, obsoleting any that may exist. +.It Fl I +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +.It Fl i Ar name +Set the suject name to +.Ar name . +This is used as the subject field in certificates +and in the file name for host and sign keys. +.It Fl M +Generate MD5 keys, obsoleting any that may exist. +.It Fl P +Generate a private certificate. +By default, the program generates public certificates. +.It Fl p Ar password +Encrypt generated files containing private data with +.Ar password +and the DES-CBC algorithm. +.It Fl q +Set the password for reading files to password. +.It Fl S Oo Cm RSA | DSA Oc +Generate a new sign key of the designated type, +obsoleting any that may exist. +By default, the program uses the host key as the sign key. +.It Fl s Ar name +Set the issuer name to +.Ar name . +This is used for the issuer field in certificates +and in the file name for identity files. +.It Fl T +Generate a trusted certificate. +By default, the program generates a non-trusted certificate. +.It Fl V Ar nkeys +Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. +.El +.Ss Random Seed File +All cryptographically sound key generation schemes must have means +to randomize the entropy seed used to initialize +the internal pseudo-random number generator used +by the library routines. +The OpenSSL library uses a designated random seed file for this purpose. +The file must be available when starting the NTP daemon and +.Nm +program. +If a site supports OpenSSL or its companion OpenSSH, +it is very likely that means to do this are already available. +.Pp +It is important to understand that entropy must be evolved +for each generation, for otherwise the random number sequence +would be predictable. +Various means dependent on external events, such as keystroke intervals, +can be used to do this and some systems have built-in entropy sources. +Suitable means are described in the OpenSSL software documentation, +but are outside the scope of this page. +.Pp +The entropy seed used by the OpenSSL library is contained in a file, +usually called +.Cm .rnd , +which must be available when starting the NTP daemon +or the +.Nm +program. +The NTP daemon will first look for the file +using the path specified by the +.Ic randfile +subcommand of the +.Ic crypto +configuration command. +If not specified in this way, or when starting the +.Nm +program, +the OpenSSL library will look for the file using the path specified +by the +.Ev RANDFILE +environment variable in the user home directory, +whether root or some other user. +If the +.Ev RANDFILE +environment variable is not present, +the library will look for the +.Cm .rnd +file in the user home directory. +If the file is not available or cannot be written, +the daemon exits with a message to the system log and the program +exits with a suitable error message. +.Ss Cryptographic Data Files +All other file formats begin with two lines. +The first contains the file name, including the generated host name +and filestamp. +The second contains the datestamp in conventional Unix date format. +Lines beginning with # are considered comments and ignored by the +.Nm +program and +.Xr ntpd 8 +daemon. +Cryptographic values are encoded first using ASN.1 rules, +then encrypted if necessary, and finally written PEM-encoded +printable ASCII format preceded and followed by MIME content identifier lines. +.Pp +The format of the symmetric keys file is somewhat different +than the other files in the interest of backward compatibility. +Since DES-CBC is deprecated in NTPv4, the only key format of interest +is MD5 alphanumeric strings. +Following hte heard the keys are +entered one per line in the format +.D1 Ar keyno type key +where +.Ar keyno +is a positive integer in the range 1-65,535, +.Ar type +is the string MD5 defining the key format and +.Ar key +is the key itself, +which is a printable ASCII string 16 characters or less in length. +Each character is chosen from the 93 printable characters +in the range 0x21 through 0x7f excluding space and the +.Ql # +character. +.Pp +Note that the keys used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +programs +are checked against passwords requested by the programs +and entered by hand, so it is generally appropriate to specify these keys +in human readable ASCII format. +.Pp +The +.Nm +program generates a MD5 symmetric keys file +.Pa ntpkey_MD5key_ Ns Ar hostname.filestamp . +Since the file contains private shared keys, +it should be visible only to root and distributed by secure means +to other subnet hosts. +The NTP daemon loads the file +.Pa ntp.keys , +so +.Nm +installs a soft link from this name to the generated file. +Subsequently, similar soft links must be installed by manual +or automated means on the other subnet hosts. +While this file is not used with the Autokey Version 2 protocol, +it is needed to authenticate some remote configuration commands +used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +utilities. +.Sh "OPTIONS" +.Bl -tag +.It \-c " \fIscheme\fP, " \-\-certificate "=" \fIscheme\fP +certificate scheme. +.sp +scheme is one of +RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160, +DSA-SHA, or DSA-SHA1. +Select the certificate message digest/signature encryption scheme. +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. The default without +this option is RSA-MD5. +.It \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-e ", " -\-id\-key +Write IFF or GQ identity keys. +.sp +Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +.It \-G ", " -\-gq\-params +Generate GQ parameters and keys. +.sp +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.It \-H ", " -\-host\-key +generate RSA host key. +.sp +Generate new host keys, obsoleting any that may exist. +.It \-I ", " -\-iffkey +generate IFF parameters. +.sp +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +.It \-i " \fIissuer\-name\fP, " \-\-issuer\-name "=" \fIissuer\-name\fP +set issuer name. +.sp +Set the subject name to name. This is used as the subject field +in certificates and in the file name for host and sign keys. +.It \-l " \fIlifetime\fP, " \-\-lifetime "=" \fIlifetime\fP +set certificate lifetime. +This option takes an integer number as its argument. +.sp +Set the certificate expiration to lifetime days from now. +.It \-M ", " -\-md5key +generate MD5 keys. +.sp +Generate MD5 keys, obsoleting any that may exist. +.It \-m " \fImodulus\fP, " \-\-modulus "=" \fImodulus\fP +modulus. +This option takes an integer number as its argument. +The value of \fImodulus\fP is constrained to being: +.in +4 +.nf +.na +in the range 256 through 2048 +.fi +.in -4 +.sp +The number of bits in the prime modulus. The default is 512. +.It \-P ", " -\-pvt\-cert +generate PC private certificate. +.sp +Generate a private certificate. By default, the program generates +public certificates. +.It \-p " \fIpasswd\fP, " \-\-pvt\-passwd "=" \fIpasswd\fP +output private password. +.sp +Encrypt generated files containing private data with the specified +password and the DES-CBC algorithm. +.It \-q " \fIpasswd\fP, " \-\-get\-pvt\-passwd "=" \fIpasswd\fP +input private password. +.sp +Set the password for reading files to the specified password. +.It \-S " \fIsign\fP, " \-\-sign\-key "=" \fIsign\fP +generate sign key (RSA or DSA). +.sp +Generate a new sign key of the designated type, obsoleting any +that may exist. By default, the program uses the host key as the +sign key. +.It \-s " \fIhost\fP, " \-\-subject\-name "=" \fIhost\fP +set subject name. +.sp +Set the issuer name to name. This is used for the issuer field +in certificates and in the file name for identity files. +.It \-T ", " -\-trusted\-cert +trusted certificate (TC scheme). +.sp +Generate a trusted certificate. By default, the program generates +a non-trusted certificate. +.It \-V " \fInum\fP, " \-\-mv\-params "=" \fInum\fP +generate MV parameters. +This option takes an integer number as its argument. +.sp +Generate parameters and keys for the Mu-Varadharajan (MV) +identification scheme. +.It \-v " \fInum\fP, " \-\-mv\-keys "=" \fInum\fP +update MV keys. +This option takes an integer number as its argument. +.sp +This option has not been fully documented. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTP_KEYGEN_\fP or \fBNTP_KEYGEN\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE +The +.Fl p Ar password +option specifies the write password and +.Fl q Ar password +option the read password for previously encrypted files. +The +.Nm +program prompts for the password if it reads an encrypted file +and the password is missing or incorrect. +If an encrypted file is read successfully and +no write password is specified, the read password is used +as the write password by default. +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh BUGS +It can take quite a while to generate some cryptographic values, +from one to several minutes with modern architectures +such as UltraSPARC and up to tens of minutes to an hour +with older architectures such as SPARC IPC. +.Pp +Please report bugs to http://bugs.ntp.org . +.Sh NOTES +Portions of this document came from FreeBSD. +.Pp +This manual page was \fIAutoGen\fP-erated from the \fBntp-keygen\fP +option definitions. diff --git a/util/ntp-keygen.man.in b/util/ntp-keygen.man.in new file mode 100644 index 000000000..e20af2b38 --- /dev/null +++ b/util/ntp-keygen.man.in @@ -0,0 +1,917 @@ +.TH ntp-keygen @NTP_KEYGEN_MS@ "22 Jun 2011" "ntp (4.2.7p184)" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.man) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 05:00:14 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-keygen-opts.def +.\" and the template file agman-cmd.tpl +.\" +.SH NAME +ntp-keygen \- Create a NTP host key +.SH SYNOPSIS +.B ntp-keygen +.\" Mixture of short (flag) options and long options +.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." +.PP +All arguments must be options. +.PP +.SH DESCRIPTION +This program generates cryptographic data files used by the NTPv4 +authentication and identification schemes. +It generates MD5 key files used in symmetric key cryptography. +In addition, if the OpenSSL software library has been installed, +it generates keys, certificate and identity files used in public key +cryptography. +These files are used for cookie encryption, +digital signature and challenge/response identification algorithms +compatible with the Internet standard security infrastructure. +.PP +All files are in PEM-encoded printable ASCII format, +so they can be embedded as MIME attachments in mail to other sites +and certificate authorities. +By default, files are not encrypted. +.PP +The +.Xr ntpd 8 +configuration command +.Ic crypto pw Ar password +specifies the read password for previously encrypted files. +The daemon expires on the spot if the password is missing +or incorrect. +For convenience, if a file has been previously encrypted, +the default read password is the name of the host running +the program. +If the previous write password is specified as the host name, +these files can be read by that host with no explicit password. +.PP +File names begin with the prefix +.Cm ntpkey_ +and end with the postfix +\fI_hostname.filestamp ,\fR +where +\fIhostname\fR +is the owner name, usually the string returned +by the Unix gethostname() routine, and +\fIfilestamp\fR +is the NTP seconds when the file was generated, in decimal digits. +This both guarantees uniqueness and simplifies maintenance +procedures, since all files can be quickly removed +by a +.Ic rm ntpkey\&* +command or all files generated +at a specific time can be removed by a +.Ic rm +\fI\&*filestamp\fR +command. +To further reduce the risk of misconfiguration, +the first two lines of a file contain the file name +and generation date and time as comments. +.PP +All files are installed by default in the keys directory +.Pa /usr/local/etc , +which is normally in a shared filesystem +in NFS-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.PP +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.PP +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.B +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.B +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.PP +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.PP +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.PP +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.PP +Installing the keys as root might not work in NFS-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.PP +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +.PP +All files are installed by default in the keys directory +.Pa /usr/local/etc , +which is normally in a shared filesystem +in NFS-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.PP +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.PP +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.B +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.B +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.PP +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.PP +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.PP +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.PP +Installing the keys as root might not work in NFS-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.PP +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +seconds. +seconds. +s Trusted Hosts and Groups +Each cryptographic configuration involves selection of a signature scheme +and identification scheme, called a cryptotype, +as explained in the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +The default cryptotype uses RSA encryption, MD5 message digest +and TC identification. +First, configure a NTP subnet including one or more low-stratum +trusted hosts from which all other hosts derive synchronization +directly or indirectly. +Trusted hosts have trusted certificates; +all other hosts have nontrusted certificates. +These hosts will automatically and dynamically build authoritative +certificate trails to one or more trusted hosts. +A trusted group is the set of all hosts that have, directly or indirectly, +a certificate trail ending at a trusted host. +The trail is defined by static configuration file entries +or dynamic means described on the +.Sx Automatic NTP Configuration Options +section of +.Xr ntp.conf 5 . +.PP +On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +.Cm ntpkey +files. +Then run +.B +T +to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +T +flag to generate keys and nontrusted certificates. +When complete, start the NTP daemons beginning at the lowest stratum +and working up the tree. +It may take some time for Autokey to instantiate the certificate trails +throughout the subnet, but setting up the environment is completely automatic. +.PP +If it is necessary to use a different sign key or different digest/signature +scheme than the default, run +.B +with the +S Ar type +option, where +\fItype\fR +is either +.Cm RSA +or +.Cm DSA . +The most often need to do this is when a DSA-signed certificate is used. +If it is necessary to use a different certificate scheme than the default, +run +.B +with the +c Ar scheme +option and selected +\fIscheme\fR +as needed. +f +.B +is run again without these options, it generates a new certificate +using the same scheme and sign key. +.PP +After setting up the environment it is advisable to update certificates +from time to time, if only to extend the validity interval. +Simply run +.B +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +.Xr ntpd 8 +should be restarted. +When +.Xr ntpd 8 +is restarted, it loads any new files and restarts the protocol. +Other dependent hosts will continue as usual until signatures are refreshed, +at which time the protocol is restarted. +.Ss Identity Schemes +As mentioned on the Autonomous Authentication page, +the default TC identity scheme is vulnerable to a middleman attack. +However, there are more secure identity schemes available, +including PC, IFF, GQ and MV described on the +.Qq Identification Schemes +page +(maybe available at +.Li http://www.eecis.udel.edu/%7emills/keygen.html ) . +These schemes are based on a TA, one or more trusted hosts +and some number of nontrusted hosts. +Trusted hosts prove identity using values provided by the TA, +while the remaining hosts prove identity using values provided +by a trusted host and certificate trails that end on that host. +The name of a trusted host is also the name of its sugroup +and also the subject and issuer name on its trusted certificate. +The TA is not necessarily a trusted host in this sense, but often is. +.PP +In some schemes there are separate keys for servers and clients. +A server can also be a client of another server, +but a client can never be a server for another client. +In general, trusted hosts and nontrusted hosts that operate +as both server and client have parameter files that contain +both server and client keys. +Hosts that operate +only as clients have key files that contain only client keys. +.PP +The PC scheme supports only one trusted host in the group. +On trusted host alice run +.B +P +p Ar password +to generate the host key file +.Pa ntpkey_RSAkey_ Ns Ar alice.filestamp +and trusted private certificate file +.Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp . +Copy both files to all group hosts; +they replace the files which would be generated in other schemes. +On each host bob install a soft link from the generic name +.Pa ntpkey_host_ Ns Ar bob +to the host key file and soft link +.Pa ntpkey_cert_ Ns Ar bob +to the private certificate file. +Note the generic links are on bob, but point to files generated +by trusted host alice. +In this scheme it is not possible to refresh +either the keys or certificates without copying them +to all other hosts in the group. +.PP +For the IFF scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host in the group, +generate the IFF parameter file. +On trusted host alice run +.B +T +I +p Ar password +to produce her parameter file +.Pa ntpkey_IFFpar_ Ns Ar alice.filestamp , +which includes both server and client keys. +Copy this file to all group hosts that operate as both servers +and clients and install a soft link from the generic +.Pa ntpkey_iff_ Ns Ar alice +to this file. +If there are no hosts restricted to operate only as clients, +there is nothing further to do. +As the IFF scheme is independent +of keys and certificates, these files can be refreshed as needed. +.PP +If a rogue client has the parameter file, it could masquerade +as a legitimate server and present a middleman threat. +To eliminate this threat, the client keys can be extracted +from the parameter file and distributed to all restricted clients. +After generating the parameter file, on alice run +.B +e +and pipe the output to a file or mail program. +Copy or mail this file to all restricted clients. +On these clients install a soft link from the generic +.Pa ntpkey_iff_ Ns Ar alice +to this file. +To further protect the integrity of the keys, +each file can be encrypted with a secret password. +.PP +For the GQ scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host +in the group, generate the IFF parameter file. +On trusted host alice run +.B +T +G +p Ar password +to produce her parameter file +.Pa ntpkey_GQpar_ Ns Ar alice.filestamp , +which includes both server and client keys. +Copy this file to all group hosts and install a soft link +from the generic +.Pa ntpkey_gq_ Ns Ar alice +to this file. +In addition, on each host bob install a soft link +from generic +.Pa ntpkey_gq_ Ns Ar bob +to this file. +As the GQ scheme updates the GQ parameters file and certificate +at the same time, keys and certificates can be regenerated as needed. +.PP +For the MV scheme, proceed as in the TC scheme to generate keys +and certificates for all group hosts. +For illustration assume trish is the TA, alice one of several trusted hosts +and bob one of her clients. +On TA trish run +.B +V Ar n +p Ar password , +where +\fIn\fR +is the number of revokable keys (typically 5) to produce +the parameter file +.Pa ntpkeys_MVpar_ Ns Ar trish.filestamp +and client key files +.Pa ntpkeys_MVkeyd_ Ns Ar trish.filestamp +where +\fId\fR +is the key number (0 \&< +\fId\fR +\&< +\fIn ) .\fR +Copy the parameter file to alice and install a soft link +from the generic +.Pa ntpkey_mv_ Ns Ar alice +to this file. +Copy one of the client key files to alice for later distribution +to her clients. +It doesn't matter which client key file goes to alice, +since they all work the same way. +Alice copies the client key file to all of her cliens. +On client bob install a soft link from generic +.Pa ntpkey_mvkey_ Ns Ar bob +to the client key file. +As the MV scheme is independent of keys and certificates, +these files can be refreshed as needed. +.Ss Command Line Options +.TP +.BR Fl c Ar scheme +Select certificate message digest/signature encryption scheme. +The +\fIscheme\fR +can be one of the following: +. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , +or +.Cm DSA-SHA1 . +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. +The default without this option is +.Cm RSA-MD5 . +.TP +.BR Fl d +Enable debugging. +This option displays the cryptographic data produced in eye-friendly billboards. +.TP +.BR Fl e +Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +.TP +.BR Fl G +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.TP +.BR Fl g +Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +.TP +.BR Fl H +Generate new host keys, obsoleting any that may exist. +.TP +.BR Fl I +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +.TP +.BR Fl i Ar name +Set the suject name to +\fIname .\fR +This is used as the subject field in certificates +and in the file name for host and sign keys. +.TP +.BR Fl M +Generate MD5 keys, obsoleting any that may exist. +.TP +.BR Fl P +Generate a private certificate. +By default, the program generates public certificates. +.TP +.BR Fl p Ar password +Encrypt generated files containing private data with +\fIpassword\fR +and the DES-CBC algorithm. +.TP +.BR Fl q +Set the password for reading files to password. +.TP +.BR Fl S Oo Cm RSA | DSA Oc +Generate a new sign key of the designated type, +obsoleting any that may exist. +By default, the program uses the host key as the sign key. +.TP +.BR Fl s Ar name +Set the issuer name to +\fIname .\fR +This is used for the issuer field in certificates +and in the file name for identity files. +.TP +.BR Fl T +Generate a trusted certificate. +By default, the program generates a non-trusted certificate. +.TP +.BR Fl V Ar nkeys +Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. +.Ss Random Seed File +All cryptographically sound key generation schemes must have means +to randomize the entropy seed used to initialize +the internal pseudo-random number generator used +by the library routines. +The OpenSSL library uses a designated random seed file for this purpose. +The file must be available when starting the NTP daemon and +.B +program. +If a site supports OpenSSL or its companion OpenSSH, +it is very likely that means to do this are already available. +.PP +It is important to understand that entropy must be evolved +for each generation, for otherwise the random number sequence +would be predictable. +Various means dependent on external events, such as keystroke intervals, +can be used to do this and some systems have built-in entropy sources. +Suitable means are described in the OpenSSL software documentation, +but are outside the scope of this page. +.PP +The entropy seed used by the OpenSSL library is contained in a file, +usually called +.Cm .rnd , +which must be available when starting the NTP daemon +or the +.B +program. +The NTP daemon will first look for the file +using the path specified by the +.Ic randfile +subcommand of the +.Ic crypto +configuration command. +If not specified in this way, or when starting the +.B +program, +the OpenSSL library will look for the file using the path specified +by the +.Ev RANDFILE +environment variable in the user home directory, +whether root or some other user. +If the +.Ev RANDFILE +environment variable is not present, +the library will look for the +.Cm .rnd +file in the user home directory. +If the file is not available or cannot be written, +the daemon exits with a message to the system log and the program +exits with a suitable error message. +.Ss Cryptographic Data Files +All other file formats begin with two lines. +The first contains the file name, including the generated host name +and filestamp. +The second contains the datestamp in conventional Unix date format. +Lines beginning with # are considered comments and ignored by the +.B +program and +.Xr ntpd 8 +daemon. +Cryptographic values are encoded first using ASN.1 rules, +then encrypted if necessary, and finally written PEM-encoded +printable ASCII format preceded and followed by MIME content identifier lines. +.PP +The format of the symmetric keys file is somewhat different +than the other files in the interest of backward compatibility. +Since DES-CBC is deprecated in NTPv4, the only key format of interest +is MD5 alphanumeric strings. +Following hte heard the keys are +entered one per line in the format +.D1 Ar keyno type key +where +\fIkeyno\fR +is a positive integer in the range 1-65,535, +\fItype\fR +is the string MD5 defining the key format and +\fIkey\fR +is the key itself, +which is a printable ASCII string 16 characters or less in length. +Each character is chosen from the 93 printable characters +in the range 0x21 through 0x7f excluding space and the +.Ql # +character. +.PP +Note that the keys used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +programs +are checked against passwords requested by the programs +and entered by hand, so it is generally appropriate to specify these keys +in human readable ASCII format. +.PP +The +.B +program generates a MD5 symmetric keys file +.Pa ntpkey_MD5key_ Ns Ar hostname.filestamp . +Since the file contains private shared keys, +it should be visible only to root and distributed by secure means +to other subnet hosts. +The NTP daemon loads the file +.Pa ntp.keys , +so +.B +installs a soft link from this name to the generated file. +Subsequently, similar soft links must be installed by manual +or automated means on the other subnet hosts. +While this file is not used with the Autokey Version 2 protocol, +it is needed to authenticate some remote configuration commands +used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +utilities. +.SH "OPTIONS" +.TP +.BR \-c " \fIscheme\fP, " \-\-certificate "=" \fIscheme\fP +certificate scheme. +.sp +scheme is one of +RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160, +DSA-SHA, or DSA-SHA1. +Select the certificate message digest/signature encryption scheme. +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. The default without +this option is RSA-MD5. +.TP +.BR \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.BR \-e ", " -\-id\-key +Write IFF or GQ identity keys. +.sp +Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +.TP +.BR \-G ", " -\-gq\-params +Generate GQ parameters and keys. +.sp +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.TP +.BR \-H ", " -\-host\-key +generate RSA host key. +.sp +Generate new host keys, obsoleting any that may exist. +.TP +.BR \-I ", " -\-iffkey +generate IFF parameters. +.sp +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +.TP +.BR \-i " \fIissuer\-name\fP, " \-\-issuer\-name "=" \fIissuer\-name\fP +set issuer name. +.sp +Set the subject name to name. This is used as the subject field +in certificates and in the file name for host and sign keys. +.TP +.BR \-l " \fIlifetime\fP, " \-\-lifetime "=" \fIlifetime\fP +set certificate lifetime. +This option takes an integer number as its argument. +.sp +Set the certificate expiration to lifetime days from now. +.TP +.BR \-M ", " -\-md5key +generate MD5 keys. +.sp +Generate MD5 keys, obsoleting any that may exist. +.TP +.BR \-m " \fImodulus\fP, " \-\-modulus "=" \fImodulus\fP +modulus. +This option takes an integer number as its argument. +The value of \fImodulus\fP is constrained to being: +.in +4 +.nf +.na +in the range 256 through 2048 +.fi +.in -4 +.sp +The number of bits in the prime modulus. The default is 512. +.TP +.BR \-P ", " -\-pvt\-cert +generate PC private certificate. +.sp +Generate a private certificate. By default, the program generates +public certificates. +.TP +.BR \-p " \fIpasswd\fP, " \-\-pvt\-passwd "=" \fIpasswd\fP +output private password. +.sp +Encrypt generated files containing private data with the specified +password and the DES-CBC algorithm. +.TP +.BR \-q " \fIpasswd\fP, " \-\-get\-pvt\-passwd "=" \fIpasswd\fP +input private password. +.sp +Set the password for reading files to the specified password. +.TP +.BR \-S " \fIsign\fP, " \-\-sign\-key "=" \fIsign\fP +generate sign key (RSA or DSA). +.sp +Generate a new sign key of the designated type, obsoleting any +that may exist. By default, the program uses the host key as the +sign key. +.TP +.BR \-s " \fIhost\fP, " \-\-subject\-name "=" \fIhost\fP +set subject name. +.sp +Set the issuer name to name. This is used for the issuer field +in certificates and in the file name for identity files. +.TP +.BR \-T ", " -\-trusted\-cert +trusted certificate (TC scheme). +.sp +Generate a trusted certificate. By default, the program generates +a non-trusted certificate. +.TP +.BR \-V " \fInum\fP, " \-\-mv\-params "=" \fInum\fP +generate MV parameters. +This option takes an integer number as its argument. +.sp +Generate parameters and keys for the Mu-Varadharajan (MV) +identification scheme. +.TP +.BR \-v " \fInum\fP, " \-\-mv\-keys "=" \fInum\fP +update MV keys. +This option takes an integer number as its argument. +.sp +This option has not been fully documented. +.TP +.BR \-? , " \-\-help" +Display usage information and exit. +.TP +.BR \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.TP +.BR \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.TP +.BR \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.BR \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTP_KEYGEN_\fP or \fBNTP_KEYGEN\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.SH USAGE +The +p Ar password +option specifies the write password and +q Ar password +option the read password for previously encrypted files. +The +.B +program prompts for the password if it reads an encrypted file +and the password is missing or incorrect. +If an encrypted file is read successfully and +no write password is specified, the read password is used +as the write password by default. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.BR 0 +Successful program execution. +.TP +.BR 1 +The operation failed or the command syntax was not valid. +.SH "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.SH "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.SH BUGS +It can take quite a while to generate some cryptographic values, +from one to several minutes with modern architectures +such as UltraSPARC and up to tens of minutes to an hour +with older architectures such as SPARC IPC. +.PP +Please report bugs to http://bugs.ntp.org . +.SH NOTES +Portions of this document came from FreeBSD. +.PP +This manual page was \fIAutoGen\fP-erated from the \fBntp-keygen\fP +option definitions. diff --git a/util/ntp-keygen.mdoc.in b/util/ntp-keygen.mdoc.in new file mode 100644 index 000000000..d39e97919 --- /dev/null +++ b/util/ntp-keygen.mdoc.in @@ -0,0 +1,884 @@ +.Dd June 22 2011 +.Dt NTP_KEYGEN @NTP_KEYGEN_MS@ User Commands +.Os Linux 2.6.26-2-686 +.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 22, 2011 at 05:00:16 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-keygen-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntp-keygen +.Nd Create a NTP host key +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +.Pp +All arguments must be options. +.Pp +.Sh DESCRIPTION +This program generates cryptographic data files used by the NTPv4 +authentication and identification schemes. +It generates MD5 key files used in symmetric key cryptography. +In addition, if the OpenSSL software library has been installed, +it generates keys, certificate and identity files used in public key +cryptography. +These files are used for cookie encryption, +digital signature and challenge/response identification algorithms +compatible with the Internet standard security infrastructure. +.Pp +All files are in PEM-encoded printable ASCII format, +so they can be embedded as MIME attachments in mail to other sites +and certificate authorities. +By default, files are not encrypted. +.Pp +The +.Xr ntpd 8 +configuration command +.Ic crypto pw Ar password +specifies the read password for previously encrypted files. +The daemon expires on the spot if the password is missing +or incorrect. +For convenience, if a file has been previously encrypted, +the default read password is the name of the host running +the program. +If the previous write password is specified as the host name, +these files can be read by that host with no explicit password. +.Pp +File names begin with the prefix +.Cm ntpkey_ +and end with the postfix +.Ar _hostname.filestamp , +where +.Ar hostname +is the owner name, usually the string returned +by the Unix gethostname() routine, and +.Ar filestamp +is the NTP seconds when the file was generated, in decimal digits. +This both guarantees uniqueness and simplifies maintenance +procedures, since all files can be quickly removed +by a +.Ic rm ntpkey\&* +command or all files generated +at a specific time can be removed by a +.Ic rm +.Ar \&*filestamp +command. +To further reduce the risk of misconfiguration, +the first two lines of a file contain the file name +and generation date and time as comments. +.Pp +All files are installed by default in the keys directory +.Pa /usr/local/etc , +which is normally in a shared filesystem +in NFS-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.Pp +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.Pp +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.Nm +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.Nm +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.Pp +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.Pp +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.Pp +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.Pp +Installing the keys as root might not work in NFS-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.Pp +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +.Pp +All files are installed by default in the keys directory +.Pa /usr/local/etc , +which is normally in a shared filesystem +in NFS-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.Pp +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.Pp +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.Nm +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.Nm +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.Pp +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.Pp +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.Pp +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.Pp +Installing the keys as root might not work in NFS-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.Pp +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +seconds. +seconds. +s Trusted Hosts and Groups +Each cryptographic configuration involves selection of a signature scheme +and identification scheme, called a cryptotype, +as explained in the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +The default cryptotype uses RSA encryption, MD5 message digest +and TC identification. +First, configure a NTP subnet including one or more low-stratum +trusted hosts from which all other hosts derive synchronization +directly or indirectly. +Trusted hosts have trusted certificates; +all other hosts have nontrusted certificates. +These hosts will automatically and dynamically build authoritative +certificate trails to one or more trusted hosts. +A trusted group is the set of all hosts that have, directly or indirectly, +a certificate trail ending at a trusted host. +The trail is defined by static configuration file entries +or dynamic means described on the +.Sx Automatic NTP Configuration Options +section of +.Xr ntp.conf 5 . +.Pp +On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +.Cm ntpkey +files. +Then run +.Nm +.Fl T +to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +.Fl T +flag to generate keys and nontrusted certificates. +When complete, start the NTP daemons beginning at the lowest stratum +and working up the tree. +It may take some time for Autokey to instantiate the certificate trails +throughout the subnet, but setting up the environment is completely automatic. +.Pp +If it is necessary to use a different sign key or different digest/signature +scheme than the default, run +.Nm +with the +.Fl S Ar type +option, where +.Ar type +is either +.Cm RSA +or +.Cm DSA . +The most often need to do this is when a DSA-signed certificate is used. +If it is necessary to use a different certificate scheme than the default, +run +.Nm +with the +.Fl c Ar scheme +option and selected +.Ar scheme +as needed. +f +.Nm +is run again without these options, it generates a new certificate +using the same scheme and sign key. +.Pp +After setting up the environment it is advisable to update certificates +from time to time, if only to extend the validity interval. +Simply run +.Nm +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +.Xr ntpd 8 +should be restarted. +When +.Xr ntpd 8 +is restarted, it loads any new files and restarts the protocol. +Other dependent hosts will continue as usual until signatures are refreshed, +at which time the protocol is restarted. +.Ss Identity Schemes +As mentioned on the Autonomous Authentication page, +the default TC identity scheme is vulnerable to a middleman attack. +However, there are more secure identity schemes available, +including PC, IFF, GQ and MV described on the +.Qq Identification Schemes +page +(maybe available at +.Li http://www.eecis.udel.edu/%7emills/keygen.html ) . +These schemes are based on a TA, one or more trusted hosts +and some number of nontrusted hosts. +Trusted hosts prove identity using values provided by the TA, +while the remaining hosts prove identity using values provided +by a trusted host and certificate trails that end on that host. +The name of a trusted host is also the name of its sugroup +and also the subject and issuer name on its trusted certificate. +The TA is not necessarily a trusted host in this sense, but often is. +.Pp +In some schemes there are separate keys for servers and clients. +A server can also be a client of another server, +but a client can never be a server for another client. +In general, trusted hosts and nontrusted hosts that operate +as both server and client have parameter files that contain +both server and client keys. +Hosts that operate +only as clients have key files that contain only client keys. +.Pp +The PC scheme supports only one trusted host in the group. +On trusted host alice run +.Nm +.Fl P +.Fl p Ar password +to generate the host key file +.Pa ntpkey_RSAkey_ Ns Ar alice.filestamp +and trusted private certificate file +.Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp . +Copy both files to all group hosts; +they replace the files which would be generated in other schemes. +On each host bob install a soft link from the generic name +.Pa ntpkey_host_ Ns Ar bob +to the host key file and soft link +.Pa ntpkey_cert_ Ns Ar bob +to the private certificate file. +Note the generic links are on bob, but point to files generated +by trusted host alice. +In this scheme it is not possible to refresh +either the keys or certificates without copying them +to all other hosts in the group. +.Pp +For the IFF scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host in the group, +generate the IFF parameter file. +On trusted host alice run +.Nm +.Fl T +.Fl I +.Fl p Ar password +to produce her parameter file +.Pa ntpkey_IFFpar_ Ns Ar alice.filestamp , +which includes both server and client keys. +Copy this file to all group hosts that operate as both servers +and clients and install a soft link from the generic +.Pa ntpkey_iff_ Ns Ar alice +to this file. +If there are no hosts restricted to operate only as clients, +there is nothing further to do. +As the IFF scheme is independent +of keys and certificates, these files can be refreshed as needed. +.Pp +If a rogue client has the parameter file, it could masquerade +as a legitimate server and present a middleman threat. +To eliminate this threat, the client keys can be extracted +from the parameter file and distributed to all restricted clients. +After generating the parameter file, on alice run +.Nm +.Fl e +and pipe the output to a file or mail program. +Copy or mail this file to all restricted clients. +On these clients install a soft link from the generic +.Pa ntpkey_iff_ Ns Ar alice +to this file. +To further protect the integrity of the keys, +each file can be encrypted with a secret password. +.Pp +For the GQ scheme proceed as in the TC scheme to generate keys +and certificates for all group hosts, then for every trusted host +in the group, generate the IFF parameter file. +On trusted host alice run +.Nm +.Fl T +.Fl G +.Fl p Ar password +to produce her parameter file +.Pa ntpkey_GQpar_ Ns Ar alice.filestamp , +which includes both server and client keys. +Copy this file to all group hosts and install a soft link +from the generic +.Pa ntpkey_gq_ Ns Ar alice +to this file. +In addition, on each host bob install a soft link +from generic +.Pa ntpkey_gq_ Ns Ar bob +to this file. +As the GQ scheme updates the GQ parameters file and certificate +at the same time, keys and certificates can be regenerated as needed. +.Pp +For the MV scheme, proceed as in the TC scheme to generate keys +and certificates for all group hosts. +For illustration assume trish is the TA, alice one of several trusted hosts +and bob one of her clients. +On TA trish run +.Nm +.Fl V Ar n +.Fl p Ar password , +where +.Ar n +is the number of revokable keys (typically 5) to produce +the parameter file +.Pa ntpkeys_MVpar_ Ns Ar trish.filestamp +and client key files +.Pa ntpkeys_MVkeyd_ Ns Ar trish.filestamp +where +.Ar d +is the key number (0 \&< +.Ar d +\&< +.Ar n ) . +Copy the parameter file to alice and install a soft link +from the generic +.Pa ntpkey_mv_ Ns Ar alice +to this file. +Copy one of the client key files to alice for later distribution +to her clients. +It doesn't matter which client key file goes to alice, +since they all work the same way. +Alice copies the client key file to all of her cliens. +On client bob install a soft link from generic +.Pa ntpkey_mvkey_ Ns Ar bob +to the client key file. +As the MV scheme is independent of keys and certificates, +these files can be refreshed as needed. +.Ss Command Line Options +.Bl -tag -width indent +.It Fl c Ar scheme +Select certificate message digest/signature encryption scheme. +The +.Ar scheme +can be one of the following: +. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , +or +.Cm DSA-SHA1 . +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. +The default without this option is +.Cm RSA-MD5 . +.It Fl d +Enable debugging. +This option displays the cryptographic data produced in eye-friendly billboards. +.It Fl e +Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +.It Fl G +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.It Fl g +Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +.It Fl H +Generate new host keys, obsoleting any that may exist. +.It Fl I +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +.It Fl i Ar name +Set the suject name to +.Ar name . +This is used as the subject field in certificates +and in the file name for host and sign keys. +.It Fl M +Generate MD5 keys, obsoleting any that may exist. +.It Fl P +Generate a private certificate. +By default, the program generates public certificates. +.It Fl p Ar password +Encrypt generated files containing private data with +.Ar password +and the DES-CBC algorithm. +.It Fl q +Set the password for reading files to password. +.It Fl S Oo Cm RSA | DSA Oc +Generate a new sign key of the designated type, +obsoleting any that may exist. +By default, the program uses the host key as the sign key. +.It Fl s Ar name +Set the issuer name to +.Ar name . +This is used for the issuer field in certificates +and in the file name for identity files. +.It Fl T +Generate a trusted certificate. +By default, the program generates a non-trusted certificate. +.It Fl V Ar nkeys +Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. +.El +.Ss Random Seed File +All cryptographically sound key generation schemes must have means +to randomize the entropy seed used to initialize +the internal pseudo-random number generator used +by the library routines. +The OpenSSL library uses a designated random seed file for this purpose. +The file must be available when starting the NTP daemon and +.Nm +program. +If a site supports OpenSSL or its companion OpenSSH, +it is very likely that means to do this are already available. +.Pp +It is important to understand that entropy must be evolved +for each generation, for otherwise the random number sequence +would be predictable. +Various means dependent on external events, such as keystroke intervals, +can be used to do this and some systems have built-in entropy sources. +Suitable means are described in the OpenSSL software documentation, +but are outside the scope of this page. +.Pp +The entropy seed used by the OpenSSL library is contained in a file, +usually called +.Cm .rnd , +which must be available when starting the NTP daemon +or the +.Nm +program. +The NTP daemon will first look for the file +using the path specified by the +.Ic randfile +subcommand of the +.Ic crypto +configuration command. +If not specified in this way, or when starting the +.Nm +program, +the OpenSSL library will look for the file using the path specified +by the +.Ev RANDFILE +environment variable in the user home directory, +whether root or some other user. +If the +.Ev RANDFILE +environment variable is not present, +the library will look for the +.Cm .rnd +file in the user home directory. +If the file is not available or cannot be written, +the daemon exits with a message to the system log and the program +exits with a suitable error message. +.Ss Cryptographic Data Files +All other file formats begin with two lines. +The first contains the file name, including the generated host name +and filestamp. +The second contains the datestamp in conventional Unix date format. +Lines beginning with # are considered comments and ignored by the +.Nm +program and +.Xr ntpd 8 +daemon. +Cryptographic values are encoded first using ASN.1 rules, +then encrypted if necessary, and finally written PEM-encoded +printable ASCII format preceded and followed by MIME content identifier lines. +.Pp +The format of the symmetric keys file is somewhat different +than the other files in the interest of backward compatibility. +Since DES-CBC is deprecated in NTPv4, the only key format of interest +is MD5 alphanumeric strings. +Following hte heard the keys are +entered one per line in the format +.D1 Ar keyno type key +where +.Ar keyno +is a positive integer in the range 1-65,535, +.Ar type +is the string MD5 defining the key format and +.Ar key +is the key itself, +which is a printable ASCII string 16 characters or less in length. +Each character is chosen from the 93 printable characters +in the range 0x21 through 0x7f excluding space and the +.Ql # +character. +.Pp +Note that the keys used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +programs +are checked against passwords requested by the programs +and entered by hand, so it is generally appropriate to specify these keys +in human readable ASCII format. +.Pp +The +.Nm +program generates a MD5 symmetric keys file +.Pa ntpkey_MD5key_ Ns Ar hostname.filestamp . +Since the file contains private shared keys, +it should be visible only to root and distributed by secure means +to other subnet hosts. +The NTP daemon loads the file +.Pa ntp.keys , +so +.Nm +installs a soft link from this name to the generated file. +Subsequently, similar soft links must be installed by manual +or automated means on the other subnet hosts. +While this file is not used with the Autokey Version 2 protocol, +it is needed to authenticate some remote configuration commands +used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +utilities. +.Sh "OPTIONS" +.Bl -tag +.It \-c " \fIscheme\fP, " \-\-certificate "=" \fIscheme\fP +certificate scheme. +.sp +scheme is one of +RSA-MD2, RSA-MD5, RSA-SHA, RSA-SHA1, RSA-MDC2, RSA-RIPEMD160, +DSA-SHA, or DSA-SHA1. +Select the certificate message digest/signature encryption scheme. +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. The default without +this option is RSA-MD5. +.It \-d ", " -\-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-D " \fIstring\fP, " \-\-set\-debug\-level "=" \fIstring\fP +Set the debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It \-e ", " -\-id\-key +Write IFF or GQ identity keys. +.sp +Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +.It \-G ", " -\-gq\-params +Generate GQ parameters and keys. +.sp +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.It \-H ", " -\-host\-key +generate RSA host key. +.sp +Generate new host keys, obsoleting any that may exist. +.It \-I ", " -\-iffkey +generate IFF parameters. +.sp +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +.It \-i " \fIissuer\-name\fP, " \-\-issuer\-name "=" \fIissuer\-name\fP +set issuer name. +.sp +Set the subject name to name. This is used as the subject field +in certificates and in the file name for host and sign keys. +.It \-l " \fIlifetime\fP, " \-\-lifetime "=" \fIlifetime\fP +set certificate lifetime. +This option takes an integer number as its argument. +.sp +Set the certificate expiration to lifetime days from now. +.It \-M ", " -\-md5key +generate MD5 keys. +.sp +Generate MD5 keys, obsoleting any that may exist. +.It \-m " \fImodulus\fP, " \-\-modulus "=" \fImodulus\fP +modulus. +This option takes an integer number as its argument. +The value of \fImodulus\fP is constrained to being: +.in +4 +.nf +.na +in the range 256 through 2048 +.fi +.in -4 +.sp +The number of bits in the prime modulus. The default is 512. +.It \-P ", " -\-pvt\-cert +generate PC private certificate. +.sp +Generate a private certificate. By default, the program generates +public certificates. +.It \-p " \fIpasswd\fP, " \-\-pvt\-passwd "=" \fIpasswd\fP +output private password. +.sp +Encrypt generated files containing private data with the specified +password and the DES-CBC algorithm. +.It \-q " \fIpasswd\fP, " \-\-get\-pvt\-passwd "=" \fIpasswd\fP +input private password. +.sp +Set the password for reading files to the specified password. +.It \-S " \fIsign\fP, " \-\-sign\-key "=" \fIsign\fP +generate sign key (RSA or DSA). +.sp +Generate a new sign key of the designated type, obsoleting any +that may exist. By default, the program uses the host key as the +sign key. +.It \-s " \fIhost\fP, " \-\-subject\-name "=" \fIhost\fP +set subject name. +.sp +Set the issuer name to name. This is used for the issuer field +in certificates and in the file name for identity files. +.It \-T ", " -\-trusted\-cert +trusted certificate (TC scheme). +.sp +Generate a trusted certificate. By default, the program generates +a non-trusted certificate. +.It \-V " \fInum\fP, " \-\-mv\-params "=" \fInum\fP +generate MV parameters. +This option takes an integer number as its argument. +.sp +Generate parameters and keys for the Mu-Varadharajan (MV) +identification scheme. +.It \-v " \fInum\fP, " \-\-mv\-keys "=" \fInum\fP +update MV keys. +This option takes an integer number as its argument. +.sp +This option has not been fully documented. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \-> " [\fIrcfile\fP]," " \-\-save-opts" "[=\fIrcfile\fP]" +Save the option state to \fIrcfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +.It \-< " \fIrcfile\fP," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts" +Load options from \fIrcfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTP_KEYGEN_\fP or \fBNTP_KEYGEN\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE +The +.Fl p Ar password +option specifies the write password and +.Fl q Ar password +option the read password for previously encrypted files. +The +.Nm +program prompts for the password if it reads an encrypted file +and the password is missing or incorrect. +If an encrypted file is read successfully and +no write password is specified, the read password is used +as the write password by default. +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh "AUTHORS" +The University of Delaware, David L. Mills, and/or others +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh BUGS +It can take quite a while to generate some cryptographic values, +from one to several minutes with modern architectures +such as UltraSPARC and up to tens of minutes to an hour +with older architectures such as SPARC IPC. +.Pp +Please report bugs to http://bugs.ntp.org . +.Sh NOTES +Portions of this document came from FreeBSD. +.Pp +This manual page was \fIAutoGen\fP-erated from the \fBntp-keygen\fP +option definitions.