sntp.1sntpman revision 309007
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 "21 Nov 2016" "4.2.8p9" "User Commands" 14.\" 15.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-Mfai12/ag-0faa02) 16.\" 17.\" It has been AutoGen-ed November 21, 2016 at 07:58:25 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. 165.sp 166This option specifies the keyfile. 167\fBsntp\fP will search for the key specified with \fB-a\fP 168\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more 169information. 170.TP 171.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-logfile\f[]=\f\*[I-Font]file\-name\f[] 172Log to specified logfile. 173.sp 174This option causes the client to write log messages to the specified 175\fIlogfile\fP. 176.TP 177.NOP \f\*[B-Font]\-M\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-steplimit\f[]=\f\*[I-Font]number\f[] 178Adjustments less than \fBsteplimit\fP msec will be slewed. 179This option takes an integer number as its argument. 180The value of 181\f\*[I-Font]number\f[] 182is constrained to being: 183.in +4 184.nf 185.na 186greater than or equal to 0 187.fi 188.in -4 189.sp 190If the time adjustment is less than \fIsteplimit\fP milliseconds, 191slew the amount using \fBadjtime(2)\fP. Otherwise, step the 192correction using \fBsettimeofday(2)\fP. The default value is 0, 193which means all adjustments will be stepped. This is a feature, as 194different situations demand different values. 195.TP 196.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-ntpversion\f[]=\f\*[I-Font]number\f[] 197Send \fBint\fP as our NTP protocol version. 198This option takes an integer number as its argument. 199The value of 200\f\*[I-Font]number\f[] 201is constrained to being: 202.in +4 203.nf 204.na 205in the range 0 through 7 206.fi 207.in -4 208The default 209\f\*[I-Font]number\f[] 210for this option is: 211.ti +4 212 4 213.sp 214When sending requests to a remote server, tell them we are running 215NTP protocol version \fIntpversion\fP . 216.TP 217.NOP \f\*[B-Font]\-r\f[], \f\*[B-Font]\-\-usereservedport\f[] 218Use the NTP Reserved Port (port 123). 219.sp 220Use port 123, which is reserved for NTP, for our network 221communications. 222.TP 223.NOP \f\*[B-Font]\-S\f[], \f\*[B-Font]\-\-step\f[] 224OK to 'step' the time with \fBsettimeofday(2)\fP. 225.sp 226.TP 227.NOP \f\*[B-Font]\-s\f[], \f\*[B-Font]\-\-slew\f[] 228OK to 'slew' the time with \fBadjtime(2)\fP. 229.sp 230.TP 231.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]seconds\f[], \f\*[B-Font]\-\-timeout\f[]=\f\*[I-Font]seconds\f[] 232The number of seconds to wait for responses. 233This option takes an integer number as its argument. 234The default 235\f\*[I-Font]seconds\f[] 236for this option is: 237.ti +4 238 5 239.sp 240When waiting for a reply, \fBsntp\fP will wait the number 241of seconds specified before giving up. The default should be 242more than enough for a unicast response. If \fBsntp\fP is 243only waiting for a broadcast response a longer timeout is 244likely needed. 245.TP 246.NOP \f\*[B-Font]\-\-wait\f[], \f\*[B-Font]\- Fl \-no\-wait\f[] 247Wait for pending replies (if not setting the time). 248The \fIno\-wait\fP form will disable the option. 249This option is enabled by default. 250.sp 251If we are not setting the time, wait for all pending responses. 252.TP 253.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[] 254Display usage information and exit. 255.TP 256.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[] 257Pass the extended usage information through a pager. 258.TP 259.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]] 260Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP 261configuration file listed in the \fBOPTION PRESETS\fP section, below. 262The command will exit after updating the config file. 263.TP 264.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[] 265Load options from \fIcfgfile\fP. 266The \fIno-load-opts\fP form will disable the loading 267of earlier config/rc/ini files. \fI\-\-no-load-opts\fP is handled early, 268out of order. 269.TP 270.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] 271Output version of program and exit. The default mode is `v', a simple 272version. The `c' mode will print copyright information and `n' will 273print the full copyright notice. 274.PP 275.SH "OPTION PRESETS" 276Any option that is not marked as \fInot presettable\fP may be preset 277by loading values from configuration ("RC" or ".INI") file(s) and values from 278environment variables named: 279.nf 280 \fBSNTP_<option-name>\fP or \fBSNTP\fP 281.fi 282.ad 283The environmental presets take precedence (are processed later than) 284the configuration files. 285The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". 286If any of these are directories, then the file \fI.ntprc\fP 287is searched for within those directories. 288.SH USAGE 289.TP 7 290.NOP \f[C]sntp ntpserver.somewhere\f[] 291is the simplest use of this program 292and can be run as an unprivileged command 293to check the current time and error in the local clock. 294.TP 7 295.NOP \f[C]sntp \-Ss \-M 128 ntpserver.somewhere\f[] 296With suitable privilege, 297run as a command 298or from a 299\fCcron\f[]\fR(8)\f[] 300job, 301\f\*[B-Font]sntp \-Ss \-M 128 ntpserver.somewhere\f[] 302will request the time from the server, 303and if that server reports that it is synchronized 304then if the offset adjustment is less than 128 milliseconds 305the correction will be slewed, 306and if the correction is more than 128 milliseconds 307the correction will be stepped. 308.TP 7 309.NOP \f[C]sntp \-S ntpserver.somewhere\f[] 310With suitable privilege, 311run as a command 312or from a 313\fCcron\f[]\fR(8)\f[] 314job, 315\f\*[B-Font]sntp \-S ntpserver.somewhere\f[] 316will set (step) the local clock from a synchronized specified server, 317like the (deprecated) 318\fCntpdate\f[]\fR(1ntpdatemdoc)\f[], 319or 320\fCrdate\f[]\fR(8)\f[] 321commands. 322.PP 323.SH "ENVIRONMENT" 324See \fBOPTION PRESETS\fP for configuration environment variables. 325.SH "FILES" 326See \fBOPTION PRESETS\fP for configuration files. 327.SH "EXIT STATUS" 328One of the following exit values will be returned: 329.TP 330.NOP 0 " (EXIT_SUCCESS)" 331Successful program execution. 332.TP 333.NOP 1 " (EXIT_FAILURE)" 334The operation failed or the command syntax was not valid. 335.TP 336.NOP 66 " (EX_NOINPUT)" 337A specified configuration file could not be loaded. 338.TP 339.NOP 70 " (EX_SOFTWARE)" 340libopts had an internal operational error. Please report 341it to autogen-users@lists.sourceforge.net. Thank you. 342.PP 343.SH AUTHORS 344.NOP "Johannes Maximilian Kuehn" 345.br 346.NOP "Harlan Stenn" 347.br 348.NOP "Dave Hart" 349.br 350.SH "COPYRIGHT" 351Copyright (C) 1992-2016 The University of Delaware and Network Time Foundation all rights reserved. 352This program is released under the terms of the NTP license, <http://ntp.org/license>. 353.SH "BUGS" 354Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 355.SH "NOTES" 356This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP 357option definitions. 358