contrib/ntp/sntp/sntp-opts.def

   1 /* -*- Mode: Text -*- */
   2
   3 autogen definitions options;
   4
   5 #include autogen-version.def
   6 #include copyright.def
   7
   8 prog-name      = "sntp";
   9 prog-title      = "standard Simple Network Time Protocol client program";
  10 argument        = '[ hostname-or-IP ...]';
  11
  12 #include homerc.def
  13
  14 long-opts;
  15
  16 config-header   = "config.h";
  17
  18 environrc;
  19
  20 #include version.def
  21
  22 flag = {
  23   name          = ipv4;
  24   value         = 4;
  25   flags-cant    = ipv6;
  26   descrip       = "Force IPv4 DNS name resolution";
  27   doc           = <<- _EndOfDoc_
  28         Force DNS resolution of the following host names on the command line
  29         to the IPv4 namespace.
  30         _EndOfDoc_;
  31 };
  32
  33 flag = {
  34   name          = ipv6;
  35   value         = 6;
  36   flags-cant    = ipv4;
  37   descrip       = "Force IPv6 DNS name resolution";
  38   doc           = <<- _EndOfDoc_
  39         Force DNS resolution of the following host names on the command line
  40         to the IPv6 namespace.
  41         _EndOfDoc_;
  42 };
  43
  44 flag = {
  45   name          = authentication;
  46   value         = a;
  47   descrip       = "Enable authentication with the key @var{auth-keynumber}";
  48   arg-type      = number;
  49   arg-name      = "auth-keynumber";
  50   doc           = <<- _EndOfDoc_
  51         Enable authentication using the key specified in this option's
  52         argument.  The argument of this option is the @option{keyid}, a
  53         number specified in the @option{keyfile} as this key's identifier.
  54         See the @option{keyfile} option (@option{-k}) for more details.
  55         _EndOfDoc_;
  56 };
  57
  58 flag = {
  59   name          = broadcast;
  60   value         = b;
  61   descrip       = "Listen to the address specified for broadcast time sync";
  62   arg-type      = string;
  63   arg-name      = "broadcast-address";
  64   max            = NOLIMIT;
  65   stack-arg;
  66   doc           = <<- _EndOfDoc_
  67         If specified @code{sntp} will listen to the specified address
  68         for NTP broadcasts.  The default maximum wait time
  69         can (and probably should) be modified with @option{-t}.
  70         _EndOfDoc_;
  71 };
  72
  73 flag = {
  74   name          = concurrent;
  75   value         = c;
  76   descrip       = "Concurrently query all IPs returned for host-name";
  77   arg-type      = string;
  78   arg-name      = "host-name";
  79   max           = NOLIMIT;
  80   stack-arg;
  81   doc           = <<- _EndOfDoc_
  82         Requests from an NTP "client" to a "server" should never be sent
  83         more rapidly than one every 2 seconds.  By default, any IPs returned
  84         as part of a DNS lookup are assumed to be for a single instance of
  85         @code{ntpd}, and therefore @code{sntp} will send queries to these IPs
  86         one after another, with a 2-second gap in between each query.
  87
  88         The @option{-c} or @option{--concurrent} flag says that any IPs
  89         returned for the DNS lookup of the supplied host-name are on
  90         different machines, so we can send concurrent queries.
  91         _EndOfDoc_;
  92 };
  93
  94 #include debug-opt.def
  95
  96 flag = {
  97   name          = gap;
  98   value         = g;
  99   descrip       = "The gap (in milliseconds) between time requests";
 100   arg-type      = number;
 101   arg-name      = "milliseconds";
 102   arg-default   = 50;
 103   doc           = <<- _EndOfDoc_
 104         Since we're only going to use the first valid response we get and
 105         there is benefit to specifying a good number of servers to query,
 106         separate the queries we send out by the specified number of
 107         milliseconds.
 108         _EndOfDoc_;
 109 };
 110
 111 flag = {
 112   name          = kod;
 113   value         = K;
 114   arg-type      = file;
 115   arg-name      = "file-name";
 116   arg-default   = "/var/db/ntp-kod";
 117   descrip       = "KoD history filename";
 118   doc           = <<- _EndOfDoc_
 119         Specifies the filename to be used for the persistent history of KoD
 120         responses received from servers.  If the file does not exist, a
 121         warning message will be displayed.  The file will not be created.
 122         _EndOfDoc_;
 123 };
 124
 125 flag = {
 126   name          = keyfile;
 127   value         = k;
 128   descrip       = "Look in this file for the key specified with @option{-a}";
 129   arg-type      = file;
 130   arg-name      = "file-name";
 131   doc           = <<- _EndOfDoc_
 132         This option specifies the keyfile.
 133         @code{sntp} will search for the key specified with @option{-a}
 134         @file{keyno} in this file.  See @command{ntp.keys(5)} for more
 135         information.
 136         _EndOfDoc_;
 137 };
 138
 139 flag = {
 140   name          = logfile;
 141   value         = l;
 142   arg-type      = file;
 143   arg-name      = "file-name";
 144   descrip       = "Log to specified logfile";
 145   doc           = <<- _EndOfDoc_
 146         This option causes the client to write log messages to the specified
 147         @file{logfile}.
 148         _EndOfDoc_;
 149 };
 150
 151 flag = {
 152   name          = steplimit;
 153   value         = M;
 154   arg-type      = number;
 155   arg-range     = "0->";
 156   descrip       = "Adjustments less than @var{steplimit} msec will be slewed";
 157   doc           = <<- _EndOfDoc_
 158         If the time adjustment is less than @file{steplimit} milliseconds,
 159         slew the amount using @command{adjtime(2)}.  Otherwise, step the
 160         correction using @command{settimeofday(2)}.  The default value is 0,
 161         which means all adjustments will be stepped.  This is a feature, as
 162         different situations demand different values.
 163         _EndOfDoc_;
 164 };
 165
 166 flag = {
 167   name          = ntpversion;
 168   value         = o;
 169   descrip       = "Send @var{int} as our NTP protocol version";
 170   arg-type      = number;
 171   arg-default   = 4;
 172   arg-range     = "0->7";
 173   doc           = <<- _EndOfDoc_
 174         When sending requests to a remote server, tell them we are running
 175         NTP protocol version @file{ntpversion} .
 176         _EndOfDoc_;
 177 };
 178
 179 flag = {
 180   name          = usereservedport;
 181   value         = r;
 182   descrip       = "Use the NTP Reserved Port (port 123)";
 183   doc           = <<- _EndOfDoc_
 184         Use port 123, which is reserved for NTP, for our network
 185         communications.
 186         _EndOfDoc_;
 187 };
 188
 189 flag = {
 190   name          = step;
 191   value         = S;
 192   descrip       = "OK to 'step' the time with @command{settimeofday(2)}";
 193   doc           = <<- _EndOfDoc_
 194         _EndOfDoc_;
 195 };
 196
 197 flag = {
 198   name          = slew;
 199   value         = s;
 200   descrip       = "OK to 'slew' the time with @command{adjtime(2)}";
 201   doc           = <<- _EndOfDoc_
 202         _EndOfDoc_;
 203 };
 204
 205
 206 flag = {
 207   name          = timeout;
 208   value         = t;
 209   descrip       = "The number of seconds to wait for responses";
 210   arg-type      = number;
 211   arg-name      = "seconds";
 212   arg-default   = 5;
 213   doc           = <<- _EndOfDoc_
 214         When waiting for a reply, @code{sntp} will wait the number
 215         of seconds specified before giving up.  The default should be
 216         more than enough for a unicast response.  If @code{sntp} is
 217         only waiting for a broadcast response a longer timeout is
 218         likely needed.
 219         _EndOfDoc_;
 220 };
 221
 222 flag = {
 223   name          = "wait";
 224   descrip       = "Wait for pending replies (if not setting the time)";
 225   disable       = no;
 226   enabled;
 227   settable;
 228   doc           = <<- _EndOfDoc_
 229         If we are not setting the time, wait for all pending responses.
 230         _EndOfDoc_;
 231 };
 232
 233 /* explain: Additional information whenever the usage routine is invoked */
 234 explain = <<- _END_EXPLAIN
 235         _END_EXPLAIN;
 236
 237 doc-section     = {
 238   ds-type       = 'DESCRIPTION';
 239   ds-format     = 'mdoc';
 240   ds-text       = <<- _END_PROG_MDOC_DESCRIP
 241 .Nm
 242 can be used as an SNTP client to query a NTP or SNTP server and either display
 243 the time or set the local system's time (given suitable privilege).  It can be
 244 run as an interactive command or from a
 245 .Ic cron
 246 job.
 247
 248 NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
 249 are defined and described by RFC 5905.
 250
 251 .Pp
 252 The default is to write the estimated correct local date and time (i.e. not
 253 UTC) to the standard output in a format like:
 254
 255 .Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'"
 256
 257 where the
 258 .Ic "'(+0800)'"
 259 means that to get to UTC from the reported local time one must
 260 add 8 hours and 0 minutes,
 261 the
 262 .Ic "'+4.567'"
 263 indicates the local clock is 4.567 seconds behind the correct time
 264 (so 4.567 seconds must be added to the local clock to get it to be correct).
 265 Note that the number of decimals printed for this value will change
 266 based on the reported precision of the server.
 267 .Ic "'+/- 0.089'"
 268 is the reported
 269 .Em synchronization distance
 270 (in seconds), which represents the maximum error due to all causes.
 271 If the server does not report valid data needed to calculate the
 272 synchronization distance, this will be reported as
 273 .Ic "'+/- ?'" .
 274 If the
 275 .Em host
 276 is different from the
 277 .Em IP ,
 278 both will be displayed.
 279 Otherwise, only the
 280 .Em IP
 281 is displayed.
 282 Finally, the
 283 .Em stratum
 284 of the host is reported
 285 and the leap indicator is decoded and displayed.
 286         _END_PROG_MDOC_DESCRIP;
 287 };
 288
 289 doc-section     = {
 290   ds-type       = 'USAGE';
 291   ds-format     = 'mdoc';
 292   ds-text       = <<- _END_MDOC_USAGE
 293 .Bl -tag -width indent
 294 .It Li "sntp ntpserver.somewhere"
 295 is the simplest use of this program
 296 and can be run as an unprivileged command
 297 to check the current time and error in the local clock.
 298 .It Li "sntp -Ss -M 128 ntpserver.somewhere"
 299 With suitable privilege,
 300 run as a command
 301 or from a
 302 .Xr cron 8
 303 job,
 304 .Ic "sntp -Ss -M 128 ntpserver.somewhere"
 305 will request the time from the server,
 306 and if that server reports that it is synchronized
 307 then if the offset adjustment is less than 128 milliseconds
 308 the correction will be slewed,
 309 and if the correction is more than 128 milliseconds
 310 the correction  will be stepped.
 311 .It Li "sntp -S ntpserver.somewhere"
 312 With suitable privilege,
 313 run as a command
 314 or from a
 315 .Xr cron 8
 316 job,
 317 .Ic "sntp -S ntpserver.somewhere"
 318 will set (step) the local clock from a synchronized specified server,
 319 like the (deprecated)
 320 .Xr ntpdate 1ntpdatemdoc ,
 321 or
 322 .Xr rdate 8
 323 commands.
 324 .El
 325         _END_MDOC_USAGE;
 326 };
 327
 328 doc-section     = {
 329   ds-type       = 'AUTHORS';
 330   ds-format     = 'mdoc';
 331   ds-text       = <<- _END_MDOC_AUTHORS
 332 .An "Johannes Maximilian Kuehn"
 333 .An "Harlan Stenn"
 334 .An "Dave Hart"
 335         _END_MDOC_AUTHORS;
 336 };