aboutsummaryrefslogtreecommitdiff
path: root/sntp/sntp-opts.def
diff options
context:
space:
mode:
Diffstat (limited to 'sntp/sntp-opts.def')
-rw-r--r--sntp/sntp-opts.def410
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;
+};