1/* -*- Mode: Text -*- */ 2 3autogen definitions options; 4 5#include autogen-version.def 6#include copyright.def 7 8prog-name = "sntp"; 9prog-title = "reference Simple Network Time Protocol client"; 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 22flag = { 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 33flag = { 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 44flag = { 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 58flag = { 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 73flag = { 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 96flag = { 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 111flag = { 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 125flag = { 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 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)}. 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 167flag = { 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 180flag = { 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 190flag = { 191 name = step; 192 value = S; 193 descrip = "OK to 'step' the time with @command{settimeofday(2)}"; 194 doc = <<- _EndOfDoc_ 195 _EndOfDoc_; 196}; 197 198flag = { 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 207flag = { 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 223flag = { 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 */ 235explain = <<- _END_EXPLAIN 236 _END_EXPLAIN; 237 238doc-section = { 239 ds-type = 'DESCRIPTION'; 240 ds-format = 'mdoc'; 241 ds-text = <<- _END_PROG_MDOC_DESCRIP 242.Nm 243can be used as an SNTP client to query a NTP or SNTP server and either display 244the time or set the local system's time (given suitable privilege). It can be 245run as an interactive command or from a 246.Ic cron 247job. 248 249NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) 250are defined and described by RFC 5905. 251 252.Pp 253The default is to write the estimated correct local date and time (i.e. not 254UTC) 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 258where the 259.Ic "'(+0800)'" 260means that to get to UTC from the reported local time one must 261add 8 hours and 0 minutes, 262the 263.Ic "'+4.567'" 264indicates 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). 266Note that the number of decimals printed for this value will change 267based on the reported precision of the server. 268.Ic "'+/- 0.089'" 269is the reported 270.Em synchronization distance 271(in seconds), which represents the maximum error due to all causes. 272If the server does not report valid data needed to calculate the 273synchronization distance, this will be reported as 274.Ic "'+/- ?'" . 275If the 276.Em host 277is different from the 278.Em IP , 279both will be displayed. 280Otherwise, only the 281.Em IP 282is displayed. 283Finally, the 284.Em stratum 285of the host is reported 286and the leap indicator is decoded and displayed. 287 _END_PROG_MDOC_DESCRIP; 288}; 289 290doc-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" 296is the simplest use of this program 297and can be run as an unprivileged command 298to check the current time and error in the local clock. 299.It Li "sntp -Ss -M 128 ntpserver.somewhere" 300With suitable privilege, 301run as a command 302or from a 303.Xr cron 8 304job, 305.Ic "sntp -Ss -M 128 ntpserver.somewhere" 306will request the time from the server, 307and if that server reports that it is synchronized 308then if the offset adjustment is less than 128 milliseconds 309the correction will be slewed, 310and if the correction is more than 128 milliseconds 311the correction will be stepped. 312.It Li "sntp -S ntpserver.somewhere" 313With suitable privilege, 314run as a command 315or from a 316.Xr cron 8 317job, 318.Ic "sntp -S ntpserver.somewhere" 319will set (step) the local clock from a synchronized specified server, 320like the (deprecated) 321.Xr ntpdate 1ntpdatemdoc , 322or 323.Xr rdate 8 324commands. 325.El 326 _END_MDOC_USAGE; 327}; 328 329doc-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