contrib/ntp/sntp/sntp.1

   1 .TH SNTP 1 2009-12-08 "( 4.2.4p8)" "Programmer's Manual"
   2 .\"  EDIT THIS FILE WITH CAUTION  (sntp.1)
   3 .\"
   4 .\"  It has been AutoGen-ed  Tuesday December  8, 2009 at 08:14:50 AM EST
   5 .\"  From the definitions    sntp-opts.def
   6 .\"  and the template file   agman1.tpl
   7 .\"
   8 .SH NAME
   9 sntp \- standard SNTP program
  10 .SH SYNOPSIS
  11 .B sntp
  12 .\" Mixture of short (flag) options and long options
  13 .RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \--\fIopt-name\fP " [[=| ]\fIvalue\fP]]..."
  14 .PP
  15 All arguments must be options.
  16 .SH "DESCRIPTION"
  17 This manual page documents, briefly, the \fBsntp\fP command.
  18 .I sntp
  19 can be used as a SNTP client to query a NTP or SNTP server and either display
  20 the time or set the local system's time (given suitable privilege).  It can be
  21 run as an interactive command or in a
  22 .I cron
  23 job.
  24 NTP is the Network Time Protocol (RFC 1305) and SNTP is the
  25 Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769).
  26 .SS Options
  27 .PP
  28 .I sntp
  29 recognizes the following options:
  30 .TP
  31 .B \-v
  32 indicates that diagnostic messages for non-fatal errors and a limited amount of
  33 tracing should be written to standard error.  Fatal ones always produce a
  34 diagnostic.  This option should be set when there is a suspected problem with
  35 the server, network or the source.
  36 .TP
  37 .B \-V
  38 requests more and less comprehensible output, mainly for investigating problems
  39 with apparently inconsistent timestamps.  This option should be set when the
  40 program fails with a message indicating that is the trouble.
  41 .TP
  42 .B \-W
  43 requests very verbose debugging output, and will interfere with the timing
  44 when writing to the terminal (because of line buffered output from C).  Note
  45 that the times produced by this are the corrections needed, and not the error
  46 in the local clock.  This option should be set only when debugging the source.
  47 .TP
  48 .B \-q
  49 indicates that it should query a daemon save file being maintained by it.
  50 This needs no privilege and will change neither the save file nor the clock.
  51 .PP
  52 The default is that it should behave as a client, and the following options
  53 are then relevant:
  54 .TP
  55 .B \-r
  56 indicates that the system clock should be reset by
  57 .IR settimeofday .
  58 Naturally, this will work only if the user has enough privilege.
  59 .TP
  60 .B \-a
  61 indicates that the system clock should be reset by
  62 .IR adjtime .
  63 Naturally, this will work only if the user has enough privilege.
  64 .PP
  65 The default is to write the estimated correct local date and time (i.e. not
  66 UTC) to the standard output in a format like
  67 .BR "'1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs'" ,
  68 where the
  69 .B "'+ 4.567 +/- 0.089 secs'"
  70 indicates the estimated error in the time on the local system.
  71 .TP
  72 .BI \-l " lockfile"
  73 sets the name of the lock file to ensure that there is only
  74 one copy of
  75 .I sntp
  76 running at once.  The default is installation-dependent, but will usually be
  77 .IR /etc/sntp.pid .
  78 .TP
  79 .BI \-e " minerr"
  80 sets the maximum ignorable variation between the clocks to
  81 .IR minerr .
  82 Acceptable values are from 0.001 to 1, and the default is 0.1 if a NTP host is
  83 is specified and 0.5 otherwise.
  84 .TP
  85 .BI \-E " maxerr"
  86 sets the maximum value of various delays that are deemed acceptable to
  87 .IR maxerr .
  88 Acceptable values are from 1 to 60, and the default is 5.  It should sometimes
  89 be increased if there are problems with the network, NTP server or system
  90 clock, but take care.
  91 .TP
  92 .BI \-P  " prompt"
  93 sets the maximum clock change that will be made automatically to
  94 .IR maxerr .
  95 Acceptable values are from 1 to 3600 or
  96 .IR no ,
  97 and the default is 30.  If the program is being run interactively in ordinary
  98 client mode, and the system clock is to be changed, larger corrections will
  99 prompt the user for confirmation.  Specifying
 100 .I no
 101 will disable this and the correction will be made regardless.
 102 .TP
 103 .BI \-c " count"
 104 sets the maximum number of NTP packets required to
 105 .IR count .
 106 Acceptable values are from 1 to 25 if a NTP host is specified and from 5 to 25
 107 otherwise, and the default is 5.  If the maximum isn't enough, the system needs
 108 a better consistency algorithm than this program uses.
 109 .TP
 110 .BI \-d " delay"
 111 sets a rough limit on the total running time to
 112 .I delay
 113 seconds.  Acceptable values are from 1 to 3600, and the default is 15 if a NTP
 114 host is specified and 300 otherwise.
 115 .TP
 116 .B \-4
 117 force IPv4 DNS resolution.
 118 .TP
 119 .B \-6
 120 force IPv6 DNS resolution.
 121 .PP
 122 .B address(es)
 123 are the DNS names or IP numbers of hosts to use for the challenge and response
 124 protocol; if no names are given, the program waits for broadcasts.  Polling a
 125 server is vastly more reliable than listening to broadcasts.  Note that a
 126 single component numeric address is not allowed, to avoid ambiguities.  If
 127 more than one name is give, they will be used in a round-robin fashion.
 128 .PP
 129 Constraints:
 130 .IP
 131 .B minerr
 132 must be less than
 133 .B maxerr
 134 which must be less than
 135 .B delay
 136 (or, if a NTP host is not specified
 137 .BR delay / count "),"
 138 and
 139 .B count
 140 must be less than half of
 141 .BR delay .
 142 .IP
 143 In update mode,
 144 .B maxerr
 145 must be less than
 146 .BR prompt.
 147 .PP
 148 Note that none of the above values are closely linked to the limits described
 149 in the NTP protocol (RFC 1305).
 150 .SH USAGE
 151 The simplest use of this program is as an unprivileged command to check the
 152 current time and error in the local clock.  For example:
 153 .IP
 154 .B sntp ntpserver.somewhere
 155 .PP
 156 With suitable privilege, it can be run as a command or in a
 157 .I cron
 158 job to reset the local clock from a reliable server, like the
 159 .I ntpdate
 160 and
 161 .I rdate
 162 commands.  For example:
 163 .IP
 164 .B sntp \-a ntpserver.somewhere
 165 .PP
 166 More information on how to use this utility is given in the
 167 .I README
 168 file in the distribution.  In particular, this
 169 .I man
 170 page does not describe how to set it up as a server, which needs special care
 171 to avoid propagating misinformation.
 172 .SH RETURN VALUE
 173 When used as a client in non-daemon mode, the program returns a zero exit
 174 status for success, and a non-zero one otherwise. When used as a daemon
 175 (either client or server), it does not return except after a serious error.
 176 .SH BUGS
 177 The program implements the SNTP protocol, and does not provide all NTP
 178 facilities.  In particular, it contains no checks against any form of spoofing.
 179 If this is a serious concern, some network security mechanism (like a firewall
 180 or even just
 181 .IR tcpwrappers )
 182 should be installed.
 183 .PP
 184 There are some errors, ambiguities and inconsistencies in the RFCs, and this
 185 code may not interwork with all other NTP implementations.  Any unreasonable
 186 restrictions should be reported as bugs to whoever is responsible.  It may
 187 be difficult to find out who that is.
 188 .PP
 189 The program will stop as soon as it feels that things have got out of control.
 190 In client daemon mode, it will usually fail during an extended period of
 191 network or server inaccessibility or excessively slow performance, or when the
 192 local clock is reset by another process.  It will then need restarting
 193 manually.  Experienced system administrators can write a shell script, a
 194 .I cron
 195 job or put it in
 196 .IR inittab ,
 197 to do this automatically.
 198 .PP
 199 The error cannot be estimated reliably with broadcast packets or for the drift
 200 in daemon mode (even with client-server packets), and the guess made by the
 201 program may be wrong (possibly even very wrong).  If this is a problem, then
 202 setting the
 203 .B \-c
 204 option to a larger value may help.  Or it may not.
 205 .SH AUTHOR
 206 .I sntp
 207 was developed by N.M. Maclaren of the University of Cambridge Computing
 208 Service.
 209 .SH OPTIONS
 210 .TP
 211 .BR \-4 ", " \--ipv4
 212 Force IPv4 DNS name resolution.
 213 This option is a member of the ipv4 class of options.
 214 .sp
 215 Force DNS resolution of following host names on the command line
 216 to the IPv4 namespace.
 217 .TP
 218 .BR \-6 ", " \--ipv6
 219 Force IPv6 DNS name resolution.
 220 This option is a member of the ipv4 class of options.
 221 .sp
 222 Force DNS resolution of following host names on the command line
 223 to the IPv6 namespace.
 224 .TP
 225 .BR \-u ", " \--unprivport
 226 Use an unprivileged port.
 227 .sp
 228 Use an unprivilegded UDP port for our queries.
 229 .TP
 230 .BR \-v ", " \--normalverbose
 231 Slightly verbose.
 232 This option must not appear in combination with any of the following options:
 233 extraverbose, megaverbose.
 234 .sp
 235 Diagnostic messages for non-fatal errors and a limited amount of
 236 tracing should be written to standard error.  Fatal ones always
 237 produce a diagnostic.  This option should be set when there is a
 238 suspected problem with the server, network or the source.
 239 .TP
 240 .BR \-V ", " \--extraverbose
 241 Extra verbose.
 242 This option must not appear in combination with any of the following options:
 243 normalverbose, megaverbose.
 244 .sp
 245 Produce more and less comprehensible output, mainly for investigating
 246 problems with apparently inconsistent timestamps.  This option should
 247 be set when the program fails with a message indicating that is the
 248 trouble.
 249 .TP
 250 .BR \-W ", " \--megaverbose
 251 Mega verbose.
 252 This option must not appear in combination with any of the following options:
 253 normalverbose, extraverbose.
 254 .sp
 255 Very verbose debugging output that will interfere with the timing
 256 when writing to the terminal (because of line buffered output from C).
 257 Note that the times produced by this are the corrections needed, and
 258 not the error in the local clock.  This option should be set only when
 259 debugging the source.
 260 .TP
 261 .BR \-r ", " \--settimeofday
 262 Set (step) the time with settimeofday().
 263 This option must not appear in combination with any of the following options:
 264 adjtime.
 265 .sp
 266
 267 .TP
 268 .BR \-a ", " \--adjtime
 269 Set (slew) the time with adjtime().
 270 This option must not appear in combination with any of the following options:
 271 settimeofday.
 272 .sp
 273
 274 .TP
 275 .BR \-? , " \--help"
 276 Display usage information and exit.
 277 .TP
 278 .BR \-! , " \--more-help"
 279 Extended usage information passed thru pager.
 280 .TP
 281 .BR \-> " [\fIrcfile\fP]," " \--save-opts" "[=\fIrcfile\fP]"
 282 Save the option state to \fIrcfile\fP.  The default is the \fIlast\fP
 283 configuration file listed in the \fBOPTION PRESETS\fP section, below.
 284 .TP
 285 .BR \-< " \fIrcfile\fP," " \--load-opts" "=\fIrcfile\fP," " \--no-load-opts"
 286 Load options from \fIrcfile\fP.
 287 The \fIno-load-opts\fP form will disable the loading
 288 of earlier RC/INI files.  \fI--no-load-opts\fP is handled early,
 289 out of order.
 290 .TP
 291 .BR \-v " [{\fIv|c|n\fP}]," " \--version" "[=\fI{v|c|n}\fP]"
 292 Output version of program and exit.  The default mode is `v', a simple
 293 version.  The `c' mode will print copyright information and `n' will
 294 print the full copyright notice.
 295 .SH OPTION PRESETS
 296 Any option that is not marked as \fInot presettable\fP may be preset
 297 by loading values from configuration ("RC" or ".INI") file(s) and values from
 298 environment variables named:
 299 .nf
 300   \fBSNTP_<option-name>\fP or \fBSNTP\fP
 301 .fi
 302 .aj
 303 The environmental presets take precedence (are processed later than)
 304 the configuration files.
 305 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
 306 If any of these are directories, then the file \fI.ntprc\fP
 307 is searched for within those directories.
 308 .SH AUTHOR
 309 ntp.org
 310 .br
 311 Please send bug reports to:  http://bugs.ntp.org, bugs@ntp.org
 312
 313 .PP
 314 .nf
 315 .na
 316         General Public Licence for the software known as MSNTP
 317         \------------------------------------------------------
 318
 319           (c) Copyright, N.M. Maclaren, 1996, 1997, 2000
 320           (c) Copyright, University of Cambridge, 1996, 1997, 2000
 321
 322
 323
 324 Free use of MSNTP in source and binary forms is permitted, provided that this
 325 entire licence is duplicated in all copies, and that any documentation,
 326 announcements, and other materials related to use acknowledge that the software
 327 was developed by N.M. Maclaren (hereafter refered to as the Author) at the
 328 University of Cambridge.  Neither the name of the Author nor the University of
 329 Cambridge may be used to endorse or promote products derived from this material
 330 without specific prior written permission.
 331
 332 The Author and the University of Cambridge retain the copyright and all other
 333 legal rights to the software and make it available non-exclusively.  All users
 334 must ensure that the software in all its derivations carries a copyright notice
 335 in the form:
 336           (c) Copyright N.M. Maclaren,
 337           (c) Copyright University of Cambridge.
 338
 339
 340
 341                            NO WARRANTY
 342
 343 Because the MSNTP software is licensed free of charge, the Author and the
 344 University of Cambridge provide absolutely no warranty, either expressed or
 345 implied, including, but not limited to, the implied warranties of
 346 merchantability and fitness for a particular purpose.  The entire risk as to
 347 the quality and performance of the MSNTP software is with you.  Should MSNTP
 348 prove defective, you assume the cost of all necessary servicing or repair.
 349
 350 In no event, unless required by law, will the Author or the University of
 351 Cambridge, or any other party who may modify and redistribute this software as
 352 permitted in accordance with the provisions below, be liable for damages for
 353 any losses whatsoever, including but not limited to lost profits, lost monies,
 354 lost or corrupted data, or other special, incidental or consequential losses
 355 that may arise out of the use or inability to use the MSNTP software.
 356
 357
 358
 359                          COPYING POLICY
 360
 361 Permission is hereby granted for copying and distribution of copies of the
 362 MSNTP source and binary files, and of any part thereof, subject to the
 363 following licence conditions:
 364
 365 1. You may distribute MSNTP or components of MSNTP, with or without additions
 366 developed by you or by others.  No charge, other than an "at-cost" distribution
 367 fee, may be charged for copies, derivations, or distributions of this material
 368 without the express written consent of the copyright holders.
 369
 370 2. You may also distribute MSNTP along with any other product for sale,
 371 provided that the cost of the bundled package is the same regardless of whether
 372 MSNTP is included or not, and provided that those interested only in MSNTP must
 373 be notified that it is a product freely available from the University of
 374 Cambridge.
 375
 376 3. If you distribute MSNTP software or parts of MSNTP, with or without
 377 additions developed by you or others, then you must either make available the
 378 source to all portions of the MSNTP system (exclusive of any additions made by
 379 you or by others) upon request, or instead you may notify anyone requesting
 380 source that it is freely available from the University of Cambridge.
 381
 382 4. You may not omit any of the copyright notices on either the source files,
 383 the executable files, or the documentation.
 384
 385 5. You may not omit transmission of this License agreement with whatever
 386 portions of MSNTP that are distributed.
 387
 388 6. Any users of this software must be notified that it is without warranty or
 389 guarantee of any nature, express or implied, nor is there any fitness for use
 390 represented.
 391
 392
 393 October 1996
 394 April 1997
 395 October 2000
 396 .fi
 397 .ad
 398 .PP
 399 This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP
 400 option definitions.