diff options
Diffstat (limited to 'sntp/sntp-opts.def')
| -rw-r--r-- | sntp/sntp-opts.def | 397 |
1 files changed, 172 insertions, 225 deletions
diff --git a/sntp/sntp-opts.def b/sntp/sntp-opts.def index b4c7f6b044e8..4a625413c8f8 100644 --- a/sntp/sntp-opts.def +++ b/sntp/sntp-opts.def @@ -3,29 +3,18 @@ autogen definitions options; #include autogen-version.def +#include copyright.def -copyright = { - date = "1970-2006"; - owner = "ntp.org"; - eaddr = "http://bugs.ntp.org, bugs@ntp.org"; - type = note; - text = `cat COPYRIGHT`; -}; +prog-name = "sntp"; +prog-title = "standard Simple Network Time Protocol program"; +argument = '[ hostname-or-IP ...]'; +#include homerc.def -prog-name = "sntp"; -prog-title = "standard SNTP program"; -homerc = $HOME, "."; long-opts; config-header = "config.h"; -#ifndef __windows__ -rcfile = ".ntprc"; -#else -rcfile = "ntp.ini"; -#endif - environrc; #include version.def @@ -35,10 +24,10 @@ test-main; flag = { name = ipv4; value = 4; - equivalence = ipv4; + flags-cant = ipv6; descrip = "Force IPv4 DNS name resolution"; doc = <<- _EndOfDoc_ - Force DNS resolution of following host names on the command line + Force DNS resolution of the following host names on the command line to the IPv4 namespace. _EndOfDoc_; }; @@ -46,28 +35,19 @@ flag = { flag = { name = ipv6; value = 6; - equivalence = ipv4; + flags-cant = ipv4; descrip = "Force IPv6 DNS name resolution"; doc = <<- _EndOfDoc_ - Force DNS resolution of following host names on the command line + Force DNS resolution of the following host names on the command line to the IPv6 namespace. _EndOfDoc_; }; -flag = { - name = unprivport; - value = u; - descrip = "Use an unprivileged port"; - doc = <<- _EndOfDoc_ - Use an unprivilegded UDP port for our queries. - _EndOfDoc_; -}; flag = { name = normalverbose; - value = v; - flags-cant = extraverbose, megaverbose; - descrip = "Slightly verbose"; + value = d; + descrip = "Normal verbose"; doc = <<- _EndOfDoc_ Diagnostic messages for non-fatal errors and a limited amount of tracing should be written to standard error. Fatal ones always @@ -77,35 +57,45 @@ flag = { }; flag = { - name = extraverbose; - value = V; - flags-cant = normalverbose, megaverbose; - descrip = "Extra verbose"; + name = kod; + value = K; + arg-type = string; + arg-name = "file-name"; + descrip = "KoD history filename"; doc = <<- _EndOfDoc_ - Produce more and less comprehensible output, mainly for investigating - problems with apparently inconsistent timestamps. This option should - be set when the program fails with a message indicating that is the - trouble. + Specifies the filename to be used to persist the history of KoD + responses received from servers. The default is + /var/db/ntp-kod. + _EndOfDoc_; +}; + + +flag = { + name = syslog; + value = p; + flags-cant = logfile; + descrip = "Logging with syslog"; + doc = <<- _EndOfDoc_ + When this option is set all logging will be done using syslog. _EndOfDoc_; }; flag = { - name = megaverbose; - value = W; - flags-cant = normalverbose, extraverbose; - descrip = "Mega verbose"; - doc = <<- _EndOfDoc_ - Very verbose debugging output that will interfere with the timing - when writing to the terminal (because of line buffered output from C). - Note that the times produced by this are the corrections needed, and - not the error in the local clock. This option should be set only when - debugging the source. + name = logfile; + value = l; + arg-type = string; + arg-name = "file-name"; + flags-cant = syslog; + descrip = "Log to specified logfile"; + doc = <<- _EndOfDoc_ + This option causes the client to write log messages to the specified + logfile. _EndOfDoc_; }; flag = { - name = settimeofday; - value = r; + name = settod; + value = s; flags-cant = adjtime; descrip = "Set (step) the time with settimeofday()"; doc = <<- _EndOfDoc_ @@ -114,157 +104,153 @@ flag = { flag = { name = adjtime; - value = a; - flags-cant = settimeofday; + value = j; + flags-cant = settod; descrip = "Set (slew) the time with adjtime()"; doc = <<- _EndOfDoc_ _EndOfDoc_; }; +flag = { + name = broadcast; + value = b; + descrip = "Use broadcasts to the address specified for synchronisation"; + arg-type = string; + arg-name = "broadcast-address"; + doc = <<- _EndOfDoc_ + If specified SNTP will listen to the specified broadcast address + for NTP broadcasts. The default maximum wait time, + 68 seconds, can be modified with -t. + _EndOfDoc_; +}; + +flag = { + name = timeout; + value = t; + descrip = "Specify the number of seconds to wait for broadcasts"; + arg-type = number; + arg-name = "seconds"; + arg-default = 68; + doc = <<- _EndOfDoc_ + When waiting for a broadcast packet SNTP will wait the number + of seconds specified before giving up. Default 68 seconds. + _EndOfDoc_; +}; + +flag = { + name = authentication; + value = a; + descrip = "Enable authentication with the key auth-keynumber"; + arg-type = number; + arg-name = "auth-keynumber"; + doc = <<- _EndOfDoc_ + This option enables authentication using the key specified in this option's argument. + The argument of this option is the keyid, a number specified in the keyfile as this + key's identifier. See the keyfile option (-k) for more details. + _EndOfDoc_; +}; + +flag = { + name = keyfile; + value = k; + descrip = "Specify a keyfile. SNTP will look in this file for the key specified with -a"; + arg-type = string; + arg-name = "file-name"; + doc = <<- _EndOfDoc_ + This option specifies the keyfile. SNTP will search for the key specified with -a keyno in this + file. Key files follow the following format: + + keyid keytype key + + Where keyid is a number identifying this key + keytype is one of the follow: + S Key in 64 Bit hexadecimal number as specified in in the DES specification. + N Key in 64 Bit hexadecimal number as specified in the NTP standard. + A Key in a 1-to-8 character ASCII string. + M Key in a 1-to-8 character ASCII string using the MD5 authentication scheme. + + For more information see ntp.keys(5). + _EndOfDoc_; +}; + + +/* explain: Additional information whenever the usage routine is invoked */ +explain = <<- _END_EXPLAIN + _END_EXPLAIN; + detail = <<- _END_DETAIL +sntp implements the Simple Network Time Protocol, and is used to query +an NTP or SNTP server and either display the time or set the local +system's time (given suitable privilege). + +It can be run interactively from the command line or as a cron job. + +NTP and SNTP are defined by RFC 5905, which obsoletes RFC 4330 and RFC +1305. + _END_DETAIL; + +prog-man-descrip = <<- _END_PROG_MAN_DESCRIP .I sntp can be used as a SNTP client to query a NTP or SNTP server and either display the time or set the local system's time (given suitable privilege). It can be run as an interactive command or in a .I cron job. -NTP is the Network Time Protocol (RFC 1305) and SNTP is the -Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769). - _END_DETAIL; -prog-man-descrip = <<- _END_PROG_MAN_DESCRIP -.I sntp +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. + +.PP +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like +.BR "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs'" , +where the +.B "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +and the +.B "'+4.567 +/- 0.089 secs'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct), +and the time of +'1996-10-15 20:17:25.123' +is believed to be correct to within ++/- 0.089 +seconds. + _END_PROG_MAN_DESCRIP; + +prog-info-descrip = <<- _END_PROG_INFO_DESCRIP +@code{sntp} can be used as a SNTP client to query a NTP or SNTP server and either display the time or set the local system's time (given suitable privilege). It can be run as an interactive command or in a -.I cron +@code{cron} job. -NTP is the Network Time Protocol (RFC 1305) and SNTP is the -Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769). -.SS Options -.PP -.I sntp -recognizes the following options: -.TP -.B \-v -indicates that diagnostic messages for non-fatal errors and a limited amount of -tracing should be written to standard error. Fatal ones always produce a -diagnostic. This option should be set when there is a suspected problem with -the server, network or the source. -.TP -.B \-V -requests more and less comprehensible output, mainly for investigating problems -with apparently inconsistent timestamps. This option should be set when the -program fails with a message indicating that is the trouble. -.TP -.B \-W -requests very verbose debugging output, and will interfere with the timing -when writing to the terminal (because of line buffered output from C). Note -that the times produced by this are the corrections needed, and not the error -in the local clock. This option should be set only when debugging the source. -.TP -.B \-q -indicates that it should query a daemon save file being maintained by it. -This needs no privilege and will change neither the save file nor the clock. -.PP -The default is that it should behave as a client, and the following options -are then relevant: -.TP -.B \-r -indicates that the system clock should be reset by -.IR settimeofday . -Naturally, this will work only if the user has enough privilege. -.TP -.B \-a -indicates that the system clock should be reset by -.IR adjtime . -Naturally, this will work only if the user has enough privilege. -.PP + +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. + +@indent The default is to write the estimated correct local date and time (i.e. not UTC) to the standard output in a format like -.BR "'1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs'" , +@example +1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs +@end example where the -.B "'+ 4.567 +/- 0.089 secs'" -indicates the estimated error in the time on the local system. -.TP -.BI \-l " lockfile" -sets the name of the lock file to ensure that there is only -one copy of -.I sntp -running at once. The default is installation-dependent, but will usually be -.IR /etc/sntp.pid . -.TP -.BI \-e " minerr" -sets the maximum ignorable variation between the clocks to -.IR minerr . -Acceptable values are from 0.001 to 1, and the default is 0.1 if a NTP host is -is specified and 0.5 otherwise. -.TP -.BI \-E " maxerr" -sets the maximum value of various delays that are deemed acceptable to -.IR maxerr . -Acceptable values are from 1 to 60, and the default is 5. It should sometimes -be increased if there are problems with the network, NTP server or system -clock, but take care. -.TP -.BI \-P " prompt" -sets the maximum clock change that will be made automatically to -.IR maxerr . -Acceptable values are from 1 to 3600 or -.IR no , -and the default is 30. If the program is being run interactively in ordinary -client mode, and the system clock is to be changed, larger corrections will -prompt the user for confirmation. Specifying -.I no -will disable this and the correction will be made regardless. -.TP -.BI \-c " count" -sets the maximum number of NTP packets required to -.IR count . -Acceptable values are from 1 to 25 if a NTP host is specified and from 5 to 25 -otherwise, and the default is 5. If the maximum isn't enough, the system needs -a better consistency algorithm than this program uses. -.TP -.BI \-d " delay" -sets a rough limit on the total running time to -.I delay -seconds. Acceptable values are from 1 to 3600, and the default is 15 if a NTP -host is specified and 300 otherwise. -.TP -.B -4 -force IPv4 DNS resolution. -.TP -.B -6 -force IPv6 DNS resolution. -.PP -.B address(es) -are the DNS names or IP numbers of hosts to use for the challenge and response -protocol; if no names are given, the program waits for broadcasts. Polling a -server is vastly more reliable than listening to broadcasts. Note that a -single component numeric address is not allowed, to avoid ambiguities. If -more than one name is give, they will be used in a round-robin fashion. -.PP -Constraints: -.IP -.B minerr -must be less than -.B maxerr -which must be less than -.B delay -(or, if a NTP host is not specified -.BR delay / count ")," -and -.B count -must be less than half of -.BR delay . -.IP -In update mode, -.B maxerr -must be less than -.BR prompt. -.PP -Note that none of the above values are closely linked to the limits described -in the NTP protocol (RFC 1305). +@example ++4.567 +/- 0.089 secs +@end example +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct), +and the (local) time of +@code{1996-10-15 20:17:25.123} +can be converted to UTC time by adding 8 hours and 0 minutes, and +is believed to be correct to within +@code{+/- 0.089} +seconds. + _END_PROG_INFO_DESCRIP; + +man-doc = <<- _END_MAN_DOC .SH USAGE The simplest use of this program is as an unprivileged command to check the current time and error in the local clock. For example: @@ -280,48 +266,9 @@ and commands. For example: .IP .B sntp -a ntpserver.somewhere -.PP -More information on how to use this utility is given in the -.I README -file in the distribution. In particular, this -.I man -page does not describe how to set it up as a server, which needs special care -to avoid propagating misinformation. .SH RETURN VALUE -When used as a client in non-daemon mode, the program returns a zero exit -status for success, and a non-zero one otherwise. When used as a daemon -(either client or server), it does not return except after a serious error. +The program returns a zero exit +status for success, and a non-zero one otherwise. .SH BUGS -The program implements the SNTP protocol, and does not provide all NTP -facilities. In particular, it contains no checks against any form of spoofing. -If this is a serious concern, some network security mechanism (like a firewall -or even just -.IR tcpwrappers ) -should be installed. -.PP -There are some errors, ambiguities and inconsistencies in the RFCs, and this -code may not interwork with all other NTP implementations. Any unreasonable -restrictions should be reported as bugs to whoever is responsible. It may -be difficult to find out who that is. -.PP -The program will stop as soon as it feels that things have got out of control. -In client daemon mode, it will usually fail during an extended period of -network or server inaccessibility or excessively slow performance, or when the -local clock is reset by another process. It will then need restarting -manually. Experienced system administrators can write a shell script, a -.I cron -job or put it in -.IR inittab , -to do this automatically. -.PP -The error cannot be estimated reliably with broadcast packets or for the drift -in daemon mode (even with client-server packets), and the guess made by the -program may be wrong (possibly even very wrong). If this is a problem, then -setting the -.B \-c -option to a larger value may help. Or it may not. -.SH AUTHOR -.I sntp -was developed by N.M. Maclaren of the University of Cambridge Computing -Service. - _END_PROG_MAN_DESCRIP; +Please report bugs to http://bugs.ntp.org . + _END_MAN_DOC; |