From: Harlan Stenn Date: Tue, 17 Apr 2012 09:05:13 +0000 (-0700) Subject: Merge bk://bk.ntp.org/ntp-dev X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b038bad213902c91a808be776bea8b519aed9c46;p=thirdparty%2Fntp.git Merge bk://bk.ntp.org/ntp-dev into stenn.ntp.org:/a/etc/amd.stage/thump2-g3/export/ntp/home/stenn/ntp-dev-autogen bk: 4f8d324966NOBd2A1y4uQQ8SxV0n9g --- b038bad213902c91a808be776bea8b519aed9c46 diff --cc ChangeLog index 41be3f2ed4,d1d7df3085..f48f009225 --- a/ChangeLog +++ b/ChangeLog @@@ -1,5 -1,7 +1,9 @@@ +* Upgrade to autogen-5.16 and libopts-36.4.11. +* Upgrade to autogen-5.15. + (4.2.7p272) 2012/04/14 Released by Harlan Stenn + * LCRYPTO is gone - replace with VER_SUFFIX. + * Change the link order for ntpsntpd. + * Remove extra 'nlist' check from configure.ac. (4.2.7p271) 2012/04/11 Released by Harlan Stenn * [Bug 1122] openssl detection via pkg-config fails when no additional -Idir flags are needed. diff --cc ntpd/invoke-ntpd.texi index 25c8f4a35f,0000000000..22b0f55542 mode 100644,000000..100644 --- a/ntpd/invoke-ntpd.texi +++ b/ntpd/invoke-ntpd.texi @@@ -1,1055 -1,0 +1,1055 @@@ +@node ntpd Invocation +@section Invoking ntpd +@pindex ntpd +@cindex NTP daemon program +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-ntpd.texi) +# +# It has been AutoGen-ed April 14, 2012 at 12:21:50 AM by AutoGen 5.16pre18 +# From the definitions ntpd-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + + + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpd} program. +This software is released under the NTP license, . + +@menu +* ntpd usage:: ntpd help/usage (-?) +* ntpd ipv4:: ipv4 option (-4) +* ntpd ipv6:: ipv6 option (-6) +* ntpd authreq:: authreq option (-a) +* ntpd authnoreq:: authnoreq option (-A) +* ntpd configfile:: configfile option (-c) +* ntpd debug-level:: debug-level option (-d) +* ntpd set-debug-level:: set-debug-level option (-D) +* ntpd driftfile:: driftfile option (-f) +* ntpd panicgate:: panicgate option (-g) +* ntpd jaildir:: jaildir option (-i) +* ntpd interface:: interface option (-I) +* ntpd keyfile:: keyfile option (-k) +* ntpd logfile:: logfile option (-l) +* ntpd novirtualips:: novirtualips option (-L) +* ntpd modifymmtimer:: modifymmtimer option (-M) +* ntpd nice:: nice option (-N) +* ntpd pidfile:: pidfile option (-p) +* ntpd priority:: priority option (-P) +* ntpd quit:: quit option (-q) +* ntpd propagationdelay:: propagationdelay option (-r) +* ntpd saveconfigquit:: saveconfigquit option +* ntpd statsdir:: statsdir option (-s) +* ntpd trustedkey:: trustedkey option (-t) +* ntpd user:: user option (-u) +* ntpd updateinterval:: updateinterval option (-U) +* ntpd wait-sync:: wait-sync option (-w) +* ntpd slew:: slew option (-x) +* ntpd usepcc:: usepcc option +* ntpd pccfreq:: pccfreq option +* ntpd config:: presetting/configuring ntpd +* ntpd exit status:: exit status +* ntpd Description:: Description +* ntpd Usage:: Usage +* ntpd Files:: Files +* ntpd See Also:: See Also +* ntpd Bugs:: Bugs +* ntpd Notes:: Notes +@end menu + +@node ntpd usage +@subsection ntpd help/usage (-?) +@cindex ntpd help + +This is the automatically generated usage text for ntpd. +The text printed is the same whether for the @code{help} option (-?) or the @code{more-help} option (-!). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example - ntpd - NTP daemon program - Ver. 4.2.7p271 ++ntpd - NTP daemon program - Ver. 4.2.7p272 +USAGE: ntpd [ - [] | --[@{=| @}] ]... \ + [ ... ] + Flg Arg Option-Name Description + -4 no ipv4 Force IPv4 DNS name resolution + - prohibits these options: + ipv6 + -6 no ipv6 Force IPv6 DNS name resolution + - prohibits these options: + ipv4 + -a no authreq Require crypto authentication + - prohibits these options: + authnoreq + -A no authnoreq Do not require crypto authentication + - prohibits these options: + authreq + -b no bcastsync Allow us to sync to broadcast servers + -c Str configfile configuration file name + -d no debug-level Increase output debug message level + - may appear multiple times + -D Str set-debug-level Set the output debug message level + - may appear multiple times + -f Str driftfile frequency drift file name + -g no panicgate Allow the first adjustment to be Big + - may appear multiple times + -i --- jaildir built without --enable-clockctl or --enable-linuxcaps + -I Str interface Listen on an interface name or address + - may appear multiple times + -k Str keyfile path to symmetric keys + -l Str logfile path to the log file + -L no novirtualips Do not listen to virtual interfaces + -n no nofork Do not fork + - prohibits these options: + wait-sync + -N no nice Run at high priority + -p Str pidfile path to the PID file + -P Num priority Process priority + -q no quit Set the time and quit + - prohibits these options: + saveconfigquit + wait-sync + -r Str propagationdelay Broadcast/propagation delay + Str saveconfigquit Save parsed configuration and quit + - prohibits these options: + quit + wait-sync + -s Str statsdir Statistics file location + -t Str trustedkey Trusted key number + - may appear multiple times + -u --- user built without --enable-clockctl or --enable-linuxcaps + -U Num updateinterval interval in seconds between scans for new or dropped interfaces + Str var make ARG an ntp variable (RW) + - may appear multiple times + Str dvar make ARG an ntp variable (RW|DEF) + - may appear multiple times + -w Num wait-sync Seconds to wait for first clock sync + - prohibits these options: + nofork + quit + saveconfigquit + -x no slew Slew up to 600 seconds + -! opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + + + +The following option preset mechanisms are supported: + - examining environment variables named NTPD_* + +please send bug reports to: http://bugs.ntp.org, bugs@@ntp.org +@end example +@exampleindent 4 + +@node ntpd ipv4 +@subsection ipv4 option (-4) +@cindex ntpd-ipv4 + +This is the ``force ipv4 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv6. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +@node ntpd ipv6 +@subsection ipv6 option (-6) +@cindex ntpd-ipv6 + +This is the ``force ipv6 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv4. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +@node ntpd authreq +@subsection authreq option (-a) +@cindex ntpd-authreq + +This is the ``require crypto authentication'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +authnoreq. +@end itemize + +Require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is the default. +@node ntpd authnoreq +@subsection authnoreq option (-A) +@cindex ntpd-authnoreq + +This is the ``do not require crypto authentication'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +authreq. +@end itemize + +Do not require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is almost never a good idea. +@node ntpd configfile +@subsection configfile option (-c) +@cindex ntpd-configfile + +This is the ``configuration file name'' option. +This option takes an argument string. +The name and path of the configuration file, +/etc/ntp.conf +by default. +@node ntpd debug-level +@subsection debug-level option (-d) +@cindex ntpd-debug-level + +This is the ``increase output debug message level'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@item +must be compiled in by defining @code{DEBUG} during the compilation. +@end itemize + +Increase the debugging message output level. +@node ntpd set-debug-level +@subsection set-debug-level option (-D) +@cindex ntpd-set-debug-level + +This is the ``set the output debug message level'' option. +This option takes an argument string. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@item +must be compiled in by defining @code{DEBUG} during the compilation. +@end itemize + +Set the output debugging level. Can be supplied multiple times, +but each overrides the previous value(s). +@node ntpd driftfile +@subsection driftfile option (-f) +@cindex ntpd-driftfile + +This is the ``frequency drift file name'' option. +This option takes an argument string. +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. +@node ntpd panicgate +@subsection panicgate option (-g) +@cindex ntpd-panicgate + +This is the ``allow the first adjustment to be big'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +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. +@node ntpd jaildir +@subsection jaildir option (-i) +@cindex ntpd-jaildir + +This is the ``jail directory'' option. +This option takes an argument string. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_DROPROOT} during the compilation. +@end itemize + +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 +). +@node ntpd interface +@subsection interface option (-I) +@cindex ntpd-interface + +This is the ``listen on an interface name or address'' option. +This option takes an argument string @file{iface}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +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. +@node ntpd keyfile +@subsection keyfile option (-k) +@cindex ntpd-keyfile + +This is the ``path to symmetric keys'' option. +This option takes an argument string. +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. +@node ntpd logfile +@subsection logfile option (-l) +@cindex ntpd-logfile + +This is the ``path to the log file'' option. +This option takes an argument string. +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. +@node ntpd novirtualips +@subsection novirtualips option (-L) +@cindex ntpd-novirtualips + +This is the ``do not listen to virtual interfaces'' option. +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. +@node ntpd modifymmtimer +@subsection modifymmtimer option (-M) +@cindex ntpd-modifymmtimer + +This is the ``modify multimedia timer (windows only)'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SYS_WINNT} during the compilation. +@end itemize + +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. +@node ntpd nice +@subsection nice option (-N) +@cindex ntpd-nice + +This is the ``run at high priority'' option. +To the extent permitted by the operating system, run +ntpd +at the highest priority. +@node ntpd pidfile +@subsection pidfile option (-p) +@cindex ntpd-pidfile + +This is the ``path to the pid file'' option. +This option takes an argument string. +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. +@node ntpd priority +@subsection priority option (-P) +@cindex ntpd-priority + +This is the ``process priority'' option. +This option takes an argument number. +To the extent permitted by the operating system, run +ntpd +at the specified +sched_setscheduler(SCHED_FIFO) +priority. +@node ntpd quit +@subsection quit option (-q) +@cindex ntpd-quit + +This is the ``set the time and quit'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +saveconfigquit, wait-sync. +@end itemize + +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. +@node ntpd propagationdelay +@subsection propagationdelay option (-r) +@cindex ntpd-propagationdelay + +This is the ``broadcast/propagation delay'' option. +This option takes an argument string. +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. +@node ntpd saveconfigquit +@subsection saveconfigquit option +@cindex ntpd-saveconfigquit + +This is the ``save parsed configuration and quit'' option. +This option takes an argument string. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SAVECONFIG} during the compilation. +@item +must not appear in combination with any of the following options: +quit, wait-sync. +@end itemize + +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. +@node ntpd statsdir +@subsection statsdir option (-s) +@cindex ntpd-statsdir + +This is the ``statistics file location'' option. +This option takes an argument string. +Specify the directory path for files created by the statistics facility. +This is the same operation as the +statsdir statsdir +configuration file directive. +@node ntpd trustedkey +@subsection trustedkey option (-t) +@cindex ntpd-trustedkey + +This is the ``trusted key number'' option. +This option takes an argument string @file{tkey}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +Add a key number to the trusted key list. +@node ntpd user +@subsection user option (-u) +@cindex ntpd-user + +This is the ``run as userid (or userid:groupid)'' option. +This option takes an argument string. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_DROPROOT} during the compilation. +@end itemize + +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 +). +@node ntpd updateinterval +@subsection updateinterval option (-U) +@cindex ntpd-updateinterval + +This is the ``interval in seconds between scans for new or dropped interfaces'' option. +This option takes an argument number. +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. +@node ntpd wait-sync +@subsection wait-sync option (-w) +@cindex ntpd-wait-sync + +This is the ``seconds to wait for first clock sync'' option. +This option takes an argument number. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_WORKING_FORK} during the compilation. +@item +must not appear in combination with any of the following options: +nofork, quit, saveconfigquit. +@end itemize + +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. +@node ntpd slew +@subsection slew option (-x) +@cindex ntpd-slew + +This is the ``slew up to 600 seconds'' option. +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. +@node ntpd usepcc +@subsection usepcc option +@cindex ntpd-usepcc + +This is the ``use cpu cycle counter (windows only)'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SYS_WINNT} during the compilation. +@end itemize + +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. +@node ntpd pccfreq +@subsection pccfreq option +@cindex ntpd-pccfreq + +This is the ``force cpu cycle counter use (windows only)'' option. +This option takes an argument string. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SYS_WINNT} during the compilation. +@end itemize + +Force substitution the CPU counter for QueryPerformanceCounter. +The CPU counter (RDTSC on x86) is used unconditionally with the +given frequency (in Hz). + + +@node ntpd config +@subsection presetting/configuring ntpd + +Any option that is not marked as @i{not presettable} may be preset by +loading values from environment variables named @code{NTPD} and @code{NTPD_}. @code{} must be one of +the options listed above in upper case and segmented with underscores. +The @code{NTPD} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the +first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node ntpd exit status +@subsection ntpd exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@end table +@node ntpd Description +@subsection ntpd Description +The +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. +The +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. +Ordinarily, +reads the +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. +If NetInfo support is built into +then +will attempt to read its configuration from the +NetInfo if the default +file cannot be read and no file is +specified by the +option. +Various internal +variables can be displayed and +configuration options altered while the +is running +using the +and +utility programs. +When +starts it looks at the value of +and if zero +will set the +to 022. +@node ntpd Usage +@subsection ntpd Usage +The +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 +keyword with the +configuration +command, as described in +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 +detects that the time on the host +is more than 1000s from the server time, +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 +to exit with a panic message to +the system log. +The +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 +to exit anyway. +Under ordinary conditions, +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 +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. +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 +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 +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 +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. +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, +enters the same state as when the +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 +comes to mind), there may be occasional +step/slew corrections and subsequent frequency corrections. +It +helps in these cases to use the +keyword when +configuring the server, but +ONLY +when you have permission to do so from the owner of the target host. +Finally, +in the past many startup scripts would run +to get the system clock close to correct before starting +but this was never more than a mediocre hack and is no longer needed. +There is a way to start +that often addresses all of the problems mentioned above. +First, use the +option on your +entries. +If you can also keep a good +file then +will effectively "warm-start" and your system's clock will +be stable in under 11 seconds' time. +As soon as possible in the startup sequence, start +with at least the +and perhaps the +options. +Then, +start the rest of your "normal" processes. +This will give +as much time as possible to get the system's clock synchronized and stable. +Finally, +if you have processes like +or database servers +that require +monotonically-increasing time, +run +as late as possible in the boot sequence +(perhaps with the +flag) +and after +exits successfully +it is as safe as it will ever be to start any process that require +stable time. +The +behavior at startup depends on whether the +frequency file, usually +exists. +This file +contains the latest estimate of clock frequency error. +When the +is started and the file does not exist, the +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 +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 +is started and the file does exist, the +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. +The +utility can operate in any of several modes, including +symmetric active/passive, client/server broadcast/multicast and +manycast, as described in the +page +(available as part of the HTML documentation +provided in +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. +By default, +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. +In some cases it may not be practical for +to run +continuously. +A common workaround has been to run the +program from a +job at designated +times. +However, this program does not have the crafted signal +processing, error checking and mitigation algorithms of +The +option is intended for this purpose. +Setting this option will cause +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 +keyword with the +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 +program may be +retired. +When kernel support is available to discipline the clock +frequency, which is the case for stock Solaris, Tru64, Linux and +a useful feature is available to discipline the clock +frequency. +First, +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 +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. +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 +command to a value not less than 16 s. +This value is used for all +configured associations, unless overridden by the +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. +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 +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. +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. +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. +The filter is activated by the +command and +keyword, as described in +@node ntpd Files +@subsection ntpd Files +@table @samp +@item Pa +the default name of the configuration file +@item Pa +the default name of the drift file +@item Pa +the default name of the key file + +@end multitable +@node ntpd See Also +@subsection ntpd See Also +In addition to the manual pages provided, +comprehensive documentation is available on the world wide web +at +A snapshot of this documentation is available in HTML format in +@node ntpd Bugs +@subsection ntpd Bugs +The +utility has gotten rather fat. +While not huge, it has gotten +larger than might be desirable for an elevated-priority +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. +@node ntpd Notes +@subsection ntpd Notes +Portions of this document came from FreeBSD. diff --cc ntpdc/invoke-ntpdc.texi index 350d8a5e60,0000000000..fc4207bfaf mode 100644,000000..100644 --- a/ntpdc/invoke-ntpdc.texi +++ b/ntpdc/invoke-ntpdc.texi @@@ -1,825 -1,0 +1,825 @@@ +@node ntpdc Invocation +@section Invoking ntpdc +@pindex ntpdc +@cindex vendor-specific NTPD control program +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-ntpdc.texi) +# +# It has been AutoGen-ed April 14, 2012 at 12:22:39 AM by AutoGen 5.16pre18 +# From the definitions ntpdc-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + + + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpdc} program. +This software is released under the NTP license, . + +@menu +* ntpdc usage:: ntpdc help/usage (-?) +* ntpdc ipv4:: ipv4 option (-4) +* ntpdc ipv6:: ipv6 option (-6) +* ntpdc command:: command option (-c) +* ntpdc interactive:: interactive option (-i) +* ntpdc listpeers:: listpeers option (-l) +* ntpdc numeric:: numeric option (-n) +* ntpdc peers:: peers option (-p) +* ntpdc showpeers:: showpeers option (-s) +* ntpdc config:: presetting/configuring ntpdc +* ntpdc exit status:: exit status +* ntpdc Description:: Description +* ntpdc Usage:: Usage +* ntpdc See Also:: See Also +* ntpdc Authors:: Authors +* ntpdc Bugs:: Bugs +@end menu + +@node ntpdc usage +@subsection ntpdc help/usage (-?) +@cindex ntpdc help + +This is the automatically generated usage text for ntpdc. +The text printed is the same whether for the @code{help} option (-?) or the @code{more-help} option (-!). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example - ntpdc - vendor-specific NTPD control program - Ver. 4.2.7p271 ++ntpdc - vendor-specific NTPD control program - Ver. 4.2.7p272 +USAGE: ntpdc [ - [] | --[@{=| @}] ]... [ host ...] + Flg Arg Option-Name Description + -4 no ipv4 Force IPv4 DNS name resolution + - prohibits these options: + ipv6 + -6 no ipv6 Force IPv6 DNS name resolution + - prohibits these options: + ipv4 + -c Str command run a command and exit + - may appear multiple times + -d no debug-level Increase debug verbosity level + - may appear multiple times + -D Str set-debug-level Set the debug verbosity level + - may appear multiple times + -i no interactive Force ntpq to operate in interactive mode + - prohibits these options: + command + listpeers + peers + showpeers + -l no listpeers Print a list of the peers + - prohibits these options: + command + -n no numeric numeric host addresses + -p no peers Print a list of the peers + - prohibits these options: + command + -s no showpeers Show a list of the peers + - prohibits these options: + command + opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + -> opt save-opts Save the option state to a config file + -< Str load-opts Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + + + +The following option preset mechanisms are supported: + - reading file $HOME/.ntprc + - reading file ./.ntprc + - examining environment variables named NTPDC_* + +please send bug reports to: http://bugs.ntp.org, bugs@@ntp.org +@end example +@exampleindent 4 + +@node ntpdc ipv4 +@subsection ipv4 option (-4) +@cindex ntpdc-ipv4 + +This is the ``force ipv4 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv6. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +@node ntpdc ipv6 +@subsection ipv6 option (-6) +@cindex ntpdc-ipv6 + +This is the ``force ipv6 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv4. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +@node ntpdc command +@subsection command option (-c) +@cindex ntpdc-command + +This is the ``run a command and exit'' option. +This option takes an argument string @file{cmd}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +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). +@node ntpdc interactive +@subsection interactive option (-i) +@cindex ntpdc-interactive + +This is the ``force ntpq to operate in interactive mode'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +command, listpeers, peers, showpeers. +@end itemize + +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +@node ntpdc listpeers +@subsection listpeers option (-l) +@cindex ntpdc-listpeers + +This is the ``print a list of the peers'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +command. +@end itemize + +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. +@node ntpdc numeric +@subsection numeric option (-n) +@cindex ntpdc-numeric + +This is the ``numeric host addresses'' option. +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +@node ntpdc peers +@subsection peers option (-p) +@cindex ntpdc-peers + +This is the ``print a list of the peers'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +command. +@end itemize + +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. +@node ntpdc showpeers +@subsection showpeers option (-s) +@cindex ntpdc-showpeers + +This is the ``show a list of the peers'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +command. +@end itemize + +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. + + +@node ntpdc config +@subsection presetting/configuring ntpdc + +Any option that is not marked as @i{not presettable} may be preset by +loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTPDC} and @code{NTPDC_}. @code{} must be one of +the options listed above in upper case and segmented with underscores. +The @code{NTPDC} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$HOME +@item +$PWD +@end itemize +The environment variables @code{HOME}, and @code{PWD} +are expanded and replaced when @file{ntpdc} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.ntprc} is searched for +within that directory and processed. + + +Configuration files may be in a wide variety of formats. +The basic format is an option name followed by a value (argument) on the +same line. Values may be separated from the option name with a colon, +equal sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + +Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: +@example +[NTPDC] +@end example +@noindent +or by +@example + +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example + + ...<...>... + +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{AutoOpts} does provide a means for searching +the associated name/value pair list (see: optionFindValue). + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the +first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node ntpdc exit status +@subsection ntpdc exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table +@node ntpdc Description +@subsection ntpdc Description +is a utility program used to query +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 +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 +@node ntpdc Usage +@subsection ntpdc Usage +If one or more request options are included on the command line +when +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, +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 +utility will prompt for +commands if the standard input is a terminal device. +The +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 +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. +The operation of +are specific to the particular +implementation of the +daemon and can be expected to +work only with this and maybe some previous versions of the daemon. +Requests from a remote +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. +Note that in contexts where a host name is expected, a +qualifier preceding the host name forces DNS resolution to the IPv4 namespace, +while a +qualifier forces DNS resolution to the IPv6 namespace. +Specifying a command line option other than +or +will cause the specified query (queries) to be sent to +the indicated host(s) immediately. +Otherwise, +will +attempt to read interactive format commands from the standard +input. +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 +followed by a file name, to the command line. +A number of interactive format commands are executed entirely +within the +utility itself and do not result in NTP +mode 7 requests being sent to a server. +These are described +following. +@table @samp +@item Ic +@item Ic +A +will print a list of all the command +keywords known to this incarnation of +A +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +than this manual +page. +@item Ic +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. +@item Ic +Set the host to which future queries will be sent. +Hostname may +be either a host name or a numeric address. +@item Ic +If +is specified, host names are printed in +information displays. +If +is specified, numeric +addresses are printed instead. +The default is +unless +modified using the command line +switch. +@item Ic +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. +@item Ic +Exit +@item Ic +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. +@item Ic +Specify a timeout period for responses to server queries. +The +default is about 8000 milliseconds. +Note that since +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. + +@end multitable +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. +@table @samp +@item Ic +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. +@item Ic +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. +The character in the left margin indicates the mode this peer +entry is operating in. +A +denotes symmetric active, a +indicates symmetric passive, a +means the +remote server is being polled in client mode, a +indicates that the server is broadcasting to this address, a +denotes that the remote peer is sending broadcasts and a +denotes that the remote peer is sending broadcasts and a +marks the peer the server is currently synchronizing +to. +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 +On +only IP-addresses +will be displayed. +@item Ic +A slightly different peer summary list. +Identical to the output +of the +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 +indicates that this peer was cast off in the falseticker +detection, while a +indicates that the peer made it +through. +A +denotes the peer the server is currently +synchronizing with. +@item Ic +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. +@item Ic +Show per-peer statistic counters associated with the specified +peer(s). +@item Ic +Obtain and print information concerning a peer clock. +The +values obtained provide information on the setting of fudge factors +and other clock performance information. +@item Ic +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. +@item Ic +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 +is the last offset given to the +loop filter by the packet processing code. +The +is the frequency error of the local clock in parts-per-million +(ppm). +The +controls the stiffness of the +phase-lock loop and thus the speed at which it can adapt to +oscillator drift. +The +value is the number +of seconds which have elapsed since the last sample offset was +given to the loop filter. +The +and +options specify the format in which this +information is to be printed, with +as the +default. +@item Ic +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. +The +show various system flags, some of +which can be set and cleared by the +and +configuration commands, respectively. +These are +the +and +flags. +See the +documentation for the meaning of these flags. +There +are two additional flags which are read only, the +and +These flags indicate +the synchronization status when the precision time kernel +modifications are in use. +The +indicates that +the local clock is being disciplined by the kernel, while the +indicates the kernel discipline is provided by the PPS +signal. +The +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 +may be +incorrect. +The +shows the default broadcast delay, +as set by the +configuration command. +The +shows the default authentication delay, +as set by the +configuration command. +@item Ic +Print statistics counters maintained in the protocol +module. +@item Ic +Print statistics counters related to memory allocation +code. +@item Ic +Print statistics counters maintained in the input-output +module. +@item Ic +Print statistics counters maintained in the timer/event queue +support code. +@item Ic +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. +@item Ic +Obtain and print traffic counts collected and maintained by the +monitor facility. +The version number should not normally need to be +specified. +@item Ic +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. + +@end multitable +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 +This can be done using the +and +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. +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. +The following commands all make authenticated requests. +@table @samp +@item Xo +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 +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 +can be 1, 2 or 3 and defaults to 3. +The +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. +@item Xo +Identical to the addpeer command, except that the operating +mode is client. +@item Xo +Identical to the addpeer command, except that the operating +mode is broadcast. +In this case a valid key identifier and key are +required. +The +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. +@item Ic +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. +@item Xo +This command provides a way to set certain data for a reference +clock. +See the source listing for further information. +@item Xo +@item Xo +These commands operate in the same way as the +and +configuration file commands of +@table @samp +@item Cm +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. +@item Cm +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. +@item Cm +Enables the calibrate feature for reference clocks. +The default for this flag is disable. +@item Cm +Enables the kernel time discipline, if available. +The default for this flag is enable if support is available, otherwise disable. +@item Cm +Enables the monitoring facility. +See the +program and the monlist command or further information. +The default for this flag is enable. +@item Cm +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. +@item Cm +Enables the pulse-per-second (PPS) signal when frequency +and time is disciplined by the precision time kernel modifications. +See the +(available as part of the HTML documentation +provided in +page for further information. +The default for this flag is disable. +@item Cm +Enables the statistics facility. +See the +section of +for further information. +The default for this flag is disable. + +@end multitable +This command operates in the same way as the +configuration file commands of +Unrestrict the matching entry from the restrict list. +Delete the matching entry from the restrict list. +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 +configuration file). +This +allows encryption keys to be changed without restarting the +server. +These commands operate in the same way as the +and +configuration file +commands of +Returns information concerning the authentication module, +including known keys and counts of encryptions and decryptions +which have been done. +Display the traps set in the server. +See the source listing for +further information. +Set a trap for asynchronous messages. +See the source listing +for further information. +Clear a trap for asynchronous messages. +See the source listing +for further information. +Clear the statistics counters in various modules of the server. +See the source listing for further information. + +@end multitable +@node ntpdc See Also +@subsection ntpdc See Also +@node ntpdc Authors +@subsection ntpdc Authors +The formatting directives in this document came from FreeBSD. +@node ntpdc Bugs +@subsection ntpdc Bugs +The +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. +Please report bugs to http://bugs.ntp.org . diff --cc ntpq/invoke-ntpq.texi index e6930a9bac,0000000000..55cb707ccf mode 100644,000000..100644 --- a/ntpq/invoke-ntpq.texi +++ b/ntpq/invoke-ntpq.texi @@@ -1,481 -1,0 +1,481 @@@ +@node ntpq Invocation +@section Invoking ntpq +@pindex ntpq +@cindex standard NTP query program +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-ntpq.texi) +# +# It has been AutoGen-ed April 14, 2012 at 12:22:51 AM by AutoGen 5.16pre18 +# From the definitions ntpq-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpq} program. +This software is released under the NTP license, . + +@menu +* ntpq usage:: ntpq help/usage (-?) +* ntpq ipv4:: ipv4 option (-4) +* ntpq ipv6:: ipv6 option (-6) +* ntpq command:: command option (-c) +* ntpq peers:: peers option (-p) +* ntpq interactive:: interactive option (-i) +* ntpq numeric:: numeric option (-n) +* ntpq old-rv:: old-rv option +* ntpq config:: presetting/configuring ntpq +* ntpq exit status:: exit status +* ntpq Description:: Description +@end menu + +@node ntpq usage +@subsection ntpq help/usage (-?) +@cindex ntpq help + +This is the automatically generated usage text for ntpq. +The text printed is the same whether for the @code{help} option (-?) or the @code{more-help} option (-!). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example - ntpq - standard NTP query program - Ver. 4.2.7p271 ++ntpq - standard NTP query program - Ver. 4.2.7p272 +USAGE: ntpq [ - [] | --[@{=| @}] ]... [ host ...] + Flg Arg Option-Name Description + -4 no ipv4 Force IPv4 DNS name resolution + - prohibits these options: + ipv6 + -6 no ipv6 Force IPv6 DNS name resolution + - prohibits these options: + ipv4 + -c Str command run a command and exit + - may appear multiple times + -d no debug-level Increase debug verbosity level + - may appear multiple times + -D Str set-debug-level Set the debug verbosity level + - may appear multiple times + -p no peers Print a list of the peers + - prohibits these options: + interactive + -i no interactive Force ntpq to operate in interactive mode + - prohibits these options: + command + peers + -n no numeric numeric host addresses + no old-rv Always output status line with readvar + opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + -> opt save-opts Save the option state to a config file + -< Str load-opts Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +The following option preset mechanisms are supported: + - reading file $HOME/.ntprc + - reading file ./.ntprc + - examining environment variables named NTPQ_* + +please send bug reports to: http://bugs.ntp.org, bugs@@ntp.org +@end example +@exampleindent 4 + +@node ntpq ipv4 +@subsection ipv4 option (-4) +@cindex ntpq-ipv4 + +This is the ``force ipv4 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv6. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +@node ntpq ipv6 +@subsection ipv6 option (-6) +@cindex ntpq-ipv6 + +This is the ``force ipv6 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv4. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +@node ntpq command +@subsection command option (-c) +@cindex ntpq-command + +This is the ``run a command and exit'' option. +This option takes an argument string @file{cmd}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +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). +@node ntpq peers +@subsection peers option (-p) +@cindex ntpq-peers + +This is the ``print a list of the peers'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +interactive. +@end itemize + +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. +@node ntpq interactive +@subsection interactive option (-i) +@cindex ntpq-interactive + +This is the ``force ntpq to operate in interactive mode'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +command, peers. +@end itemize + +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +@node ntpq numeric +@subsection numeric option (-n) +@cindex ntpq-numeric + +This is the ``numeric host addresses'' option. +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +@node ntpq old-rv +@subsection old-rv option +@cindex ntpq-old-rv + +This is the ``always output status line with readvar'' option. +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. + + +@node ntpq config +@subsection presetting/configuring ntpq + +Any option that is not marked as @i{not presettable} may be preset by +loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTPQ} and @code{NTPQ_}. @code{} must be one of +the options listed above in upper case and segmented with underscores. +The @code{NTPQ} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$HOME +@item +$PWD +@end itemize +The environment variables @code{HOME}, and @code{PWD} +are expanded and replaced when @file{ntpq} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.ntprc} is searched for +within that directory and processed. + + +Configuration files may be in a wide variety of formats. +The basic format is an option name followed by a value (argument) on the +same line. Values may be separated from the option name with a colon, +equal sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + +Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: +@example +[NTPQ] +@end example +@noindent +or by +@example + +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example + + ...<...>... + +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{AutoOpts} does provide a means for searching +the associated name/value pair list (see: optionFindValue). + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the +first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node ntpq exit status +@subsection ntpq exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table +@node ntpq Description +@subsection ntpq Description + +The +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 +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 +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, +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 +utility will prompt for +commands if the standard input is a terminal device. + +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 +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 +or +will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. +Otherwise, +will attempt to read +interactive format commands from the standard input. +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 +utility itself and do not result in NTP mode 6 +requests being sent to a server. +These are described following. +@table @samp +@item Ic +@item Ic +A +by itself will print a list of all the command +keywords known to this incarnation of +A +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +than this manual +page. +@item Ic +@item Ic +@item Ic +The data carried by NTP mode 6 messages consists of a list of +items of the form +where the +is ignored, and can be omitted, +in requests to the server to read variables. +The +utility maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +and +commands described below. +The +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 +command can be used to remove individual variables from the list, +while the +command removes all variables from the +list. +@item Ic +Normally +does not authenticate requests unless +they are write requests. +The command +causes +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 +display. +The command +causes +to display whether or not +is currently autheinticating requests. +@item Ic +Causes output from query commands to be "cooked", so that +variables which are recognized by +will have their +values reformatted for human consumption. +Variables which +thinks should have a decodable value but didn't are +marked with a trailing +@item Xo +With no argument, displays the current debug level. +Otherwise, the debug level is changed to the indicated level. +@item Ic +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. +@item Ic +Set the host to which future queries will be sent. +may be either a host name or a numeric address. +@item Ic +If +is specified, host names are printed in +information displays. +If +is specified, numeric +addresses are printed instead. +The default is +unless +modified using the command line +switch. +@item Ic +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. +@item Ic +Sets the NTP version number which +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. +@item Ic +Exit +@item Ic +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. +@item Ic +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. +@item Ic +Specify a timeout period for responses to server queries. +The +default is about 5000 milliseconds. +Note that since +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. + +@end multitable diff --cc ntpsnmpd/invoke-ntpsnmpd.texi index fc0cd88ddd,0000000000..6902b1eda1 mode 100644,000000..100644 --- a/ntpsnmpd/invoke-ntpsnmpd.texi +++ b/ntpsnmpd/invoke-ntpsnmpd.texi @@@ -1,156 -1,0 +1,178 @@@ +@node ntpsnmpd Invocation +@section Invoking ntpsnmpd +@pindex ntpsnmpd +@cindex NTP SNMP MIB agent +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-ntpsnmpd.texi) +# +# It has been AutoGen-ed April 14, 2012 at 12:22:53 AM by AutoGen 5.16pre18 +# From the definitions ntpsnmpd-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + + + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpsnmpd} program. +This software is released under the NTP license, . + +@menu +* ntpsnmpd usage:: ntpsnmpd help/usage (-?) +* ntpsnmpd agentxsocket:: agentxsocket option +* ntpsnmpd config:: presetting/configuring ntpsnmpd +* ntpsnmpd exit status:: exit status +* ntpsnmpd Description:: Description +* ntpsnmpd Authors:: Authors +@end menu + +@node ntpsnmpd usage +@subsection ntpsnmpd help/usage (-?) +@cindex ntpsnmpd help + +This is the automatically generated usage text for ntpsnmpd. +The text printed is the same whether for the @code{help} option (-?) or the @code{more-help} option (-!). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example - ntpsnmpd is unavailable - no -? - @end example ++USAGE: ntpsnmpd [ - [] | --[@{=| @}] ]... ++ Flg Arg Option-Name Description ++ -n no nofork Do not fork ++ -p no syslog Log to syslog() ++ Str agentxsocket The socket address ntpsnmpd uses to connect to net-snmpd ++ opt version Output version information and exit ++ -? no help Display extended usage information and exit ++ -! no more-help Extended usage information passed thru pager ++ -> opt save-opts Save the option state to a config file ++ -< Str load-opts Load options from a config file ++ - disabled as --no-load-opts ++ - may appear multiple times ++ ++Options are specified by doubled hyphens and their name or by a single ++hyphen and the flag character. ++ ++ ++ ++The following option preset mechanisms are supported: ++ - reading file $HOME/.ntprc ++ - reading file ./.ntprc ++ - examining environment variables named NTPSNMPD_* ++ ++please send bug reports to: http://bugs.ntp.org, bugs@@ntp.org +@exampleindent 4 + +@node ntpsnmpd agentxsocket +@subsection agentxsocket option +@cindex ntpsnmpd-agentxsocket + +This is the ``the socket address ntpsnmpd uses to connect to net-snmpd'' option. +This option takes an argument string. +[:] +The default is the Unix Domain socket "unix:/var/agentx/master". Another common alternative is tcp:localhost:705. + + +@node ntpsnmpd config +@subsection presetting/configuring ntpsnmpd + +Any option that is not marked as @i{not presettable} may be preset by +loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTPSNMPD} and @code{NTPSNMPD_}. @code{} must be one of +the options listed above in upper case and segmented with underscores. +The @code{NTPSNMPD} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$HOME +@item +$PWD +@end itemize +The environment variables @code{HOME}, and @code{PWD} +are expanded and replaced when @file{ntpsnmpd} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.ntprc} is searched for +within that directory and processed. + + +Configuration files may be in a wide variety of formats. +The basic format is an option name followed by a value (argument) on the +same line. Values may be separated from the option name with a colon, +equal sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + +Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: +@example +[NTPSNMPD] +@end example +@noindent +or by +@example + +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example + + ...<...>... + +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{AutoOpts} does provide a means for searching +the associated name/value pair list (see: optionFindValue). + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the +first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node ntpsnmpd exit status +@subsection ntpsnmpd exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table +@node ntpsnmpd Description +@subsection ntpsnmpd Description +@node ntpsnmpd Authors +@subsection ntpsnmpd Authors diff --cc util/invoke-ntp-keygen.texi index 6107a9149b,0000000000..3b0d0e6ea1 mode 100644,000000..100644 --- a/util/invoke-ntp-keygen.texi +++ b/util/invoke-ntp-keygen.texi @@@ -1,1049 -1,0 +1,1049 @@@ +@node ntp-keygen Invocation +@section Invoking ntp-keygen +@pindex ntp-keygen +@cindex Create a NTP host key +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-ntp-keygen.texi) +# +# It has been AutoGen-ed April 14, 2012 at 12:22:58 AM by AutoGen 5.16pre18 +# From the definitions ntp-keygen-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + + + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp-keygen} program. +This software is released under the NTP license, . + +@menu +* ntp-keygen usage:: ntp-keygen help/usage (-?) +* ntp-keygen certificate:: certificate option (-c) +* ntp-keygen cipher:: cipher option (-C) +* ntp-keygen id-key:: id-key option (-e) +* ntp-keygen gq-params:: gq-params option (-G) +* ntp-keygen host-key:: host-key option (-H) +* ntp-keygen iffkey:: iffkey option (-I) +* ntp-keygen ident:: ident option (-i) +* ntp-keygen lifetime:: lifetime option (-l) +* ntp-keygen md5key:: md5key option (-M) +* ntp-keygen modulus:: modulus option (-m) +* ntp-keygen pvt-cert:: pvt-cert option (-P) +* ntp-keygen pvt-passwd:: pvt-passwd option (-p) +* ntp-keygen get-pvt-passwd:: get-pvt-passwd option (-q) +* ntp-keygen sign-key:: sign-key option (-S) +* ntp-keygen subject-name:: subject-name option (-s) +* ntp-keygen trusted-cert:: trusted-cert option (-T) +* ntp-keygen mv-params:: mv-params option (-V) +* ntp-keygen mv-keys:: mv-keys option (-v) +* ntp-keygen config:: presetting/configuring ntp-keygen +* ntp-keygen exit status:: exit status +* ntp-keygen Description:: Description +* ntp-keygen Usage:: Usage +* ntp-keygen Notes:: Notes +* ntp-keygen Bugs:: Bugs +@end menu + +@node ntp-keygen usage +@subsection ntp-keygen help/usage (-?) +@cindex ntp-keygen help + +This is the automatically generated usage text for ntp-keygen. +The text printed is the same whether for the @code{help} option (-?) or the @code{more-help} option (-!). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example - ntp-keygen (ntp) - Create a NTP host key - Ver. 4.2.7p271 ++ntp-keygen (ntp) - Create a NTP host key - Ver. 4.2.7p272 +USAGE: ntp-keygen [ - [] | --[@{=| @}] ]... + Flg Arg Option-Name Description + -c Str certificate certificate scheme + -C Str cipher privatekey cipher + -d no debug-level Increase debug verbosity level + - may appear multiple times + -D Str set-debug-level Set the debug verbosity level + - may appear multiple times + -e no id-key Write IFF or GQ identity keys + -G no gq-params Generate GQ parameters and keys + -H no host-key generate RSA host key + -I no iffkey generate IFF parameters + -i Str ident set Autokey group name + -l Num lifetime set certificate lifetime + -M no md5key generate MD5 keys + -m Num modulus modulus + - It must be in the range: + 256 to 2048 + -P no pvt-cert generate PC private certificate + -p Str pvt-passwd output private password + -q Str get-pvt-passwd input private password + -S Str sign-key generate sign key (RSA or DSA) + -s Str subject-name set host and optionally group name + -T no trusted-cert trusted certificate (TC scheme) + -V Num mv-params generate MV parameters + -v Num mv-keys update MV keys + opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + -> opt save-opts Save the option state to a config file + -< Str load-opts Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + + + +The following option preset mechanisms are supported: + - reading file $HOME/.ntprc + - reading file ./.ntprc + - examining environment variables named NTP_KEYGEN_* + +please send bug reports to: http://bugs.ntp.org, bugs@@ntp.org +@end example +@exampleindent 4 + +@node ntp-keygen certificate +@subsection certificate option (-c) +@cindex ntp-keygen-certificate + +This is the ``certificate scheme'' option. +This option takes an argument string @file{scheme}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +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. +@node ntp-keygen cipher +@subsection cipher option (-C) +@cindex ntp-keygen-cipher + +This is the ``privatekey cipher'' option. +This option takes an argument string @file{cipher}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Select the cipher which is used to encrypt the files containing +private keys. The default is three-key triple DES in CBC mode, +equivalent to "-C des-ede3-cbc". The openssl tool lists ciphers +available in "openssl -h" output. +@node ntp-keygen id-key +@subsection id-key option (-e) +@cindex ntp-keygen-id-key + +This is the ``write iff or gq identity keys'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +@node ntp-keygen gq-params +@subsection gq-params option (-G) +@cindex ntp-keygen-gq-params + +This is the ``generate gq parameters and keys'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +@node ntp-keygen host-key +@subsection host-key option (-H) +@cindex ntp-keygen-host-key + +This is the ``generate rsa host key'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate new host keys, obsoleting any that may exist. +@node ntp-keygen iffkey +@subsection iffkey option (-I) +@cindex ntp-keygen-iffkey + +This is the ``generate iff parameters'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +@node ntp-keygen ident +@subsection ident option (-i) +@cindex ntp-keygen-ident + +This is the ``set autokey group name'' option. +This option takes an argument string @file{group}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Set the optional Autokey group name to name. This is used in +the file name of IFF, GQ, and MV client parameters files. In +that role, the default is the host name if this option is not +provided. The group name, if specified using -i/--ident or +using -s/--subject-name following an '@' character, is also a +part of the self-signed host certificate's subject and issuer +names in the form host@group and should match the 'crypto ident' +or 'server ident' configuration in ntpd's configuration file. +@node ntp-keygen lifetime +@subsection lifetime option (-l) +@cindex ntp-keygen-lifetime + +This is the ``set certificate lifetime'' option. +This option takes an argument number @file{lifetime}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Set the certificate expiration to lifetime days from now. +@node ntp-keygen md5key +@subsection md5key option (-M) +@cindex ntp-keygen-md5key + +This is the ``generate md5 keys'' option. +Generate MD5 keys, obsoleting any that may exist. +@node ntp-keygen modulus +@subsection modulus option (-m) +@cindex ntp-keygen-modulus + +This is the ``modulus'' option. +This option takes an argument number @file{modulus}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +The number of bits in the prime modulus. The default is 512. +@node ntp-keygen pvt-cert +@subsection pvt-cert option (-P) +@cindex ntp-keygen-pvt-cert + +This is the ``generate pc private certificate'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate a private certificate. By default, the program generates +public certificates. +@node ntp-keygen pvt-passwd +@subsection pvt-passwd option (-p) +@cindex ntp-keygen-pvt-passwd + +This is the ``output private password'' option. +This option takes an argument string @file{passwd}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Encrypt generated files containing private data with the specified +password and the cipher selected with -C/--cipher. +@node ntp-keygen get-pvt-passwd +@subsection get-pvt-passwd option (-q) +@cindex ntp-keygen-get-pvt-passwd + +This is the ``input private password'' option. +This option takes an argument string @file{passwd}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Set the password for reading files to the specified password. +@node ntp-keygen sign-key +@subsection sign-key option (-S) +@cindex ntp-keygen-sign-key + +This is the ``generate sign key (rsa or dsa)'' option. +This option takes an argument string @file{sign}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +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. +@node ntp-keygen subject-name +@subsection subject-name option (-s) +@cindex ntp-keygen-subject-name + +This is the ``set host and optionally group name'' option. +This option takes an argument string @file{host@@group}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Set the Autokey host name, and optionally, group name specified +following an '@' character. The host name is used in the file +name of generated host and signing certificates, without the +group name. The host name, and if provided, group name are used +in host@group form for the host certificate's subject and issuer +fields. Specifying '-s @group' is allowed, and results in +leaving the host name unchanged while appending @group to the +subject and issuer fields, as with -i group. The group name, or +if not provided, the host name are also used in the file names +of IFF, GQ, and MV client parameter files. +@node ntp-keygen trusted-cert +@subsection trusted-cert option (-T) +@cindex ntp-keygen-trusted-cert + +This is the ``trusted certificate (tc scheme)'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate a trusted certificate. By default, the program generates +a non-trusted certificate. +@node ntp-keygen mv-params +@subsection mv-params option (-V) +@cindex ntp-keygen-mv-params + +This is the ``generate mv parameters'' option. +This option takes an argument number @file{num}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +Generate parameters and keys for the Mu-Varadharajan (MV) +identification scheme. +@node ntp-keygen mv-keys +@subsection mv-keys option (-v) +@cindex ntp-keygen-mv-keys + +This is the ``update mv keys'' option. +This option takes an argument number @file{num}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{AUTOKEY} during the compilation. +@end itemize + +This option has no @samp{doc} documentation. + + +@node ntp-keygen config +@subsection presetting/configuring ntp-keygen + +Any option that is not marked as @i{not presettable} may be preset by +loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTP-KEYGEN} and @code{NTP-KEYGEN_}. @code{} must be one of +the options listed above in upper case and segmented with underscores. +The @code{NTP-KEYGEN} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$HOME +@item +$PWD +@end itemize +The environment variables @code{HOME}, and @code{PWD} +are expanded and replaced when @file{ntp-keygen} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.ntprc} is searched for +within that directory and processed. + + +Configuration files may be in a wide variety of formats. +The basic format is an option name followed by a value (argument) on the +same line. Values may be separated from the option name with a colon, +equal sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + +Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: +@example +[NTP-KEYGEN] +@end example +@noindent +or by +@example + +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example + + ...<...>... + +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{AutoOpts} does provide a means for searching +the associated name/value pair list (see: optionFindValue). + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the +first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node ntp-keygen exit status +@subsection ntp-keygen exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table +@node ntp-keygen Description +@subsection ntp-keygen 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. +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. +The +configuration command +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. + +File names begin with the prefix +and end with the postfix +where +is the owner name, usually the string returned +by the Unix gethostname() routine, and +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 +command or all files generated +at a specific time can be removed by a +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. +All files are installed by default in the keys directory +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. +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. +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, +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +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. +The safest way to run the +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +then run the program. +When run for the first time, +or if all +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. +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. +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. +Running the program as other than root and using the Unix +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +in the user home directory. +However, there should be only one +most conveniently +in the root directory, so it is convenient to define the +environment variable used by the OpenSSL library as the path to +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 +using the +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. +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. + +All files are installed by default in the keys directory +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. +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. +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, +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +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. +The safest way to run the +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +then run the program. +When run for the first time, +or if all +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. +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. +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. +Running the program as other than root and using the Unix +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +in the user home directory. +However, there should be only one +most conveniently +in the root directory, so it is convenient to define the +environment variable used by the OpenSSL library as the path to +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 +using the +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. +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 +section of +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 +section of +On each trusted host as root, change to the keys directory. +To insure a fresh fileset, remove all +files. +Then run +to generate keys and a trusted certificate. +On all other hosts do the same, but leave off the +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. +If it is necessary to use a different sign key or different digest/signature +scheme than the default, run +with the +option, where +is either +or +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 +with the +option and selected +as needed. +f +is run again without these options, it generates a new certificate +using the same scheme and sign key. +After setting up the environment it is advisable to update certificates +from time to time, if only to extend the validity interval. +Simply run +with the same flags as before to generate new certificates +using existing keys. +However, if the host or sign key is changed, +should be restarted. +When +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. +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 +page +(maybe available at +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. +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. +The PC scheme supports only one trusted host in the group. +On trusted host alice run +to generate the host key file +and trusted private certificate file +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 +to the host key file and soft link +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. +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 +to produce her parameter file +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 +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. +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 +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 +to this file. +To further protect the integrity of the keys, +each file can be encrypted with a secret password. +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 +to produce her parameter file +which includes both server and client keys. +Copy this file to all group hosts and install a soft link +from the generic +to this file. +In addition, on each host bob install a soft link +from generic +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. +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 +where +is the number of revokable keys (typically 5) to produce +the parameter file +and client key files +where +is the key number (0 \&< +\&< +Copy the parameter file to alice and install a soft link +from the generic +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 +to the client key file. +As the MV scheme is independent of keys and certificates, +these files can be refreshed as needed. +@table @samp +@item Fl +Select certificate message digest/signature encryption scheme. +The +can be one of the following: +or +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 +@item Fl +Enable debugging. +This option displays the cryptographic data produced in eye-friendly billboards. +@item Fl +Write the IFF client keys to the standard output. +This is intended for automatic key distribution by mail. +@item Fl +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +@item Fl +Generate keys for the GQ identification scheme +using the existing GQ parameters. +If the GQ parameters do not yet exist, create them first. +@item Fl +Generate new host keys, obsoleting any that may exist. +@item Fl +Generate parameters for the IFF identification scheme, +obsoleting any that may exist. +@item Fl +Set the suject name to +This is used as the subject field in certificates +and in the file name for host and sign keys. +@item Fl +Generate MD5 keys, obsoleting any that may exist. +@item Fl +Generate a private certificate. +By default, the program generates public certificates. +@item Fl +Encrypt generated files containing private data with +and the DES-CBC algorithm. +@item Fl +Set the password for reading files to password. +@item Fl +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. +@item Fl +Set the issuer name to +This is used for the issuer field in certificates +and in the file name for identity files. +@item Fl +Generate a trusted certificate. +By default, the program generates a non-trusted certificate. +@item Fl +Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. + +@end multitable +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 +program. +If a site supports OpenSSL or its companion OpenSSH, +it is very likely that means to do this are already available. +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. +The entropy seed used by the OpenSSL library is contained in a file, +usually called +which must be available when starting the NTP daemon +or the +program. +The NTP daemon will first look for the file +using the path specified by the +subcommand of the +configuration command. +If not specified in this way, or when starting the +program, +the OpenSSL library will look for the file using the path specified +by the +environment variable in the user home directory, +whether root or some other user. +If the +environment variable is not present, +the library will look for the +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. +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 +program and +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. +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 +where +is a positive integer in the range 1-65,535, +is the string MD5 defining the key format and +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 +character. +Note that the keys used by the +and +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. +The +program generates a MD5 symmetric keys file +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 +so +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 +and +utilities. +@node ntp-keygen Usage +@subsection ntp-keygen Usage +The +option specifies the write password and +option the read password for previously encrypted files. +The +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. +@node ntp-keygen Notes +@subsection ntp-keygen Notes +Portions of this document came from FreeBSD. +@node ntp-keygen Bugs +@subsection ntp-keygen 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. +Please report bugs to http://bugs.ntp.org .