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   arg-default   = "/etc/ntp.keys";
 132   doc           = <<- _EndOfDoc_
 133         This option specifies the keyfile.
 134         @code{sntp} will search for the key specified with @option{-a}
 135         @file{keyno} in this file.  See @command{ntp.keys(5)} for more
 136         information.
 137         _EndOfDoc_;
 138 };
 139
 140 flag = {
 141   name          = logfile;
 142   value         = l;
 143   arg-type      = file;
 144   arg-name      = "file-name";
 145   descrip       = "Log to specified logfile";
 146   doc           = <<- _EndOfDoc_
 147         This option causes the client to write log messages to the specified
 148         @file{logfile}.
 149         _EndOfDoc_;
 150 };
 151
 152 flag = {
 153   name          = steplimit;
 154   value         = M;
 155   arg-type      = number;
 156   arg-range     = "0->";
 157   descrip       = "Adjustments less than @var{steplimit} msec will be slewed";
 158   doc           = <<- _EndOfDoc_
 159         If the time adjustment is less than @file{steplimit} milliseconds,
 160         slew the amount using @command{adjtime(2)}.  Otherwise, step the
 161         correction using @command{settimeofday(2)}.  The default value is 0,
 162         which means all adjustments will be stepped.  This is a feature, as
 163         different situations demand different values.
 164         _EndOfDoc_;
 165 };
 166
 167 flag = {
 168   name          = ntpversion;
 169   value         = o;
 170   descrip       = "Send @var{int} as our NTP protocol version";
 171   arg-type      = number;
 172   arg-default   = 4;
 173   arg-range     = "0->7";
 174   doc           = <<- _EndOfDoc_
 175         When sending requests to a remote server, tell them we are running
 176         NTP protocol version @file{ntpversion} .
 177         _EndOfDoc_;
 178 };
 179
 180 flag = {
 181   name          = usereservedport;
 182   value         = r;
 183   descrip       = "Use the NTP Reserved Port (port 123)";
 184   doc           = <<- _EndOfDoc_
 185         Use port 123, which is reserved for NTP, for our network
 186         communications.
 187         _EndOfDoc_;
 188 };
 189
 190 flag = {
 191   name          = step;
 192   value         = S;
 193   descrip       = "OK to 'step' the time with @command{settimeofday(2)}";
 194   doc           = <<- _EndOfDoc_
 195         _EndOfDoc_;
 196 };
 197
 198 flag = {
 199   name          = slew;
 200   value         = s;
 201   descrip       = "OK to 'slew' the time with @command{adjtime(2)}";
 202   doc           = <<- _EndOfDoc_
 203         _EndOfDoc_;
 204 };
 205
 206
 207 flag = {
 208   name          = timeout;
 209   value         = t;
 210   descrip       = "The number of seconds to wait for responses";
 211   arg-type      = number;
 212   arg-name      = "seconds";
 213   arg-default   = 5;
 214   doc           = <<- _EndOfDoc_
 215         When waiting for a reply, @code{sntp} will wait the number
 216         of seconds specified before giving up.  The default should be
 217         more than enough for a unicast response.  If @code{sntp} is
 218         only waiting for a broadcast response a longer timeout is
 219         likely needed.
 220         _EndOfDoc_;
 221 };
 222
 223 flag = {
 224   name          = "wait";
 225   descrip       = "Wait for pending replies (if not setting the time)";
 226   disable       = no;
 227   enabled;
 228   settable;
 229   doc           = <<- _EndOfDoc_
 230         If we are not setting the time, wait for all pending responses.
 231         _EndOfDoc_;
 232 };
 233
 234 /* explain: Additional information whenever the usage routine is invoked */
 235 explain = <<- _END_EXPLAIN
 236         _END_EXPLAIN;
 237
 238 doc-section     = {
 239   ds-type       = 'DESCRIPTION';
 240   ds-format     = 'mdoc';
 241   ds-text       = <<- _END_PROG_MDOC_DESCRIP
 242 .Nm
 243 can be used as an SNTP client to query a NTP or SNTP server and either display
 244 the time or set the local system's time (given suitable privilege).  It can be
 245 run as an interactive command or from a
 246 .Ic cron
 247 job.
 248
 249 NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
 250 are defined and described by RFC 5905.
 251
 252 .Pp
 253 The default is to write the estimated correct local date and time (i.e. not
 254 UTC) to the standard output in a format like:
 255
 256 .Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'"
 257
 258 where the
 259 .Ic "'(+0800)'"
 260 means that to get to UTC from the reported local time one must
 261 add 8 hours and 0 minutes,
 262 the
 263 .Ic "'+4.567'"
 264 indicates the local clock is 4.567 seconds behind the correct time
 265 (so 4.567 seconds must be added to the local clock to get it to be correct).
 266 Note that the number of decimals printed for this value will change
 267 based on the reported precision of the server.
 268 .Ic "'+/- 0.089'"
 269 is the reported
 270 .Em synchronization distance
 271 (in seconds), which represents the maximum error due to all causes.
 272 If the server does not report valid data needed to calculate the
 273 synchronization distance, this will be reported as
 274 .Ic "'+/- ?'" .
 275 If the
 276 .Em host
 277 is different from the
 278 .Em IP ,
 279 both will be displayed.
 280 Otherwise, only the
 281 .Em IP
 282 is displayed.
 283 Finally, the
 284 .Em stratum
 285 of the host is reported
 286 and the leap indicator is decoded and displayed.
 287         _END_PROG_MDOC_DESCRIP;
 288 };
 289
 290 doc-section     = {
 291   ds-type       = 'USAGE';
 292   ds-format     = 'mdoc';
 293   ds-text       = <<- _END_MDOC_USAGE
 294 .Bl -tag -width indent
 295 .It Li "sntp ntpserver.somewhere"
 296 is the simplest use of this program
 297 and can be run as an unprivileged command
 298 to check the current time and error in the local clock.
 299 .It Li "sntp -Ss -M 128 ntpserver.somewhere"
 300 With suitable privilege,
 301 run as a command
 302 or from a
 303 .Xr cron 8
 304 job,
 305 .Ic "sntp -Ss -M 128 ntpserver.somewhere"
 306 will request the time from the server,
 307 and if that server reports that it is synchronized
 308 then if the offset adjustment is less than 128 milliseconds
 309 the correction will be slewed,
 310 and if the correction is more than 128 milliseconds
 311 the correction  will be stepped.
 312 .It Li "sntp -S ntpserver.somewhere"
 313 With suitable privilege,
 314 run as a command
 315 or from a
 316 .Xr cron 8
 317 job,
 318 .Ic "sntp -S ntpserver.somewhere"
 319 will set (step) the local clock from a synchronized specified server,
 320 like the (deprecated)
 321 .Xr ntpdate 1ntpdatemdoc ,
 322 or
 323 .Xr rdate 8
 324 commands.
 325 .El
 326         _END_MDOC_USAGE;
 327 };
 328
 329 doc-section     = {
 330   ds-type       = 'AUTHORS';
 331   ds-format     = 'mdoc';
 332   ds-text       = <<- _END_MDOC_AUTHORS
 333 .An "Johannes Maximilian Kuehn"
 334 .An "Harlan Stenn"
 335 .An "Dave Hart"
 336         _END_MDOC_AUTHORS;
 337 };