/contrib/ntp/sntp/sntp.1

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 400 lines · 375 code · 25 blank · 0 comment · 0 complexity · f21de68fd931dae6287dcf6b216f5081 MD5 · raw file

  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. .TP
  267. .BR \-a ", " \--adjtime
  268. Set (slew) the time with adjtime().
  269. This option must not appear in combination with any of the following options:
  270. settimeofday.
  271. .sp
  272. .TP
  273. .BR \-? , " \--help"
  274. Display usage information and exit.
  275. .TP
  276. .BR \-! , " \--more-help"
  277. Extended usage information passed thru pager.
  278. .TP
  279. .BR \-> " [\fIrcfile\fP]," " \--save-opts" "[=\fIrcfile\fP]"
  280. Save the option state to \fIrcfile\fP. The default is the \fIlast\fP
  281. configuration file listed in the \fBOPTION PRESETS\fP section, below.
  282. .TP
  283. .BR \-< " \fIrcfile\fP," " \--load-opts" "=\fIrcfile\fP," " \--no-load-opts"
  284. Load options from \fIrcfile\fP.
  285. The \fIno-load-opts\fP form will disable the loading
  286. of earlier RC/INI files. \fI--no-load-opts\fP is handled early,
  287. out of order.
  288. .TP
  289. .BR \-v " [{\fIv|c|n\fP}]," " \--version" "[=\fI{v|c|n}\fP]"
  290. Output version of program and exit. The default mode is `v', a simple
  291. version. The `c' mode will print copyright information and `n' will
  292. print the full copyright notice.
  293. .SH OPTION PRESETS
  294. Any option that is not marked as \fInot presettable\fP may be preset
  295. by loading values from configuration ("RC" or ".INI") file(s) and values from
  296. environment variables named:
  297. .nf
  298. \fBSNTP_<option-name>\fP or \fBSNTP\fP
  299. .fi
  300. .aj
  301. The environmental presets take precedence (are processed later than)
  302. the configuration files.
  303. The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
  304. If any of these are directories, then the file \fI.ntprc\fP
  305. is searched for within those directories.
  306. .SH AUTHOR
  307. ntp.org
  308. .br
  309. Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
  310. .PP
  311. .nf
  312. .na
  313. General Public Licence for the software known as MSNTP
  314. \------------------------------------------------------
  315. (c) Copyright, N.M. Maclaren, 1996, 1997, 2000
  316. (c) Copyright, University of Cambridge, 1996, 1997, 2000
  317. Free use of MSNTP in source and binary forms is permitted, provided that this
  318. entire licence is duplicated in all copies, and that any documentation,
  319. announcements, and other materials related to use acknowledge that the software
  320. was developed by N.M. Maclaren (hereafter refered to as the Author) at the
  321. University of Cambridge. Neither the name of the Author nor the University of
  322. Cambridge may be used to endorse or promote products derived from this material
  323. without specific prior written permission.
  324. The Author and the University of Cambridge retain the copyright and all other
  325. legal rights to the software and make it available non-exclusively. All users
  326. must ensure that the software in all its derivations carries a copyright notice
  327. in the form:
  328. (c) Copyright N.M. Maclaren,
  329. (c) Copyright University of Cambridge.
  330. NO WARRANTY
  331. Because the MSNTP software is licensed free of charge, the Author and the
  332. University of Cambridge provide absolutely no warranty, either expressed or
  333. implied, including, but not limited to, the implied warranties of
  334. merchantability and fitness for a particular purpose. The entire risk as to
  335. the quality and performance of the MSNTP software is with you. Should MSNTP
  336. prove defective, you assume the cost of all necessary servicing or repair.
  337. In no event, unless required by law, will the Author or the University of
  338. Cambridge, or any other party who may modify and redistribute this software as
  339. permitted in accordance with the provisions below, be liable for damages for
  340. any losses whatsoever, including but not limited to lost profits, lost monies,
  341. lost or corrupted data, or other special, incidental or consequential losses
  342. that may arise out of the use or inability to use the MSNTP software.
  343. COPYING POLICY
  344. Permission is hereby granted for copying and distribution of copies of the
  345. MSNTP source and binary files, and of any part thereof, subject to the
  346. following licence conditions:
  347. 1. You may distribute MSNTP or components of MSNTP, with or without additions
  348. developed by you or by others. No charge, other than an "at-cost" distribution
  349. fee, may be charged for copies, derivations, or distributions of this material
  350. without the express written consent of the copyright holders.
  351. 2. You may also distribute MSNTP along with any other product for sale,
  352. provided that the cost of the bundled package is the same regardless of whether
  353. MSNTP is included or not, and provided that those interested only in MSNTP must
  354. be notified that it is a product freely available from the University of
  355. Cambridge.
  356. 3. If you distribute MSNTP software or parts of MSNTP, with or without
  357. additions developed by you or others, then you must either make available the
  358. source to all portions of the MSNTP system (exclusive of any additions made by
  359. you or by others) upon request, or instead you may notify anyone requesting
  360. source that it is freely available from the University of Cambridge.
  361. 4. You may not omit any of the copyright notices on either the source files,
  362. the executable files, or the documentation.
  363. 5. You may not omit transmission of this License agreement with whatever
  364. portions of MSNTP that are distributed.
  365. 6. Any users of this software must be notified that it is without warranty or
  366. guarantee of any nature, express or implied, nor is there any fitness for use
  367. represented.
  368. October 1996
  369. April 1997
  370. October 2000
  371. .fi
  372. .ad
  373. .PP
  374. This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP
  375. option definitions.