diff options
Diffstat (limited to 'sntp/sntp-opts.def')
-rw-r--r-- | sntp/sntp-opts.def | 410 |
1 files changed, 228 insertions, 182 deletions
diff --git a/sntp/sntp-opts.def b/sntp/sntp-opts.def index 4a625413c8f8..c32f5e51e47b 100644 --- a/sntp/sntp-opts.def +++ b/sntp/sntp-opts.def @@ -6,269 +6,315 @@ autogen definitions options; #include copyright.def prog-name = "sntp"; -prog-title = "standard Simple Network Time Protocol program"; +prog-title = "standard Simple Network Time Protocol client program"; argument = '[ hostname-or-IP ...]'; #include homerc.def long-opts; -config-header = "config.h"; +config-header = "config.h"; environrc; #include version.def -test-main; - flag = { - name = ipv4; - value = 4; - flags-cant = ipv6; - descrip = "Force IPv4 DNS name resolution"; - doc = <<- _EndOfDoc_ + name = ipv4; + value = 4; + flags-cant = ipv6; + descrip = "Force IPv4 DNS name resolution"; + doc = <<- _EndOfDoc_ Force DNS resolution of the following host names on the command line to the IPv4 namespace. _EndOfDoc_; }; flag = { - name = ipv6; - value = 6; - flags-cant = ipv4; - descrip = "Force IPv6 DNS name resolution"; - doc = <<- _EndOfDoc_ + name = ipv6; + value = 6; + flags-cant = ipv4; + descrip = "Force IPv6 DNS name resolution"; + doc = <<- _EndOfDoc_ Force DNS resolution of the following host names on the command line to the IPv6 namespace. _EndOfDoc_; }; +flag = { + name = authentication; + value = a; + descrip = "Enable authentication with the key @var{auth-keynumber}"; + arg-type = number; + arg-name = "auth-keynumber"; + doc = <<- _EndOfDoc_ + Enable authentication using the key specified in this option's + argument. The argument of this option is the @option{keyid}, a + number specified in the @option{keyfile} as this key's identifier. + See the @option{keyfile} option (@option{-k}) for more details. + _EndOfDoc_; +}; + +flag = { + name = broadcast; + value = b; + descrip = "Listen to the address specified for broadcast time sync"; + arg-type = string; + arg-name = "broadcast-address"; + max = NOLIMIT; + stack-arg; + doc = <<- _EndOfDoc_ + If specified @code{sntp} will listen to the specified address + for NTP broadcasts. The default maximum wait time + can (and probably should) be modified with @option{-t}. + _EndOfDoc_; +}; flag = { - name = normalverbose; - 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 - produce a diagnostic. This option should be set when there is a - suspected problem with the server, network or the source. + name = concurrent; + value = c; + descrip = "Concurrently query all IPs returned for host-name"; + arg-type = string; + arg-name = "host-name"; + max = NOLIMIT; + stack-arg; + doc = <<- _EndOfDoc_ + Requests from an NTP "client" to a "server" should never be sent + more rapidly than one every 2 seconds. By default, any IPs returned + as part of a DNS lookup are assumed to be for a single instance of + @code{ntpd}, and therefore @code{sntp} will send queries to these IPs + one after another, with a 2-second gap in between each query. + + The @option{-c} or @option{--concurrent} flag says that any IPs + returned for the DNS lookup of the supplied host-name are on + different machines, so we can send concurrent queries. _EndOfDoc_; }; +#include debug-opt.def + flag = { - name = kod; - value = K; - arg-type = string; - arg-name = "file-name"; - descrip = "KoD history filename"; - doc = <<- _EndOfDoc_ - Specifies the filename to be used to persist the history of KoD - responses received from servers. The default is - /var/db/ntp-kod. + name = gap; + value = g; + descrip = "The gap (in milliseconds) between time requests"; + arg-type = number; + arg-name = "milliseconds"; + arg-default = 50; + doc = <<- _EndOfDoc_ + Since we're only going to use the first valid response we get and + there is benefit to specifying a good number of servers to query, + separate the queries we send out by the specified number of + milliseconds. _EndOfDoc_; }; +flag = { + name = kod; + value = K; + arg-type = file; + arg-name = "file-name"; + arg-default = "/var/db/ntp-kod"; + descrip = "KoD history filename"; + doc = <<- _EndOfDoc_ + Specifies the filename to be used for the persistent history of KoD + responses received from servers. If the file does not exist, a + warning message will be displayed. The file will not be created. + _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. + name = keyfile; + value = k; + descrip = "Look in this file for the key specified with @option{-a}"; + arg-type = file; + arg-name = "file-name"; + doc = <<- _EndOfDoc_ + This option specifies the keyfile. + @code{sntp} will search for the key specified with @option{-a} + @file{keyno} in this file. See @command{ntp.keys(5)} for more + information. _EndOfDoc_; }; flag = { - name = logfile; - value = l; - arg-type = string; - arg-name = "file-name"; - flags-cant = syslog; - descrip = "Log to specified logfile"; - doc = <<- _EndOfDoc_ + name = logfile; + value = l; + arg-type = file; + arg-name = "file-name"; + descrip = "Log to specified logfile"; + doc = <<- _EndOfDoc_ This option causes the client to write log messages to the specified - logfile. + @file{logfile}. _EndOfDoc_; }; flag = { - name = settod; - value = s; - flags-cant = adjtime; - descrip = "Set (step) the time with settimeofday()"; - doc = <<- _EndOfDoc_ + name = steplimit; + value = M; + arg-type = number; + arg-range = "0->"; + descrip = "Adjustments less than @var{steplimit} msec will be slewed"; + doc = <<- _EndOfDoc_ + If the time adjustment is less than @file{steplimit} milliseconds, + slew the amount using @command{adjtime(2)}. Otherwise, step the + correction using @command{settimeofday(2)}. _EndOfDoc_; }; flag = { - name = adjtime; - value = j; - flags-cant = settod; - descrip = "Set (slew) the time with adjtime()"; - doc = <<- _EndOfDoc_ + name = ntpversion; + value = o; + descrip = "Send @var{int} as our NTP protocol version"; + arg-type = number; + arg-default = 4; + arg-range = "0->7"; + doc = <<- _EndOfDoc_ + When sending requests to a remote server, tell them we are running + NTP protocol version @file{ntpversion} . _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. + name = usereservedport; + value = r; + descrip = "Use the NTP Reserved Port (port 123)"; + doc = <<- _EndOfDoc_ + Use port 123, which is reserved for NTP, for our network + communications. _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. + name = step; + value = S; + descrip = "OK to 'step' the time with @command{settimeofday(2)}"; + doc = <<- _EndOfDoc_ _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. + name = slew; + value = s; + descrip = "OK to 'slew' the time with @command{adjtime(2)}"; + doc = <<- _EndOfDoc_ _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). + name = timeout; + value = t; + descrip = "The number of seconds to wait for responses"; + arg-type = number; + arg-name = "seconds"; + arg-default = 5; + doc = <<- _EndOfDoc_ + When waiting for a reply, @code{sntp} will wait the number + of seconds specified before giving up. The default should be + more than enough for a unicast response. If @code{sntp} is + only waiting for a broadcast response a longer timeout is + likely needed. _EndOfDoc_; }; +flag = { + name = "wait"; + descrip = "Wait for pending replies (if not setting the time)"; + disable = no; + enabled; + settable; + doc = <<- _EndOfDoc_ + If we are not setting the time, wait for all pending responses. + _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 +doc-section = { + ds-type = 'DESCRIPTION'; + ds-format = 'mdoc'; + ds-text = <<- _END_PROG_MDOC_DESCRIP +.Nm +can be used as an 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 +run as an interactive command or from a +.Ic cron job. NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) are defined and described by RFC 5905. -.PP +.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'" , +UTC) to the standard output in a format like: + +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'" + where the -.B "'(+0800)'" +.Ic "'(+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'" +the +.Ic "'+4.567'" 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 -@code{cron} -job. +(so 4.567 seconds must be added to the local clock to get it to be correct). +Note that the number of decimals printed for this value will change +based on the reported precision of the server. +.Ic "'+/- 0.089'" +is the reported +.Em synchronization distance +(in seconds), which represents the maximum error due to all causes. +If the server does not report valid data needed to calculate the +synchronization distance, this will be reported as +.Ic "'+/- ?'" . +If the +.Em host +is different from the +.Em IP , +both will be displayed. +Otherwise, only the +.Em IP +is displayed. +Finally, the +.Em stratum +of the host is reported. + _END_PROG_MDOC_DESCRIP; +}; -NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) -are defined and described by RFC 5905. +doc-section = { + ds-type = 'USAGE'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_USAGE +.Bl -tag -width indent +.It Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.It Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate 1ntpdatemdoc , +or +.Xr rdate 8 +commands. +.El + _END_MDOC_USAGE; +}; -@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 -@example -1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs -@end example -where the -@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: -.IP -.B sntp ntpserver.somewhere -.PP -With suitable privilege, it can be run as a command or in a -.I cron -job to reset the local clock from a reliable server, like the -.I ntpdate -and -.I rdate -commands. For example: -.IP -.B sntp -a ntpserver.somewhere -.SH RETURN VALUE -The program returns a zero exit -status for success, and a non-zero one otherwise. -.SH BUGS -Please report bugs to http://bugs.ntp.org . - _END_MAN_DOC; +doc-section = { + ds-type = 'AUTHORS'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" + _END_MDOC_AUTHORS; +}; |