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