sntp-opts.def revision 1.1.1.6
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 }; 338
Indexes created Tue Mar 24 00:24:13 UTC 2026