sntp.man.in revision 275970
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 @SNTP_MS@ "19 Dec 2014" "4.2.8" "User Commands" 14.\" 15.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-4dayXk/ag-feaqWk) 16.\" 17.\" It has been AutoGen-ed December 19, 2014 at 07:51:32 AM by AutoGen 5.18.5pre4 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. 76.SH "OPTIONS" 77.TP 78.NOP \f\*[B-Font]\-4\f[], \f\*[B-Font]\-\-ipv4\f[] 79Force IPv4 DNS name resolution. 80This option must not appear in combination with any of the following options: 81ipv6. 82.sp 83Force DNS resolution of the following host names on the command line 84to the IPv4 namespace. 85.TP 86.NOP \f\*[B-Font]\-6\f[], \f\*[B-Font]\-\-ipv6\f[] 87Force IPv6 DNS name resolution. 88This option must not appear in combination with any of the following options: 89ipv4. 90.sp 91Force DNS resolution of the following host names on the command line 92to the IPv6 namespace. 93.TP 94.NOP \f\*[B-Font]\-a\f[] \f\*[I-Font]auth\-keynumber\f[], \f\*[B-Font]\-\-authentication\f[]=\f\*[I-Font]auth\-keynumber\f[] 95Enable authentication with the key \fBauth-keynumber\fP. 96This option takes an integer number as its argument. 97.sp 98Enable authentication using the key specified in this option's 99argument. The argument of this option is the \fBkeyid\fP, a 100number specified in the \fBkeyfile\fP as this key's identifier. 101See the \fBkeyfile\fP option (\fB-k\fP) for more details. 102.TP 103.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]broadcast\-address\f[], \f\*[B-Font]\-\-broadcast\f[]=\f\*[I-Font]broadcast\-address\f[] 104Listen to the address specified for broadcast time sync. 105This option may appear an unlimited number of times. 106.sp 107If specified \fBsntp\fP will listen to the specified address 108for NTP broadcasts. The default maximum wait time 109can (and probably should) be modified with \fB-t\fP. 110.TP 111.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]host\-name\f[], \f\*[B-Font]\-\-concurrent\f[]=\f\*[I-Font]host\-name\f[] 112Concurrently query all IPs returned for host-name. 113This option may appear an unlimited number of times. 114.sp 115Requests from an NTP "client" to a "server" should never be sent 116more rapidly than one every 2 seconds. By default, any IPs returned 117as part of a DNS lookup are assumed to be for a single instance of 118\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs 119one after another, with a 2-second gap in between each query. 120.sp 121The \fB-c\fP or \fB--concurrent\fP flag says that any IPs 122returned for the DNS lookup of the supplied host-name are on 123different machines, so we can send concurrent queries. 124.TP 125.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[] 126Increase debug verbosity level. 127This option may appear an unlimited number of times. 128.sp 129.TP 130.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[] 131Set the debug verbosity level. 132This option may appear an unlimited number of times. 133This option takes an integer number as its argument. 134.sp 135.TP 136.NOP \f\*[B-Font]\-g\f[] \f\*[I-Font]milliseconds\f[], \f\*[B-Font]\-\-gap\f[]=\f\*[I-Font]milliseconds\f[] 137The gap (in milliseconds) between time requests. 138This option takes an integer number as its argument. 139The default 140\f\*[I-Font]milliseconds\f[] 141for this option is: 142.ti +4 143 50 144.sp 145Since we're only going to use the first valid response we get and 146there is benefit to specifying a good number of servers to query, 147separate the queries we send out by the specified number of 148milliseconds. 149.TP 150.NOP \f\*[B-Font]\-K\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-kod\f[]=\f\*[I-Font]file\-name\f[] 151KoD history filename. 152The default 153\f\*[I-Font]file\-name\f[] 154for this option is: 155.ti +4 156 /var/db/ntp-kod 157.sp 158Specifies the filename to be used for the persistent history of KoD 159responses received from servers. If the file does not exist, a 160warning message will be displayed. The file will not be created. 161.TP 162.NOP \f\*[B-Font]\-k\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-keyfile\f[]=\f\*[I-Font]file\-name\f[] 163Look in this file for the key specified with \fB-a\fP. 164.sp 165This option specifies the keyfile. 166\fBsntp\fP will search for the key specified with \fB-a\fP 167\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more 168information. 169.TP 170.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-logfile\f[]=\f\*[I-Font]file\-name\f[] 171Log to specified logfile. 172.sp 173This option causes the client to write log messages to the specified 174\fIlogfile\fP. 175.TP 176.NOP \f\*[B-Font]\-M\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-steplimit\f[]=\f\*[I-Font]number\f[] 177Adjustments less than \fBsteplimit\fP msec will be slewed. 178This option takes an integer number as its argument. 179The value of 180\f\*[I-Font]number\f[] 181is constrained to being: 182.in +4 183.nf 184.na 185greater than or equal to 0 186.fi 187.in -4 188.sp 189If the time adjustment is less than \fIsteplimit\fP milliseconds, 190slew the amount using \fBadjtime(2)\fP. Otherwise, step the 191correction using \fBsettimeofday(2)\fP. 192.TP 193.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-ntpversion\f[]=\f\*[I-Font]number\f[] 194Send \fBint\fP as our NTP protocol version. 195This option takes an integer number as its argument. 196The value of 197\f\*[I-Font]number\f[] 198is constrained to being: 199.in +4 200.nf 201.na 202in the range 0 through 7 203.fi 204.in -4 205The default 206\f\*[I-Font]number\f[] 207for this option is: 208.ti +4 209 4 210.sp 211When sending requests to a remote server, tell them we are running 212NTP protocol version \fIntpversion\fP . 213.TP 214.NOP \f\*[B-Font]\-r\f[], \f\*[B-Font]\-\-usereservedport\f[] 215Use the NTP Reserved Port (port 123). 216.sp 217Use port 123, which is reserved for NTP, for our network 218communications. 219.TP 220.NOP \f\*[B-Font]\-S\f[], \f\*[B-Font]\-\-step\f[] 221OK to 'step' the time with \fBsettimeofday(2)\fP. 222.sp 223.TP 224.NOP \f\*[B-Font]\-s\f[], \f\*[B-Font]\-\-slew\f[] 225OK to 'slew' the time with \fBadjtime(2)\fP. 226.sp 227.TP 228.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]seconds\f[], \f\*[B-Font]\-\-timeout\f[]=\f\*[I-Font]seconds\f[] 229The number of seconds to wait for responses. 230This option takes an integer number as its argument. 231The default 232\f\*[I-Font]seconds\f[] 233for this option is: 234.ti +4 235 5 236.sp 237When waiting for a reply, \fBsntp\fP will wait the number 238of seconds specified before giving up. The default should be 239more than enough for a unicast response. If \fBsntp\fP is 240only waiting for a broadcast response a longer timeout is 241likely needed. 242.TP 243.NOP \f\*[B-Font]\-\-wait\f[], \f\*[B-Font]\- Fl \-no\-wait\f[] 244Wait for pending replies (if not setting the time). 245The \fIno\-wait\fP form will disable the option. 246This option is enabled by default. 247.sp 248If we are not setting the time, wait for all pending responses. 249.TP 250.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[] 251Display usage information and exit. 252.TP 253.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[] 254Pass the extended usage information through a pager. 255.TP 256.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]] 257Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP 258configuration file listed in the \fBOPTION PRESETS\fP section, below. 259The command will exit after updating the config file. 260.TP 261.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[] 262Load options from \fIcfgfile\fP. 263The \fIno-load-opts\fP form will disable the loading 264of earlier config/rc/ini files. \fI\-\-no-load-opts\fP is handled early, 265out of order. 266.TP 267.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] 268Output version of program and exit. The default mode is `v', a simple 269version. The `c' mode will print copyright information and `n' will 270print the full copyright notice. 271.PP 272.SH "OPTION PRESETS" 273Any option that is not marked as \fInot presettable\fP may be preset 274by loading values from configuration ("RC" or ".INI") file(s) and values from 275environment variables named: 276.nf 277 \fBSNTP_<option-name>\fP or \fBSNTP\fP 278.fi 279.ad 280The environmental presets take precedence (are processed later than) 281the configuration files. 282The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". 283If any of these are directories, then the file \fI.ntprc\fP 284is searched for within those directories. 285.SH USAGE 286.TP 7 287.NOP \f[C]sntp ntpserver.somewhere\f[] 288is the simplest use of this program 289and can be run as an unprivileged command 290to check the current time and error in the local clock. 291.TP 7 292.NOP \f[C]sntp \-a ntpserver.somewhere\f[] 293With suitable privilege, 294run as a command 295or from a 296\fCcron\fR(8)\f[] 297job, 298\f\*[B-Font]sntp \-a\f[] 299will reset the local clock from a synchronized specified server, 300like the (deprecated) 301\fCntpdate\fR(@NTPDATE_MS@)\f[], 302or 303\fCrdate\fR(8)\f[] 304commands. 305.PP 306.SH "ENVIRONMENT" 307See \fBOPTION PRESETS\fP for configuration environment variables. 308.SH "FILES" 309See \fBOPTION PRESETS\fP for configuration files. 310.SH "EXIT STATUS" 311One of the following exit values will be returned: 312.TP 313.NOP 0 " (EXIT_SUCCESS)" 314Successful program execution. 315.TP 316.NOP 1 " (EXIT_FAILURE)" 317The operation failed or the command syntax was not valid. 318.TP 319.NOP 66 " (EX_NOINPUT)" 320A specified configuration file could not be loaded. 321.TP 322.NOP 70 " (EX_SOFTWARE)" 323libopts had an internal operational error. Please report 324it to autogen-users@lists.sourceforge.net. Thank you. 325.PP 326.SH AUTHORS 327.NOP "Johannes Maximilian Kuehn" 328.br 329.NOP "Harlan Stenn" 330.br 331.NOP "Dave Hart" 332.br 333.SH "COPYRIGHT" 334Copyright (C) 1970-2014 The University of Delaware all rights reserved. 335This program is released under the terms of the NTP license, <http://ntp.org/license>. 336.SH "BUGS" 337Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 338.SH "NOTES" 339This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP 340option definitions. 341