sntp.man.in revision 310419
1169689Skan.de1 NOP
290075Sobrien.  it 1 an-trap
390075Sobrien.  if \\n[.$] \,\\$*\/
4132718Skan..
590075Sobrien.ie t \
6132718Skan.ds B-Font [CB]
790075Sobrien.ds I-Font [CI]
890075Sobrien.ds R-Font [CR]
990075Sobrien.el \
1090075Sobrien.ds B-Font B
11132718Skan.ds I-Font I
1290075Sobrien.ds R-Font R
1390075Sobrien.TH sntp @SNTP_MS@ "21 Nov 2016" "4.2.8p9" "User Commands"
1490075Sobrien.\"
1590075Sobrien.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-Mfai12/ag-0faa02)
1690075Sobrien.\"
17132718Skan.\" It has been AutoGen-ed November 21, 2016 at 07:58:25 AM by AutoGen 5.18.5
18169689Skan.\" From the definitions sntp-opts.def
19169689Skan.\" and the template file agman-cmd.tpl
2090075Sobrien.SH NAME
2190075Sobrien\f\*[B-Font]sntp\fP
2290075Sobrien\- standard Simple Network Time Protocol client program
2390075Sobrien.SH SYNOPSIS
2490075Sobrien\f\*[B-Font]sntp\fP
2590075Sobrien.\" Mixture of short (flag) options and long options
2690075Sobrien[\f\*[B-Font]\-flags\f[]]
2790075Sobrien[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]]
2890075Sobrien[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
2990075Sobrien[ hostname-or-IP ...]
3090075Sobrien.sp \n(Ppu
3190075Sobrien.ne 2
3296263Sobrien
3396263Sobrien.SH DESCRIPTION
3496263Sobrien\f\*[B-Font]sntp\fP
3596263Sobriencan be used as an SNTP client to query a NTP or SNTP server and either display
3690075Sobrienthe time or set the local system's time (given suitable privilege).  It can be
37132718Skanrun as an interactive command or from a
3890075Sobrien\f\*[B-Font]cron\f[]
3990075Sobrienjob.
4090075SobrienNTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
41132718Skanare defined and described by RFC 5905.
42132718Skan.sp \n(Ppu
4390075Sobrien.ne 2
4490075Sobrien
4590075SobrienThe default is to write the estimated correct local date and time (i.e. not
4690075SobrienUTC) to the standard output in a format like:
4790075Sobrien\f\*[B-Font]'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'\f[]
48146895Skanwhere the
4990075Sobrien\f\*[B-Font]'(+0800)'\f[]
5090075Sobrienmeans that to get to UTC from the reported local time one must
5190075Sobrienadd 8 hours and 0 minutes,
5290075Sobrienthe
5390075Sobrien\f\*[B-Font]'+4.567'\f[]
5490075Sobrienindicates the local clock is 4.567 seconds behind the correct time
55169689Skan(so 4.567 seconds must be added to the local clock to get it to be correct).
56169689SkanNote that the number of decimals printed for this value will change
57169689Skanbased on the reported precision of the server.
58169689Skan\f\*[B-Font]'+/- 0.089'\f[]
59132718Skanis the reported
6090075Sobrien\fIsynchronization\f[] \fIdistance\f[]
6190075Sobrien(in seconds), which represents the maximum error due to all causes.
6290075SobrienIf the server does not report valid data needed to calculate the
6390075Sobriensynchronization distance, this will be reported as
6490075Sobrien\f\*[B-Font]'+/- ?'\f[].
6590075SobrienIf the
6690075Sobrien\fIhost\f[]
6790075Sobrienis different from the
6890075Sobrien\fIIP\f[],
6990075Sobrienboth will be displayed.
7090075SobrienOtherwise, only the 
7190075Sobrien\fIIP\f[]
7290075Sobrienis displayed.
7390075SobrienFinally, the
7490075Sobrien\fIstratum\f[]
75132718Skanof the host is reported
76169689Skanand the leap indicator is decoded and displayed.
7790075Sobrien.SH "OPTIONS"
7890075Sobrien.TP
7990075Sobrien.NOP \f\*[B-Font]\-4\f[], \f\*[B-Font]\-\-ipv4\f[]
8090075SobrienForce IPv4 DNS name resolution.
8190075SobrienThis option must not appear in combination with any of the following options:
8290075Sobrienipv6.
8390075Sobrien.sp
8490075SobrienForce DNS resolution of the following host names on the command line
8590075Sobriento the IPv4 namespace.
8690075Sobrien.TP
87169689Skan.NOP \f\*[B-Font]\-6\f[], \f\*[B-Font]\-\-ipv6\f[]
88169689SkanForce IPv6 DNS name resolution.
89169689SkanThis option must not appear in combination with any of the following options:
90169689Skanipv4.
91169689Skan.sp
92169689SkanForce DNS resolution of the following host names on the command line
93169689Skanto the IPv6 namespace.
94169689Skan.TP
95169689Skan.NOP \f\*[B-Font]\-a\f[] \f\*[I-Font]auth\-keynumber\f[], \f\*[B-Font]\-\-authentication\f[]=\f\*[I-Font]auth\-keynumber\f[]
96169689SkanEnable authentication with the key \fBauth-keynumber\fP.
97169689SkanThis option takes an integer number as its argument.
98169689Skan.sp
99169689SkanEnable authentication using the key specified in this option's
100169689Skanargument.  The argument of this option is the \fBkeyid\fP, a
101117395Skannumber specified in the \fBkeyfile\fP as this key's identifier.
102117395SkanSee the \fBkeyfile\fP option (\fB-k\fP) for more details.
103117395Skan.TP
10490075Sobrien.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]broadcast\-address\f[], \f\*[B-Font]\-\-broadcast\f[]=\f\*[I-Font]broadcast\-address\f[]
10590075SobrienListen to the address specified for broadcast time sync.
10690075SobrienThis option may appear an unlimited number of times.
10790075Sobrien.sp
10890075SobrienIf specified \fBsntp\fP will listen to the specified address
10990075Sobrienfor NTP broadcasts.  The default maximum wait time
11090075Sobriencan (and probably should) be modified with \fB-t\fP.
11190075Sobrien.TP
11290075Sobrien.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]host\-name\f[], \f\*[B-Font]\-\-concurrent\f[]=\f\*[I-Font]host\-name\f[]
11390075SobrienConcurrently query all IPs returned for host-name.
11490075SobrienThis option may appear an unlimited number of times.
11590075Sobrien.sp
116117395SkanRequests from an NTP "client" to a "server" should never be sent
11790075Sobrienmore rapidly than one every 2 seconds.  By default, any IPs returned
11890075Sobrienas part of a DNS lookup are assumed to be for a single instance of
11990075Sobrien\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs
12090075Sobrienone after another, with a 2-second gap in between each query.
121169689Skan.sp
122169689SkanThe \fB-c\fP or \fB--concurrent\fP flag says that any IPs
12390075Sobrienreturned for the DNS lookup of the supplied host-name are on
12490075Sobriendifferent machines, so we can send concurrent queries.
12590075Sobrien.TP
12690075Sobrien.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[]
12790075SobrienIncrease debug verbosity level.
12890075SobrienThis option may appear an unlimited number of times.
12990075Sobrien.sp
13090075Sobrien.TP
13190075Sobrien.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[]
132169689SkanSet the debug verbosity level.
133169689SkanThis option may appear an unlimited number of times.
134169689SkanThis option takes an integer number as its argument.
13590075Sobrien.sp
136169689Skan.TP
13790075Sobrien.NOP \f\*[B-Font]\-g\f[] \f\*[I-Font]milliseconds\f[], \f\*[B-Font]\-\-gap\f[]=\f\*[I-Font]milliseconds\f[]
13890075SobrienThe gap (in milliseconds) between time requests.
13990075SobrienThis option takes an integer number as its argument.
14090075SobrienThe default
141169689Skan\f\*[I-Font]milliseconds\f[]
142169689Skanfor this option is:
143169689Skan.ti +4
144169689Skan 50
145169689Skan.sp
146169689SkanSince we're only going to use the first valid response we get and
147169689Skanthere is benefit to specifying a good number of servers to query,
148169689Skanseparate the queries we send out by the specified number of
149169689Skanmilliseconds.
150169689Skan.TP
15190075Sobrien.NOP \f\*[B-Font]\-K\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-kod\f[]=\f\*[I-Font]file\-name\f[]
15290075SobrienKoD history filename.
15390075SobrienThe default
15490075Sobrien\f\*[I-Font]file\-name\f[]
15590075Sobrienfor this option is:
15690075Sobrien.ti +4
15790075Sobrien /var/db/ntp-kod
158169689Skan.sp
159169689SkanSpecifies the filename to be used for the persistent history of KoD
160169689Skanresponses received from servers.  If the file does not exist, a
161169689Skanwarning message will be displayed.  The file will not be created.
162169689Skan.TP
163169689Skan.NOP \f\*[B-Font]\-k\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-keyfile\f[]=\f\*[I-Font]file\-name\f[]
164169689SkanLook in this file for the key specified with \fB-a\fP.
165169689Skan.sp
166169689SkanThis option specifies the keyfile.
167169689Skan\fBsntp\fP will search for the key specified with \fB-a\fP
168169689Skan\fIkeyno\fP in this file.  See \fBntp.keys(5)\fP for more
169169689Skaninformation.
170169689Skan.TP
171169689Skan.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-logfile\f[]=\f\*[I-Font]file\-name\f[]
172169689SkanLog to specified logfile.
173169689Skan.sp
174169689SkanThis option causes the client to write log messages to the specified
175169689Skan\fIlogfile\fP.
176169689Skan.TP
177169689Skan.NOP \f\*[B-Font]\-M\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-steplimit\f[]=\f\*[I-Font]number\f[]
178169689SkanAdjustments less than \fBsteplimit\fP msec will be slewed.
179169689SkanThis option takes an integer number as its argument.
180169689SkanThe value of
181169689Skan\f\*[I-Font]number\f[]
182169689Skanis constrained to being:
183169689Skan.in +4
184169689Skan.nf
185169689Skan.na
186169689Skangreater than or equal to 0
187169689Skan.fi
188169689Skan.in -4
189169689Skan.sp
190169689SkanIf the time adjustment is less than \fIsteplimit\fP milliseconds,
191169689Skanslew the amount using \fBadjtime(2)\fP.  Otherwise, step the
192169689Skancorrection using \fBsettimeofday(2)\fP.  The default value is 0,
193169689Skanwhich means all adjustments will be stepped.  This is a feature, as
194169689Skandifferent situations demand different values.
195169689Skan.TP
196169689Skan.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-ntpversion\f[]=\f\*[I-Font]number\f[]
197169689SkanSend \fBint\fP as our NTP protocol version.
198169689SkanThis option takes an integer number as its argument.
199169689SkanThe value of
200169689Skan\f\*[I-Font]number\f[]
201169689Skanis constrained to being:
202169689Skan.in +4
203169689Skan.nf
204169689Skan.na
205169689Skanin the range  0 through 7
206169689Skan.fi
207169689Skan.in -4
208169689SkanThe default
209169689Skan\f\*[I-Font]number\f[]
210169689Skanfor this option is:
211169689Skan.ti +4
212169689Skan 4
213169689Skan.sp
214169689SkanWhen sending requests to a remote server, tell them we are running
215169689SkanNTP protocol version \fIntpversion\fP .
216169689Skan.TP
217169689Skan.NOP \f\*[B-Font]\-r\f[], \f\*[B-Font]\-\-usereservedport\f[]
218169689SkanUse the NTP Reserved Port (port 123).
219169689Skan.sp
220169689SkanUse port 123, which is reserved for NTP, for our network
221169689Skancommunications.
222169689Skan.TP
223169689Skan.NOP \f\*[B-Font]\-S\f[], \f\*[B-Font]\-\-step\f[]
224169689SkanOK to 'step' the time with \fBsettimeofday(2)\fP.
225169689Skan.sp
226169689Skan.TP
227169689Skan.NOP \f\*[B-Font]\-s\f[], \f\*[B-Font]\-\-slew\f[]
228169689SkanOK to 'slew' the time with \fBadjtime(2)\fP.
229169689Skan.sp
230169689Skan.TP
231169689Skan.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]seconds\f[], \f\*[B-Font]\-\-timeout\f[]=\f\*[I-Font]seconds\f[]
232169689SkanThe number of seconds to wait for responses.
233169689SkanThis option takes an integer number as its argument.
23490075SobrienThe default
23590075Sobrien\f\*[I-Font]seconds\f[]
23690075Sobrienfor this option is:
23790075Sobrien.ti +4
23890075Sobrien 5
23990075Sobrien.sp
240169689SkanWhen waiting for a reply, \fBsntp\fP will wait the number
241169689Skanof seconds specified before giving up.  The default should be
24290075Sobrienmore than enough for a unicast response.  If \fBsntp\fP is
243169689Skanonly waiting for a broadcast response a longer timeout is
244169689Skanlikely needed.
245169689Skan.TP
246169689Skan.NOP \f\*[B-Font]\-\-wait\f[], \f\*[B-Font]\- Fl \-no\-wait\f[]
247169689SkanWait for pending replies (if not setting the time).
24890075SobrienThe \fIno\-wait\fP form will disable the option.
24990075SobrienThis option is enabled by default.
25090075Sobrien.sp
25190075SobrienIf we are not setting the time, wait for all pending responses.
25290075Sobrien.TP
25390075Sobrien.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[]
254169689SkanDisplay usage information and exit.
255169689Skan.TP
25690075Sobrien.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[]
25790075SobrienPass the extended usage information through a pager.
258169689Skan.TP
259169689Skan.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
260169689SkanSave the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
261169689Skanconfiguration file listed in the \fBOPTION PRESETS\fP section, below.
262169689SkanThe command will exit after updating the config file.
263169689Skan.TP
264169689Skan.NOP \f\*[B-Font]\-<\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]
265169689SkanLoad options from \fIcfgfile\fP.
266169689SkanThe \fIno-load-opts\fP form will disable the loading
267169689Skanof earlier config/rc/ini files.  \fI\-\-no-load-opts\fP is handled early,
268169689Skanout of order.
269169689Skan.TP
270169689Skan.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]
271169689SkanOutput version of program and exit.  The default mode is `v', a simple
272169689Skanversion.  The `c' mode will print copyright information and `n' will
273169689Skanprint the full copyright notice.
274169689Skan.PP
275169689Skan.SH "OPTION PRESETS"
276169689SkanAny option that is not marked as \fInot presettable\fP may be preset
277169689Skanby loading values from configuration ("RC" or ".INI") file(s) and values from
278169689Skanenvironment variables named:
279169689Skan.nf
280169689Skan  \fBSNTP_<option-name>\fP or \fBSNTP\fP
281169689Skan.fi
28290075Sobrien.ad
28390075SobrienThe environmental presets take precedence (are processed later than)
284169689Skanthe configuration files.
28590075SobrienThe \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
28690075SobrienIf any of these are directories, then the file \fI.ntprc\fP
28790075Sobrienis searched for within those directories.
28890075Sobrien.SH USAGE
28990075Sobrien.TP 7
29090075Sobrien.NOP \f[C]sntp ntpserver.somewhere\f[]
29190075Sobrienis the simplest use of this program
29290075Sobrienand can be run as an unprivileged command
293132718Skanto check the current time and error in the local clock.
29490075Sobrien.TP 7
295169689Skan.NOP \f[C]sntp \-Ss \-M 128 ntpserver.somewhere\f[]
296169689SkanWith suitable privilege,
29790075Sobrienrun as a command
29890075Sobrienor from a
29990075Sobrien\fCcron\f[]\fR(8)\f[]
30090075Sobrienjob,
30190075Sobrien\f\*[B-Font]sntp \-Ss \-M 128 ntpserver.somewhere\f[]
30290075Sobrienwill request the time from the server,
30390075Sobrienand if that server reports that it is synchronized
30490075Sobrienthen if the offset adjustment is less than 128 milliseconds
305169689Skanthe correction will be slewed,
306169689Skanand if the correction is more than 128 milliseconds
30790075Sobrienthe correction  will be stepped.
30890075Sobrien.TP 7
30990075Sobrien.NOP \f[C]sntp \-S ntpserver.somewhere\f[]
31090075SobrienWith suitable privilege,
31190075Sobrienrun as a command
31290075Sobrienor from a
31390075Sobrien\fCcron\f[]\fR(8)\f[]
31490075Sobrienjob,
31590075Sobrien\f\*[B-Font]sntp \-S ntpserver.somewhere\f[]
31690075Sobrienwill set (step) the local clock from a synchronized specified server,
31790075Sobrienlike the (deprecated)
31890075Sobrien\fCntpdate\f[]\fR(@NTPDATE_MS@)\f[],
31990075Sobrienor
32090075Sobrien\fCrdate\f[]\fR(8)\f[]
32190075Sobriencommands.
32290075Sobrien.PP
32390075Sobrien.SH "ENVIRONMENT"
32490075SobrienSee \fBOPTION PRESETS\fP for configuration environment variables.
32590075Sobrien.SH "FILES"
32690075SobrienSee \fBOPTION PRESETS\fP for configuration files.
32790075Sobrien.SH "EXIT STATUS"
32890075SobrienOne of the following exit values will be returned:
32990075Sobrien.TP
33090075Sobrien.NOP 0 " (EXIT_SUCCESS)"
33190075SobrienSuccessful program execution.
33290075Sobrien.TP
33390075Sobrien.NOP 1 " (EXIT_FAILURE)"
33490075SobrienThe operation failed or the command syntax was not valid.
33590075Sobrien.TP
33690075Sobrien.NOP 66 " (EX_NOINPUT)"
33790075SobrienA specified configuration file could not be loaded.
33890075Sobrien.TP
33990075Sobrien.NOP 70 " (EX_SOFTWARE)"
34090075Sobrienlibopts had an internal operational error.  Please report
34190075Sobrienit to autogen-users@lists.sourceforge.net.  Thank you.
34290075Sobrien.PP
34390075Sobrien.SH AUTHORS
34490075Sobrien.NOP  "Johannes Maximilian Kuehn" 
34590075Sobrien.br
34690075Sobrien.NOP  "Harlan Stenn" 
34790075Sobrien.br
34890075Sobrien.NOP  "Dave Hart" 
34990075Sobrien.br
35090075Sobrien.SH "COPYRIGHT"
35190075SobrienCopyright (C) 1992-2016 The University of Delaware and Network Time Foundation all rights reserved.
35290075SobrienThis program is released under the terms of the NTP license, <http://ntp.org/license>.
35390075Sobrien.SH "BUGS"
35490075SobrienPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org
35590075Sobrien.SH "NOTES"
35690075SobrienThis manual page was \fIAutoGen\fP-erated from the \fBsntp\fP
35790075Sobrienoption definitions.
35890075Sobrien