sntp-opts.def revision 1.1.1.2.16.2
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 }; 337
Indexes created Thu Mar 26 00:23:24 UTC 2026