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