/contrib/ntp/sntp/sntp-opts.def

https://bitbucket.org/freebsd/freebsd-head/ · Module-Definition · 327 lines · 307 code · 20 blank · 0 comment · 16 complexity · c3094450dc8dbbaa76005cd5eb8ea0c7 MD5 · raw file

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