sntp.1sntpman revision 362716
1.de1 NOP 2. it 1 an-trap 3. if \\n[.$] \,\\$*\/ 4.. 5.ie t \ 6.ds B-Font [CB] 7.ds I-Font [CI] 8.ds R-Font [CR] 9.el \ 10.ds B-Font B 11.ds I-Font I 12.ds R-Font R 13.TH sntp 1sntpman "23 Jun 2020" "4.2.8p15" "User Commands" 14.\" 15.\" EDIT THIS FILE WITH CAUTION (in-mem file) 16.\" 17.\" It has been AutoGen-ed June 23, 2020 at 02:19:38 AM by AutoGen 5.18.5 18.\" From the definitions sntp-opts.def 19.\" and the template file agman-cmd.tpl 20.SH NAME 21\f\*[B-Font]sntp\fP 22\- standard Simple Network Time Protocol client program 23.SH SYNOPSIS 24\f\*[B-Font]sntp\fP 25.\" Mixture of short (flag) options and long options 26[\f\*[B-Font]\-flags\f[]] 27[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]] 28[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]] 29[ hostname-or-IP ...] 30.sp \n(Ppu 31.ne 2 32 33.SH DESCRIPTION 34\f\*[B-Font]sntp\fP 35can be used as an SNTP client to query a NTP or SNTP server and either display 36the time or set the local system's time (given suitable privilege). It can be 37run as an interactive command or from a 38\f\*[B-Font]cron\f[] 39job. 40NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) 41are defined and described by RFC 5905. 42.sp \n(Ppu 43.ne 2 44 45The default is to write the estimated correct local date and time (i.e. not 46UTC) to the standard output in a format like: 47\f\*[B-Font]'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'\f[] 48where the 49\f\*[B-Font]'(+0800)'\f[] 50means that to get to UTC from the reported local time one must 51add 8 hours and 0 minutes, 52the 53\f\*[B-Font]'+4.567'\f[] 54indicates the local clock is 4.567 seconds behind the correct time 55(so 4.567 seconds must be added to the local clock to get it to be correct). 56Note that the number of decimals printed for this value will change 57based on the reported precision of the server. 58\f\*[B-Font]'+/- 0.089'\f[] 59is the reported 60\fIsynchronization\f[] \fIdistance\f[] 61(in seconds), which represents the maximum error due to all causes. 62If the server does not report valid data needed to calculate the 63synchronization distance, this will be reported as 64\f\*[B-Font]'+/- ?'\f[]. 65If the 66\fIhost\f[] 67is different from the 68\fIIP\f[], 69both will be displayed. 70Otherwise, only the 71\fIIP\f[] 72is displayed. 73Finally, the 74\fIstratum\f[] 75of the host is reported 76and the leap indicator is decoded and displayed. 77.SH "OPTIONS" 78.TP 79.NOP \f\*[B-Font]\-4\f[], \f\*[B-Font]\-\-ipv4\f[] 80Force IPv4 DNS name resolution. 81This option must not appear in combination with any of the following options: 82ipv6. 83.sp 84Force DNS resolution of the following host names on the command line 85to the IPv4 namespace. 86.TP 87.NOP \f\*[B-Font]\-6\f[], \f\*[B-Font]\-\-ipv6\f[] 88Force IPv6 DNS name resolution. 89This option must not appear in combination with any of the following options: 90ipv4. 91.sp 92Force DNS resolution of the following host names on the command line 93to the IPv6 namespace. 94.TP 95.NOP \f\*[B-Font]\-a\f[] \f\*[I-Font]auth\-keynumber\f[], \f\*[B-Font]\-\-authentication\f[]=\f\*[I-Font]auth\-keynumber\f[] 96Enable authentication with the key \fBauth-keynumber\fP. 97This option takes an integer number as its argument. 98.sp 99Enable authentication using the key specified in this option's 100argument. The argument of this option is the \fBkeyid\fP, a 101number specified in the \fBkeyfile\fP as this key's identifier. 102See the \fBkeyfile\fP option (\fB-k\fP) for more details. 103.TP 104.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]broadcast\-address\f[], \f\*[B-Font]\-\-broadcast\f[]=\f\*[I-Font]broadcast\-address\f[] 105Listen to the address specified for broadcast time sync. 106This option may appear an unlimited number of times. 107.sp 108If specified \fBsntp\fP will listen to the specified address 109for NTP broadcasts. The default maximum wait time 110can (and probably should) be modified with \fB-t\fP. 111.TP 112.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]host\-name\f[], \f\*[B-Font]\-\-concurrent\f[]=\f\*[I-Font]host\-name\f[] 113Concurrently query all IPs returned for host-name. 114This option may appear an unlimited number of times. 115.sp 116Requests from an NTP "client" to a "server" should never be sent 117more rapidly than one every 2 seconds. By default, any IPs returned 118as part of a DNS lookup are assumed to be for a single instance of 119\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs 120one after another, with a 2-second gap in between each query. 121.sp 122The \fB-c\fP or \fB--concurrent\fP flag says that any IPs 123returned for the DNS lookup of the supplied host-name are on 124different machines, so we can send concurrent queries. 125.TP 126.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[] 127Increase debug verbosity level. 128This option may appear an unlimited number of times. 129.sp 130.TP 131.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[] 132Set the debug verbosity level. 133This option may appear an unlimited number of times. 134This option takes an integer number as its argument. 135.sp 136.TP 137.NOP \f\*[B-Font]\-g\f[] \f\*[I-Font]milliseconds\f[], \f\*[B-Font]\-\-gap\f[]=\f\*[I-Font]milliseconds\f[] 138The gap (in milliseconds) between time requests. 139This option takes an integer number as its argument. 140The default 141\f\*[I-Font]milliseconds\f[] 142for this option is: 143.ti +4 144 50 145.sp 146Since we're only going to use the first valid response we get and 147there is benefit to specifying a good number of servers to query, 148separate the queries we send out by the specified number of 149milliseconds. 150.TP 151.NOP \f\*[B-Font]\-K\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-kod\f[]=\f\*[I-Font]file\-name\f[] 152KoD history filename. 153The default 154\f\*[I-Font]file\-name\f[] 155for this option is: 156.ti +4 157 /var/db/ntp-kod 158.sp 159Specifies the filename to be used for the persistent history of KoD 160responses received from servers. If the file does not exist, a 161warning message will be displayed. The file will not be created. 162.TP 163.NOP \f\*[B-Font]\-k\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-keyfile\f[]=\f\*[I-Font]file\-name\f[] 164Look in this file for the key specified with \fB-a\fP. 165The default 166\f\*[I-Font]file\-name\f[] 167for this option is: 168.ti +4 169 /etc/ntp.keys 170.sp 171This option specifies the keyfile. 172\fBsntp\fP will search for the key specified with \fB-a\fP 173\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more 174information. 175.TP 176.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-logfile\f[]=\f\*[I-Font]file\-name\f[] 177Log to specified logfile. 178.sp 179This option causes the client to write log messages to the specified 180\fIlogfile\fP. 181.TP 182.NOP \f\*[B-Font]\-M\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-steplimit\f[]=\f\*[I-Font]number\f[] 183Adjustments less than \fBsteplimit\fP msec will be slewed. 184This option takes an integer number as its argument. 185The value of 186\f\*[I-Font]number\f[] 187is constrained to being: 188.in +4 189.nf 190.na 191greater than or equal to 0 192.fi 193.in -4 194.sp 195If the time adjustment is less than \fIsteplimit\fP milliseconds, 196slew the amount using \fBadjtime(2)\fP. Otherwise, step the 197correction using \fBsettimeofday(2)\fP. The default value is 0, 198which means all adjustments will be stepped. This is a feature, as 199different situations demand different values. 200.TP 201.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-ntpversion\f[]=\f\*[I-Font]number\f[] 202Send \fBint\fP as our NTP protocol version. 203This option takes an integer number as its argument. 204The value of 205\f\*[I-Font]number\f[] 206is constrained to being: 207.in +4 208.nf 209.na 210in the range 0 through 7 211.fi 212.in -4 213The default 214\f\*[I-Font]number\f[] 215for this option is: 216.ti +4 217 4 218.sp 219When sending requests to a remote server, tell them we are running 220NTP protocol version \fIntpversion\fP . 221.TP 222.NOP \f\*[B-Font]\-r\f[], \f\*[B-Font]\-\-usereservedport\f[] 223Use the NTP Reserved Port (port 123). 224.sp 225Use port 123, which is reserved for NTP, for our network 226communications. 227.TP 228.NOP \f\*[B-Font]\-S\f[], \f\*[B-Font]\-\-step\f[] 229OK to 'step' the time with \fBsettimeofday(2)\fP. 230.sp 231.TP 232.NOP \f\*[B-Font]\-s\f[], \f\*[B-Font]\-\-slew\f[] 233OK to 'slew' the time with \fBadjtime(2)\fP. 234.sp 235.TP 236.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]seconds\f[], \f\*[B-Font]\-\-timeout\f[]=\f\*[I-Font]seconds\f[] 237The number of seconds to wait for responses. 238This option takes an integer number as its argument. 239The default 240\f\*[I-Font]seconds\f[] 241for this option is: 242.ti +4 243 5 244.sp 245When waiting for a reply, \fBsntp\fP will wait the number 246of seconds specified before giving up. The default should be 247more than enough for a unicast response. If \fBsntp\fP is 248only waiting for a broadcast response a longer timeout is 249likely needed. 250.TP 251.NOP \f\*[B-Font]\-\-wait\f[], \f\*[B-Font]\- Fl \-no\-wait\f[] 252Wait for pending replies (if not setting the time). 253The \fIno\-wait\fP form will disable the option. 254This option is enabled by default. 255.sp 256If we are not setting the time, wait for all pending responses. 257.TP 258.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[] 259Display usage information and exit. 260.TP 261.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[] 262Pass the extended usage information through a pager. 263.TP 264.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]] 265Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP 266configuration file listed in the \fBOPTION PRESETS\fP section, below. 267The command will exit after updating the config file. 268.TP 269.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[] 270Load options from \fIcfgfile\fP. 271The \fIno-load-opts\fP form will disable the loading 272of earlier config/rc/ini files. \fI\-\-no-load-opts\fP is handled early, 273out of order. 274.TP 275.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] 276Output version of program and exit. The default mode is `v', a simple 277version. The `c' mode will print copyright information and `n' will 278print the full copyright notice. 279.PP 280.SH "OPTION PRESETS" 281Any option that is not marked as \fInot presettable\fP may be preset 282by loading values from configuration ("RC" or ".INI") file(s) and values from 283environment variables named: 284.nf 285 \fBSNTP_<option-name>\fP or \fBSNTP\fP 286.fi 287.ad 288The environmental presets take precedence (are processed later than) 289the configuration files. 290The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". 291If any of these are directories, then the file \fI.ntprc\fP 292is searched for within those directories. 293.SH USAGE 294.TP 7 295.NOP \f[C]sntp ntpserver.somewhere\f[] 296is the simplest use of this program 297and can be run as an unprivileged command 298to check the current time and error in the local clock. 299.TP 7 300.NOP \f[C]sntp \-Ss \-M 128 ntpserver.somewhere\f[] 301With suitable privilege, 302run as a command 303or from a 304\fCcron\f[]\fR(8)\f[] 305job, 306\f\*[B-Font]sntp \-Ss \-M 128 ntpserver.somewhere\f[] 307will request the time from the server, 308and if that server reports that it is synchronized 309then if the offset adjustment is less than 128 milliseconds 310the correction will be slewed, 311and if the correction is more than 128 milliseconds 312the correction will be stepped. 313.TP 7 314.NOP \f[C]sntp \-S ntpserver.somewhere\f[] 315With suitable privilege, 316run as a command 317or from a 318\fCcron\f[]\fR(8)\f[] 319job, 320\f\*[B-Font]sntp \-S ntpserver.somewhere\f[] 321will set (step) the local clock from a synchronized specified server, 322like the (deprecated) 323\fCntpdate\f[]\fR(1ntpdatemdoc)\f[], 324or 325\fCrdate\f[]\fR(8)\f[] 326commands. 327.PP 328.SH "ENVIRONMENT" 329See \fBOPTION PRESETS\fP for configuration environment variables. 330.SH "FILES" 331See \fBOPTION PRESETS\fP for configuration files. 332.SH "EXIT STATUS" 333One of the following exit values will be returned: 334.TP 335.NOP 0 " (EXIT_SUCCESS)" 336Successful program execution. 337.TP 338.NOP 1 " (EXIT_FAILURE)" 339The operation failed or the command syntax was not valid. 340.TP 341.NOP 66 " (EX_NOINPUT)" 342A specified configuration file could not be loaded. 343.TP 344.NOP 70 " (EX_SOFTWARE)" 345libopts had an internal operational error. Please report 346it to autogen-users@lists.sourceforge.net. Thank you. 347.PP 348.SH AUTHORS 349.NOP "Johannes Maximilian Kuehn" 350.br 351.NOP "Harlan Stenn" 352.br 353.NOP "Dave Hart" 354.br 355.SH "COPYRIGHT" 356Copyright (C) 1992-2020 The University of Delaware and Network Time Foundation all rights reserved. 357This program is released under the terms of the NTP license, <http://ntp.org/license>. 358.SH "BUGS" 359Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 360.SH "NOTES" 361This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP 362option definitions. 363