1/* -*- Mode: Text -*- */ 2 3autogen definitions options; 4 5#include autogen-version.def 6 7copyright = { 8 date = "1970-2006"; 9 owner = "ntp.org"; 10 eaddr = "http://bugs.ntp.org, bugs@ntp.org"; 11 type = note; 12 text = `cat COPYRIGHT`; 13}; 14 15 16prog-name = "sntp"; 17prog-title = "standard SNTP program"; 18homerc = $HOME, "."; 19long-opts; 20 21config-header = "config.h"; 22 23#ifndef __windows__ 24rcfile = ".ntprc"; 25#else 26rcfile = "ntp.ini"; 27#endif 28 29environrc; 30 31#include version.def 32 33test-main; 34 35flag = { 36 name = ipv4; 37 value = 4; 38 equivalence = ipv4; 39 descrip = "Force IPv4 DNS name resolution"; 40 doc = <<- _EndOfDoc_ 41 Force DNS resolution of following host names on the command line 42 to the IPv4 namespace. 43 _EndOfDoc_; 44}; 45 46flag = { 47 name = ipv6; 48 value = 6; 49 equivalence = ipv4; 50 descrip = "Force IPv6 DNS name resolution"; 51 doc = <<- _EndOfDoc_ 52 Force DNS resolution of following host names on the command line 53 to the IPv6 namespace. 54 _EndOfDoc_; 55}; 56 57flag = { 58 name = unprivport; 59 value = u; 60 descrip = "Use an unprivileged port"; 61 doc = <<- _EndOfDoc_ 62 Use an unprivilegded UDP port for our queries. 63 _EndOfDoc_; 64}; 65 66flag = { 67 name = normalverbose; 68 value = v; 69 flags-cant = extraverbose, megaverbose; 70 descrip = "Slightly verbose"; 71 doc = <<- _EndOfDoc_ 72 Diagnostic messages for non-fatal errors and a limited amount of 73 tracing should be written to standard error. Fatal ones always 74 produce a diagnostic. This option should be set when there is a 75 suspected problem with the server, network or the source. 76 _EndOfDoc_; 77}; 78 79flag = { 80 name = extraverbose; 81 value = V; 82 flags-cant = normalverbose, megaverbose; 83 descrip = "Extra verbose"; 84 doc = <<- _EndOfDoc_ 85 Produce more and less comprehensible output, mainly for investigating 86 problems with apparently inconsistent timestamps. This option should 87 be set when the program fails with a message indicating that is the 88 trouble. 89 _EndOfDoc_; 90}; 91 92flag = { 93 name = megaverbose; 94 value = W; 95 flags-cant = normalverbose, extraverbose; 96 descrip = "Mega verbose"; 97 doc = <<- _EndOfDoc_ 98 Very verbose debugging output that will interfere with the timing 99 when writing to the terminal (because of line buffered output from C). 100 Note that the times produced by this are the corrections needed, and 101 not the error in the local clock. This option should be set only when 102 debugging the source. 103 _EndOfDoc_; 104}; 105 106flag = { 107 name = settimeofday; 108 value = r; 109 flags-cant = adjtime; 110 descrip = "Set (step) the time with settimeofday()"; 111 doc = <<- _EndOfDoc_ 112 _EndOfDoc_; 113}; 114 115flag = { 116 name = adjtime; 117 value = a; 118 flags-cant = settimeofday; 119 descrip = "Set (slew) the time with adjtime()"; 120 doc = <<- _EndOfDoc_ 121 _EndOfDoc_; 122}; 123 124detail = <<- _END_DETAIL 125.I sntp 126can be used as a SNTP client to query a NTP or SNTP server and either display 127the time or set the local system's time (given suitable privilege). It can be 128run as an interactive command or in a 129.I cron 130job. 131NTP is the Network Time Protocol (RFC 1305) and SNTP is the 132Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769). 133 _END_DETAIL; 134 135prog-man-descrip = <<- _END_PROG_MAN_DESCRIP 136.I sntp 137can be used as a SNTP client to query a NTP or SNTP server and either display 138the time or set the local system's time (given suitable privilege). It can be 139run as an interactive command or in a 140.I cron 141job. 142NTP is the Network Time Protocol (RFC 1305) and SNTP is the 143Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769). 144.SS Options 145.PP 146.I sntp 147recognizes the following options: 148.TP 149.B \-v 150indicates that diagnostic messages for non-fatal errors and a limited amount of 151tracing should be written to standard error. Fatal ones always produce a 152diagnostic. This option should be set when there is a suspected problem with 153the server, network or the source. 154.TP 155.B \-V 156requests more and less comprehensible output, mainly for investigating problems 157with apparently inconsistent timestamps. This option should be set when the 158program fails with a message indicating that is the trouble. 159.TP 160.B \-W 161requests very verbose debugging output, and will interfere with the timing 162when writing to the terminal (because of line buffered output from C). Note 163that the times produced by this are the corrections needed, and not the error 164in the local clock. This option should be set only when debugging the source. 165.TP 166.B \-q 167indicates that it should query a daemon save file being maintained by it. 168This needs no privilege and will change neither the save file nor the clock. 169.PP 170The default is that it should behave as a client, and the following options 171are then relevant: 172.TP 173.B \-r 174indicates that the system clock should be reset by 175.IR settimeofday . 176Naturally, this will work only if the user has enough privilege. 177.TP 178.B \-a 179indicates that the system clock should be reset by 180.IR adjtime . 181Naturally, this will work only if the user has enough privilege. 182.PP 183The default is to write the estimated correct local date and time (i.e. not 184UTC) to the standard output in a format like 185.BR "'1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs'" , 186where the 187.B "'+ 4.567 +/- 0.089 secs'" 188indicates the estimated error in the time on the local system. 189.TP 190.BI \-l " lockfile" 191sets the name of the lock file to ensure that there is only 192one copy of 193.I sntp 194running at once. The default is installation-dependent, but will usually be 195.IR /etc/sntp.pid . 196.TP 197.BI \-e " minerr" 198sets the maximum ignorable variation between the clocks to 199.IR minerr . 200Acceptable values are from 0.001 to 1, and the default is 0.1 if a NTP host is 201is specified and 0.5 otherwise. 202.TP 203.BI \-E " maxerr" 204sets the maximum value of various delays that are deemed acceptable to 205.IR maxerr . 206Acceptable values are from 1 to 60, and the default is 5. It should sometimes 207be increased if there are problems with the network, NTP server or system 208clock, but take care. 209.TP 210.BI \-P " prompt" 211sets the maximum clock change that will be made automatically to 212.IR maxerr . 213Acceptable values are from 1 to 3600 or 214.IR no , 215and the default is 30. If the program is being run interactively in ordinary 216client mode, and the system clock is to be changed, larger corrections will 217prompt the user for confirmation. Specifying 218.I no 219will disable this and the correction will be made regardless. 220.TP 221.BI \-c " count" 222sets the maximum number of NTP packets required to 223.IR count . 224Acceptable values are from 1 to 25 if a NTP host is specified and from 5 to 25 225otherwise, and the default is 5. If the maximum isn't enough, the system needs 226a better consistency algorithm than this program uses. 227.TP 228.BI \-d " delay" 229sets a rough limit on the total running time to 230.I delay 231seconds. Acceptable values are from 1 to 3600, and the default is 15 if a NTP 232host is specified and 300 otherwise. 233.TP 234.B -4 235force IPv4 DNS resolution. 236.TP 237.B -6 238force IPv6 DNS resolution. 239.PP 240.B address(es) 241are the DNS names or IP numbers of hosts to use for the challenge and response 242protocol; if no names are given, the program waits for broadcasts. Polling a 243server is vastly more reliable than listening to broadcasts. Note that a 244single component numeric address is not allowed, to avoid ambiguities. If 245more than one name is give, they will be used in a round-robin fashion. 246.PP 247Constraints: 248.IP 249.B minerr 250must be less than 251.B maxerr 252which must be less than 253.B delay 254(or, if a NTP host is not specified 255.BR delay / count ")," 256and 257.B count 258must be less than half of 259.BR delay . 260.IP 261In update mode, 262.B maxerr 263must be less than 264.BR prompt. 265.PP 266Note that none of the above values are closely linked to the limits described 267in the NTP protocol (RFC 1305). 268.SH USAGE 269The simplest use of this program is as an unprivileged command to check the 270current time and error in the local clock. For example: 271.IP 272.B sntp ntpserver.somewhere 273.PP 274With suitable privilege, it can be run as a command or in a 275.I cron 276job to reset the local clock from a reliable server, like the 277.I ntpdate 278and 279.I rdate 280commands. For example: 281.IP 282.B sntp -a ntpserver.somewhere 283.PP 284More information on how to use this utility is given in the 285.I README 286file in the distribution. In particular, this 287.I man 288page does not describe how to set it up as a server, which needs special care 289to avoid propagating misinformation. 290.SH RETURN VALUE 291When used as a client in non-daemon mode, the program returns a zero exit 292status for success, and a non-zero one otherwise. When used as a daemon 293(either client or server), it does not return except after a serious error. 294.SH BUGS 295The program implements the SNTP protocol, and does not provide all NTP 296facilities. In particular, it contains no checks against any form of spoofing. 297If this is a serious concern, some network security mechanism (like a firewall 298or even just 299.IR tcpwrappers ) 300should be installed. 301.PP 302There are some errors, ambiguities and inconsistencies in the RFCs, and this 303code may not interwork with all other NTP implementations. Any unreasonable 304restrictions should be reported as bugs to whoever is responsible. It may 305be difficult to find out who that is. 306.PP 307The program will stop as soon as it feels that things have got out of control. 308In client daemon mode, it will usually fail during an extended period of 309network or server inaccessibility or excessively slow performance, or when the 310local clock is reset by another process. It will then need restarting 311manually. Experienced system administrators can write a shell script, a 312.I cron 313job or put it in 314.IR inittab , 315to do this automatically. 316.PP 317The error cannot be estimated reliably with broadcast packets or for the drift 318in daemon mode (even with client-server packets), and the guess made by the 319program may be wrong (possibly even very wrong). If this is a problem, then 320setting the 321.B \-c 322option to a larger value may help. Or it may not. 323.SH AUTHOR 324.I sntp 325was developed by N.M. Maclaren of the University of Cambridge Computing 326Service. 327 _END_PROG_MAN_DESCRIP; 328