1/* -*- Mode: Text -*- */
2
3autogen definitions options;
4
5#include autogen-version.def
| 1/* -*- Mode: Text -*- */
2
3autogen definitions options;
4
5#include autogen-version.def
|
6#include copyright.def
| |
7
| 6
|
8prog-name = "sntp";
9prog-title = "standard Simple Network Time Protocol client program";
10argument = '[ hostname-or-IP ...]';
| 7copyright = {
8 date = "1970-2006";
9 owner = "ntp.org";
10 eaddr = "http://bugs.ntp.isc.org, bugs@ntp.org";
11 type = note;
12 text = `cat COPYRIGHT`;
13};
|
11
| 14
|
12#include homerc.def
| |
13
| 15
|
| 16prog-name = "sntp";
17prog-title = "standard SNTP program";
18homerc = $HOME, ".";
|
14long-opts;
15
| 19long-opts;
20
|
16config-header = "config.h";
| 21config-header = "config.h";
|
17
| 22
|
| 23#ifndef __windows__
24rcfile = ".ntprc";
25#else
26rcfile = "ntp.ini";
27#endif
28
|
18environrc;
19
20#include version.def
21
| 29environrc;
30
31#include version.def
32
|
| 33test-main;
34
|
22flag = {
| 35flag = {
|
23 name = ipv4;
24 value = 4;
25 flags-cant = ipv6;
26 descrip = "Force IPv4 DNS name resolution";
27 doc = <<- _EndOfDoc_
28 Force DNS resolution of the following host names on the command line
| 36 name = ipv4;
37 value = 4;
38 equivalence = ipv4;
39 descrip = "Force IPv4 DNS name resolution";
40 doc = <<- _EndOfDoc_
41 Force DNS resolution of following host names on the command line
|
29 to the IPv4 namespace.
30 _EndOfDoc_;
31};
32
33flag = {
| 42 to the IPv4 namespace.
43 _EndOfDoc_;
44};
45
46flag = {
|
34 name = ipv6;
35 value = 6;
36 flags-cant = ipv4;
37 descrip = "Force IPv6 DNS name resolution";
38 doc = <<- _EndOfDoc_
39 Force DNS resolution of the following host names on the command line
| 47 name = ipv6;
48 value = 6;
49 equivalence = ipv4;
50 descrip = "Force IPv6 DNS name resolution";
51 doc = <<- _EndOfDoc_
52 Force DNS resolution of following host names on the command line
|
40 to the IPv6 namespace.
41 _EndOfDoc_;
42};
43
44flag = {
| 53 to the IPv6 namespace.
54 _EndOfDoc_;
55};
56
57flag = {
|
45 name = authentication;
46 value = a;
47 descrip = "Enable authentication with the key @var{auth-keynumber}";
48 arg-type = number;
49 arg-name = "auth-keynumber";
50 doc = <<- _EndOfDoc_
51 Enable authentication using the key specified in this option's
52 argument. The argument of this option is the @option{keyid}, a
53 number specified in the @option{keyfile} as this key's identifier.
54 See the @option{keyfile} option (@option{-k}) for more details.
| 58 name = unprivport;
59 value = u;
60 descrip = "Use an unprivileged port";
61 doc = <<- _EndOfDoc_
62 Use an unprivilegded UDP port for our queries.
|
55 _EndOfDoc_;
56};
57
58flag = {
| 63 _EndOfDoc_;
64};
65
66flag = {
|
59 name = broadcast;
60 value = b;
61 descrip = "Listen to the address specified for broadcast time sync";
62 arg-type = string;
63 arg-name = "broadcast-address";
64 max = NOLIMIT;
65 stack-arg;
66 doc = <<- _EndOfDoc_
67 If specified @code{sntp} will listen to the specified address
68 for NTP broadcasts. The default maximum wait time
69 can (and probably should) be modified with @option{-t}.
| 67 name = normalverbose;
68 value = v;
69 flags-cant = extraverbose, megaverbose;
70 descrip = "Slightly verbose";
71 doc = <<- _EndOfDoc_
72 Diagnostic messages for non-fatal errors and a limited amount of
73 tracing should be written to standard error. Fatal ones always
74 produce a diagnostic. This option should be set when there is a
75 suspected problem with the server, network or the source.
|
70 _EndOfDoc_;
71};
72
73flag = {
| 76 _EndOfDoc_;
77};
78
79flag = {
|
74 name = concurrent;
75 value = c;
76 descrip = "Concurrently query all IPs returned for host-name";
77 arg-type = string;
78 arg-name = "host-name";
79 max = NOLIMIT;
80 stack-arg;
81 doc = <<- _EndOfDoc_
82 Requests from an NTP "client" to a "server" should never be sent
83 more rapidly than one every 2 seconds. By default, any IPs returned
84 as part of a DNS lookup are assumed to be for a single instance of
85 @code{ntpd}, and therefore @code{sntp} will send queries to these IPs
86 one after another, with a 2-second gap in between each query.
87
88 The @option{-c} or @option{--concurrent} flag says that any IPs
89 returned for the DNS lookup of the supplied host-name are on
90 different machines, so we can send concurrent queries.
| 80 name = extraverbose;
81 value = V;
82 flags-cant = normalverbose, megaverbose;
83 descrip = "Extra verbose";
84 doc = <<- _EndOfDoc_
85 Produce more and less comprehensible output, mainly for investigating
86 problems with apparently inconsistent timestamps. This option should
87 be set when the program fails with a message indicating that is the
88 trouble.
|
91 _EndOfDoc_;
92};
93
| 89 _EndOfDoc_;
90};
91
|
94#include debug-opt.def
95
| |
96flag = {
| 92flag = {
|
97 name = gap;
98 value = g;
99 descrip = "The gap (in milliseconds) between time requests";
100 arg-type = number;
101 arg-name = "milliseconds";
102 arg-default = 50;
103 doc = <<- _EndOfDoc_
104 Since we're only going to use the first valid response we get and
105 there is benefit to specifying a good number of servers to query,
106 separate the queries we send out by the specified number of
107 milliseconds.
| 93 name = megaverbose;
94 value = W;
95 flags-cant = normalverbose, extraverbose;
96 descrip = "Mega verbose";
97 doc = <<- _EndOfDoc_
98 Very verbose debugging output that will interfere with the timing
99 when writing to the terminal (because of line buffered output from C).
100 Note that the times produced by this are the corrections needed, and
101 not the error in the local clock. This option should be set only when
102 debugging the source.
|
108 _EndOfDoc_;
109};
110
111flag = {
| 103 _EndOfDoc_;
104};
105
106flag = {
|
112 name = kod;
113 value = K;
114 arg-type = file;
115 arg-name = "file-name";
116 arg-default = "/var/db/ntp-kod";
117 descrip = "KoD history filename";
118 doc = <<- _EndOfDoc_
119 Specifies the filename to be used for the persistent history of KoD
120 responses received from servers. If the file does not exist, a
121 warning message will be displayed. The file will not be created.
| 107 name = settimeofday;
108 value = r;
109 flags-cant = adjtime;
110 descrip = "Set (step) the time with settimeofday()";
111 doc = <<- _EndOfDoc_
|
122 _EndOfDoc_;
123};
124
125flag = {
| 112 _EndOfDoc_;
113};
114
115flag = {
|
126 name = keyfile;
127 value = k;
128 descrip = "Look in this file for the key specified with @option{-a}";
129 arg-type = file;
130 arg-name = "file-name";
131 doc = <<- _EndOfDoc_
132 This option specifies the keyfile.
133 @code{sntp} will search for the key specified with @option{-a}
134 @file{keyno} in this file. See @command{ntp.keys(5)} for more
135 information.
| 116 name = adjtime;
117 value = a;
118 flags-cant = settimeofday;
119 descrip = "Set (slew) the time with adjtime()";
120 doc = <<- _EndOfDoc_
|
136 _EndOfDoc_;
137};
138
| 121 _EndOfDoc_;
122};
123
|
139flag = {
140 name = logfile;
141 value = l;
142 arg-type = file;
143 arg-name = "file-name";
144 descrip = "Log to specified logfile";
145 doc = <<- _EndOfDoc_
146 This option causes the client to write log messages to the specified
147 @file{logfile}.
148 _EndOfDoc_;
149};
150
151flag = {
152 name = steplimit;
153 value = M;
154 arg-type = number;
155 arg-range = "0->";
156 descrip = "Adjustments less than @var{steplimit} msec will be slewed";
157 doc = <<- _EndOfDoc_
158 If the time adjustment is less than @file{steplimit} milliseconds,
159 slew the amount using @command{adjtime(2)}. Otherwise, step the
160 correction using @command{settimeofday(2)}. The default value is 0,
161 which means all adjustments will be stepped. This is a feature, as
162 different situations demand different values.
163 _EndOfDoc_;
164};
165
166flag = {
167 name = ntpversion;
168 value = o;
169 descrip = "Send @var{int} as our NTP protocol version";
170 arg-type = number;
171 arg-default = 4;
172 arg-range = "0->7";
173 doc = <<- _EndOfDoc_
174 When sending requests to a remote server, tell them we are running
175 NTP protocol version @file{ntpversion} .
176 _EndOfDoc_;
177};
178
179flag = {
180 name = usereservedport;
181 value = r;
182 descrip = "Use the NTP Reserved Port (port 123)";
183 doc = <<- _EndOfDoc_
184 Use port 123, which is reserved for NTP, for our network
185 communications.
186 _EndOfDoc_;
187};
188
189flag = {
190 name = step;
191 value = S;
192 descrip = "OK to 'step' the time with @command{settimeofday(2)}";
193 doc = <<- _EndOfDoc_
194 _EndOfDoc_;
195};
196
197flag = {
198 name = slew;
199 value = s;
200 descrip = "OK to 'slew' the time with @command{adjtime(2)}";
201 doc = <<- _EndOfDoc_
202 _EndOfDoc_;
203};
204
205
206flag = {
207 name = timeout;
208 value = t;
209 descrip = "The number of seconds to wait for responses";
210 arg-type = number;
211 arg-name = "seconds";
212 arg-default = 5;
213 doc = <<- _EndOfDoc_
214 When waiting for a reply, @code{sntp} will wait the number
215 of seconds specified before giving up. The default should be
216 more than enough for a unicast response. If @code{sntp} is
217 only waiting for a broadcast response a longer timeout is
218 likely needed.
219 _EndOfDoc_;
220};
221
222flag = {
223 name = "wait";
224 descrip = "Wait for pending replies (if not setting the time)";
225 disable = no;
226 enabled;
227 settable;
228 doc = <<- _EndOfDoc_
229 If we are not setting the time, wait for all pending responses.
230 _EndOfDoc_;
231};
232
233/* explain: Additional information whenever the usage routine is invoked */
234explain = <<- _END_EXPLAIN
235 _END_EXPLAIN;
236
237doc-section = {
238 ds-type = 'DESCRIPTION';
239 ds-format = 'mdoc';
240 ds-text = <<- _END_PROG_MDOC_DESCRIP
241.Nm
242can be used as an SNTP client to query a NTP or SNTP server and either display
| 124detail = <<- _END_DETAIL
125.I sntp
126can be used as a SNTP client to query a NTP or SNTP server and either display
|
243the time or set the local system's time (given suitable privilege). It can be
| 127the time or set the local system's time (given suitable privilege). It can be
|
244run as an interactive command or from a
245.Ic cron
| 128run as an interactive command or in a
129.I cron
|
246job.
| 130job.
|
| 131NTP is the Network Time Protocol (RFC 1305) and SNTP is the
132Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769).
133 _END_DETAIL;
|
247
| 134
|
248NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
249are defined and described by RFC 5905.
250
251.Pp
| 135prog-man-descrip = <<- _END_PROG_MAN_DESCRIP
136.I sntp
137can be used as a SNTP client to query a NTP or SNTP server and either display
138the time or set the local system's time (given suitable privilege). It can be
139run as an interactive command or in a
140.I cron
141job.
142NTP is the Network Time Protocol (RFC 1305) and SNTP is the
143Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769).
144.SS Options
145.PP
146.I sntp
147recognizes the following options:
148.TP
149.B \-v
150indicates that diagnostic messages for non-fatal errors and a limited amount of
151tracing should be written to standard error. Fatal ones always produce a
152diagnostic. This option should be set when there is a suspected problem with
153the server, network or the source.
154.TP
155.B \-V
156requests more and less comprehensible output, mainly for investigating problems
157with apparently inconsistent timestamps. This option should be set when the
158program fails with a message indicating that is the trouble.
159.TP
160.B \-W
161requests very verbose debugging output, and will interfere with the timing
162when writing to the terminal (because of line buffered output from C). Note
163that the times produced by this are the corrections needed, and not the error
164in the local clock. This option should be set only when debugging the source.
165.TP
166.B \-q
167indicates that it should query a daemon save file being maintained by it.
168This needs no privilege and will change neither the save file nor the clock.
169.PP
170The default is that it should behave as a client, and the following options
171are then relevant:
172.TP
173.B \-r
174indicates that the system clock should be reset by
175.IR settimeofday .
176Naturally, this will work only if the user has enough privilege.
177.TP
178.B \-a
179indicates that the system clock should be reset by
180.IR adjtime .
181Naturally, this will work only if the user has enough privilege.
182.PP
|
252The default is to write the estimated correct local date and time (i.e. not
| 183The default is to write the estimated correct local date and time (i.e. not
|
253UTC) to the standard output in a format like:
254
255.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'"
256
| 184UTC) to the standard output in a format like
185.BR "'1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs'" ,
|
257where the
| 186where the
|
258.Ic "'(+0800)'"
259means that to get to UTC from the reported local time one must
260add 8 hours and 0 minutes,
261the
262.Ic "'+4.567'"
263indicates the local clock is 4.567 seconds behind the correct time
264(so 4.567 seconds must be added to the local clock to get it to be correct).
265Note that the number of decimals printed for this value will change
266based on the reported precision of the server.
267.Ic "'+/- 0.089'"
268is the reported
269.Em synchronization distance
270(in seconds), which represents the maximum error due to all causes.
271If the server does not report valid data needed to calculate the
272synchronization distance, this will be reported as
273.Ic "'+/- ?'" .
274If the
275.Em host
276is different from the
277.Em IP ,
278both will be displayed.
279Otherwise, only the
280.Em IP
281is displayed.
282Finally, the
283.Em stratum
284of the host is reported
285and the leap indicator is decoded and displayed.
286 _END_PROG_MDOC_DESCRIP;
287};
288
289doc-section = {
290 ds-type = 'USAGE';
291 ds-format = 'mdoc';
292 ds-text = <<- _END_MDOC_USAGE
293.Bl -tag -width indent
294.It Li "sntp ntpserver.somewhere"
295is the simplest use of this program
296and can be run as an unprivileged command
297to check the current time and error in the local clock.
298.It Li "sntp -Ss -M 128 ntpserver.somewhere"
299With suitable privilege,
300run as a command
301or from a
302.Xr cron 8
303job,
304.Ic "sntp -Ss -M 128 ntpserver.somewhere"
305will request the time from the server,
306and if that server reports that it is synchronized
307then if the offset adjustment is less than 128 milliseconds
308the correction will be slewed,
309and if the correction is more than 128 milliseconds
310the correction will be stepped.
311.It Li "sntp -S ntpserver.somewhere"
312With suitable privilege,
313run as a command
314or from a
315.Xr cron 8
316job,
317.Ic "sntp -S ntpserver.somewhere"
318will set (step) the local clock from a synchronized specified server,
319like the (deprecated)
320.Xr ntpdate 1ntpdatemdoc ,
321or
322.Xr rdate 8
323commands.
324.El
325 _END_MDOC_USAGE;
326};
327
328doc-section = {
329 ds-type = 'AUTHORS';
330 ds-format = 'mdoc';
331 ds-text = <<- _END_MDOC_AUTHORS
332.An "Johannes Maximilian Kuehn"
333.An "Harlan Stenn"
334.An "Dave Hart"
335 _END_MDOC_AUTHORS;
336};
| 187.B "'+ 4.567 +/- 0.089 secs'"
188indicates the estimated error in the time on the local system.
189.TP
190.BI \-l " lockfile"
191sets the name of the lock file to ensure that there is only
192one copy of
193.I sntp
194running at once. The default is installation-dependent, but will usually be
195.IR /etc/sntp.pid .
196.TP
197.BI \-e " minerr"
198sets the maximum ignorable variation between the clocks to
199.IR minerr .
200Acceptable values are from 0.001 to 1, and the default is 0.1 if a NTP host is
201is specified and 0.5 otherwise.
202.TP
203.BI \-E " maxerr"
204sets the maximum value of various delays that are deemed acceptable to
205.IR maxerr .
206Acceptable values are from 1 to 60, and the default is 5. It should sometimes
207be increased if there are problems with the network, NTP server or system
208clock, but take care.
209.TP
210.BI \-P " prompt"
211sets the maximum clock change that will be made automatically to
212.IR maxerr .
213Acceptable values are from 1 to 3600 or
214.IR no ,
215and the default is 30. If the program is being run interactively in ordinary
216client mode, and the system clock is to be changed, larger corrections will
217prompt the user for confirmation. Specifying
218.I no
219will disable this and the correction will be made regardless.
220.TP
221.BI \-c " count"
222sets the maximum number of NTP packets required to
223.IR count .
224Acceptable values are from 1 to 25 if a NTP host is specified and from 5 to 25
225otherwise, and the default is 5. If the maximum isn't enough, the system needs
226a better consistency algorithm than this program uses.
227.TP
228.BI \-d " delay"
229sets a rough limit on the total running time to
230.I delay
231seconds. Acceptable values are from 1 to 3600, and the default is 15 if a NTP
232host is specified and 300 otherwise.
233.TP
234.B -4
235force IPv4 DNS resolution.
236.TP
237.B -6
238force IPv6 DNS resolution.
239.PP
240.B address(es)
241are the DNS names or IP numbers of hosts to use for the challenge and response
242protocol; if no names are given, the program waits for broadcasts. Polling a
243server is vastly more reliable than listening to broadcasts. Note that a
244single component numeric address is not allowed, to avoid ambiguities. If
245more than one name is give, they will be used in a round-robin fashion.
246.PP
247Constraints:
248.IP
249.B minerr
250must be less than
251.B maxerr
252which must be less than
253.B delay
254(or, if a NTP host is not specified
255.BR delay / count "),"
256and
257.B count
258must be less than half of
259.BR delay .
260.IP
261In update mode,
262.B maxerr
263must be less than
264.BR prompt.
265.PP
266Note that none of the above values are closely linked to the limits described
267in the NTP protocol (RFC 1305).
268.SH USAGE
269The simplest use of this program is as an unprivileged command to check the
270current time and error in the local clock. For example:
271.IP
272.B sntp ntpserver.somewhere
273.PP
274With suitable privilege, it can be run as a command or in a
275.I cron
276job to reset the local clock from a reliable server, like the
277.I ntpdate
278and
279.I rdate
280commands. For example:
281.IP
282.B sntp -a ntpserver.somewhere
283.PP
284More information on how to use this utility is given in the
285.I README
286file in the distribution. In particular, this
287.I man
288page does not describe how to set it up as a server, which needs special care
289to avoid propagating misinformation.
290.SH RETURN VALUE
291When used as a client in non-daemon mode, the program returns a zero exit
292status for success, and a non-zero one otherwise. When used as a daemon
293(either client or server), it does not return except after a serious error.
294.SH BUGS
295The program implements the SNTP protocol, and does not provide all NTP
296facilities. In particular, it contains no checks against any form of spoofing.
297If this is a serious concern, some network security mechanism (like a firewall
298or even just
299.IR tcpwrappers )
300should be installed.
301.PP
302There are some errors, ambiguities and inconsistencies in the RFCs, and this
303code may not interwork with all other NTP implementations. Any unreasonable
304restrictions should be reported as bugs to whoever is responsible. It may
305be difficult to find out who that is.
306.PP
307The program will stop as soon as it feels that things have got out of control.
308In client daemon mode, it will usually fail during an extended period of
309network or server inaccessibility or excessively slow performance, or when the
310local clock is reset by another process. It will then need restarting
311manually. Experienced system administrators can write a shell script, a
312.I cron
313job or put it in
314.IR inittab ,
315to do this automatically.
316.PP
317The error cannot be estimated reliably with broadcast packets or for the drift
318in daemon mode (even with client-server packets), and the guess made by the
319program may be wrong (possibly even very wrong). If this is a problem, then
320setting the
321.B \-c
322option to a larger value may help. Or it may not.
323.SH AUTHOR
324.I sntp
325was developed by N.M. Maclaren of the University of Cambridge Computing
326Service.
327 _END_PROG_MAN_DESCRIP;
|
| |