contrib/ntp/sntp/sntp-opts.def

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