sntp-opts.def revision 280849
1181834Sroberto/* -*- Mode: Text -*- */ 2181834Sroberto 3181834Srobertoautogen definitions options; 4181834Sroberto 5181834Sroberto#include autogen-version.def 6280849Scy#include copyright.def 7181834Sroberto 8280849Scyprog-name = "sntp"; 9280849Scyprog-title = "standard Simple Network Time Protocol client program"; 10280849Scyargument = '[ hostname-or-IP ...]'; 11181834Sroberto 12280849Scy#include homerc.def 13181834Sroberto 14181834Srobertolong-opts; 15181834Sroberto 16280849Scyconfig-header = "config.h"; 17181834Sroberto 18181834Srobertoenvironrc; 19181834Sroberto 20181834Sroberto#include version.def 21181834Sroberto 22181834Srobertoflag = { 23280849Scy name = ipv4; 24280849Scy value = 4; 25280849Scy flags-cant = ipv6; 26280849Scy descrip = "Force IPv4 DNS name resolution"; 27280849Scy doc = <<- _EndOfDoc_ 28280849Scy Force DNS resolution of the following host names on the command line 29181834Sroberto to the IPv4 namespace. 30181834Sroberto _EndOfDoc_; 31181834Sroberto}; 32181834Sroberto 33181834Srobertoflag = { 34280849Scy name = ipv6; 35280849Scy value = 6; 36280849Scy flags-cant = ipv4; 37280849Scy descrip = "Force IPv6 DNS name resolution"; 38280849Scy doc = <<- _EndOfDoc_ 39280849Scy Force DNS resolution of the following host names on the command line 40181834Sroberto to the IPv6 namespace. 41181834Sroberto _EndOfDoc_; 42181834Sroberto}; 43181834Sroberto 44181834Srobertoflag = { 45280849Scy name = authentication; 46280849Scy value = a; 47280849Scy descrip = "Enable authentication with the key @var{auth-keynumber}"; 48280849Scy arg-type = number; 49280849Scy arg-name = "auth-keynumber"; 50280849Scy doc = <<- _EndOfDoc_ 51280849Scy Enable authentication using the key specified in this option's 52280849Scy argument. The argument of this option is the @option{keyid}, a 53280849Scy number specified in the @option{keyfile} as this key's identifier. 54280849Scy See the @option{keyfile} option (@option{-k}) for more details. 55181834Sroberto _EndOfDoc_; 56181834Sroberto}; 57181834Sroberto 58181834Srobertoflag = { 59280849Scy name = broadcast; 60280849Scy value = b; 61280849Scy descrip = "Listen to the address specified for broadcast time sync"; 62280849Scy arg-type = string; 63280849Scy arg-name = "broadcast-address"; 64280849Scy max = NOLIMIT; 65280849Scy stack-arg; 66280849Scy doc = <<- _EndOfDoc_ 67280849Scy If specified @code{sntp} will listen to the specified address 68280849Scy for NTP broadcasts. The default maximum wait time 69280849Scy can (and probably should) be modified with @option{-t}. 70181834Sroberto _EndOfDoc_; 71181834Sroberto}; 72181834Sroberto 73181834Srobertoflag = { 74280849Scy name = concurrent; 75280849Scy value = c; 76280849Scy descrip = "Concurrently query all IPs returned for host-name"; 77280849Scy arg-type = string; 78280849Scy arg-name = "host-name"; 79280849Scy max = NOLIMIT; 80280849Scy stack-arg; 81280849Scy doc = <<- _EndOfDoc_ 82280849Scy Requests from an NTP "client" to a "server" should never be sent 83280849Scy more rapidly than one every 2 seconds. By default, any IPs returned 84280849Scy as part of a DNS lookup are assumed to be for a single instance of 85280849Scy @code{ntpd}, and therefore @code{sntp} will send queries to these IPs 86280849Scy one after another, with a 2-second gap in between each query. 87280849Scy 88280849Scy The @option{-c} or @option{--concurrent} flag says that any IPs 89280849Scy returned for the DNS lookup of the supplied host-name are on 90280849Scy different machines, so we can send concurrent queries. 91181834Sroberto _EndOfDoc_; 92181834Sroberto}; 93181834Sroberto 94280849Scy#include debug-opt.def 95280849Scy 96181834Srobertoflag = { 97280849Scy name = gap; 98280849Scy value = g; 99280849Scy descrip = "The gap (in milliseconds) between time requests"; 100280849Scy arg-type = number; 101280849Scy arg-name = "milliseconds"; 102280849Scy arg-default = 50; 103280849Scy doc = <<- _EndOfDoc_ 104280849Scy Since we're only going to use the first valid response we get and 105280849Scy there is benefit to specifying a good number of servers to query, 106280849Scy separate the queries we send out by the specified number of 107280849Scy milliseconds. 108181834Sroberto _EndOfDoc_; 109181834Sroberto}; 110181834Sroberto 111181834Srobertoflag = { 112280849Scy name = kod; 113280849Scy value = K; 114280849Scy arg-type = file; 115280849Scy arg-name = "file-name"; 116280849Scy arg-default = "/var/db/ntp-kod"; 117280849Scy descrip = "KoD history filename"; 118280849Scy doc = <<- _EndOfDoc_ 119280849Scy Specifies the filename to be used for the persistent history of KoD 120280849Scy responses received from servers. If the file does not exist, a 121280849Scy warning message will be displayed. The file will not be created. 122181834Sroberto _EndOfDoc_; 123181834Sroberto}; 124181834Sroberto 125181834Srobertoflag = { 126280849Scy name = keyfile; 127280849Scy value = k; 128280849Scy descrip = "Look in this file for the key specified with @option{-a}"; 129280849Scy arg-type = file; 130280849Scy arg-name = "file-name"; 131280849Scy doc = <<- _EndOfDoc_ 132280849Scy This option specifies the keyfile. 133280849Scy @code{sntp} will search for the key specified with @option{-a} 134280849Scy @file{keyno} in this file. See @command{ntp.keys(5)} for more 135280849Scy information. 136181834Sroberto _EndOfDoc_; 137181834Sroberto}; 138181834Sroberto 139280849Scyflag = { 140280849Scy name = logfile; 141280849Scy value = l; 142280849Scy arg-type = file; 143280849Scy arg-name = "file-name"; 144280849Scy descrip = "Log to specified logfile"; 145280849Scy doc = <<- _EndOfDoc_ 146280849Scy This option causes the client to write log messages to the specified 147280849Scy @file{logfile}. 148280849Scy _EndOfDoc_; 149280849Scy}; 150280849Scy 151280849Scyflag = { 152280849Scy name = steplimit; 153280849Scy value = M; 154280849Scy arg-type = number; 155280849Scy arg-range = "0->"; 156280849Scy descrip = "Adjustments less than @var{steplimit} msec will be slewed"; 157280849Scy doc = <<- _EndOfDoc_ 158280849Scy If the time adjustment is less than @file{steplimit} milliseconds, 159280849Scy slew the amount using @command{adjtime(2)}. Otherwise, step the 160280849Scy correction using @command{settimeofday(2)}. The default value is 0, 161280849Scy which means all adjustments will be stepped. This is a feature, as 162280849Scy different situations demand different values. 163280849Scy _EndOfDoc_; 164280849Scy}; 165280849Scy 166280849Scyflag = { 167280849Scy name = ntpversion; 168280849Scy value = o; 169280849Scy descrip = "Send @var{int} as our NTP protocol version"; 170280849Scy arg-type = number; 171280849Scy arg-default = 4; 172280849Scy arg-range = "0->7"; 173280849Scy doc = <<- _EndOfDoc_ 174280849Scy When sending requests to a remote server, tell them we are running 175280849Scy NTP protocol version @file{ntpversion} . 176280849Scy _EndOfDoc_; 177280849Scy}; 178280849Scy 179280849Scyflag = { 180280849Scy name = usereservedport; 181280849Scy value = r; 182280849Scy descrip = "Use the NTP Reserved Port (port 123)"; 183280849Scy doc = <<- _EndOfDoc_ 184280849Scy Use port 123, which is reserved for NTP, for our network 185280849Scy communications. 186280849Scy _EndOfDoc_; 187280849Scy}; 188280849Scy 189280849Scyflag = { 190280849Scy name = step; 191280849Scy value = S; 192280849Scy descrip = "OK to 'step' the time with @command{settimeofday(2)}"; 193280849Scy doc = <<- _EndOfDoc_ 194280849Scy _EndOfDoc_; 195280849Scy}; 196280849Scy 197280849Scyflag = { 198280849Scy name = slew; 199280849Scy value = s; 200280849Scy descrip = "OK to 'slew' the time with @command{adjtime(2)}"; 201280849Scy doc = <<- _EndOfDoc_ 202280849Scy _EndOfDoc_; 203280849Scy}; 204280849Scy 205280849Scy 206280849Scyflag = { 207280849Scy name = timeout; 208280849Scy value = t; 209280849Scy descrip = "The number of seconds to wait for responses"; 210280849Scy arg-type = number; 211280849Scy arg-name = "seconds"; 212280849Scy arg-default = 5; 213280849Scy doc = <<- _EndOfDoc_ 214280849Scy When waiting for a reply, @code{sntp} will wait the number 215280849Scy of seconds specified before giving up. The default should be 216280849Scy more than enough for a unicast response. If @code{sntp} is 217280849Scy only waiting for a broadcast response a longer timeout is 218280849Scy likely needed. 219280849Scy _EndOfDoc_; 220280849Scy}; 221280849Scy 222280849Scyflag = { 223280849Scy name = "wait"; 224280849Scy descrip = "Wait for pending replies (if not setting the time)"; 225280849Scy disable = no; 226280849Scy enabled; 227280849Scy settable; 228280849Scy doc = <<- _EndOfDoc_ 229280849Scy If we are not setting the time, wait for all pending responses. 230280849Scy _EndOfDoc_; 231280849Scy}; 232280849Scy 233280849Scy/* explain: Additional information whenever the usage routine is invoked */ 234280849Scyexplain = <<- _END_EXPLAIN 235280849Scy _END_EXPLAIN; 236280849Scy 237280849Scydoc-section = { 238280849Scy ds-type = 'DESCRIPTION'; 239280849Scy ds-format = 'mdoc'; 240280849Scy ds-text = <<- _END_PROG_MDOC_DESCRIP 241280849Scy.Nm 242280849Scycan be used as an SNTP client to query a NTP or SNTP server and either display 243181834Srobertothe time or set the local system's time (given suitable privilege). It can be 244280849Scyrun as an interactive command or from a 245280849Scy.Ic cron 246181834Srobertojob. 247181834Sroberto 248280849ScyNTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) 249280849Scyare defined and described by RFC 5905. 250280849Scy 251280849Scy.Pp 252181834SrobertoThe default is to write the estimated correct local date and time (i.e. not 253280849ScyUTC) to the standard output in a format like: 254280849Scy 255280849Scy.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'" 256280849Scy 257181834Srobertowhere the 258280849Scy.Ic "'(+0800)'" 259280849Scymeans that to get to UTC from the reported local time one must 260280849Scyadd 8 hours and 0 minutes, 261280849Scythe 262280849Scy.Ic "'+4.567'" 263280849Scyindicates the local clock is 4.567 seconds behind the correct time 264280849Scy(so 4.567 seconds must be added to the local clock to get it to be correct). 265280849ScyNote that the number of decimals printed for this value will change 266280849Scybased on the reported precision of the server. 267280849Scy.Ic "'+/- 0.089'" 268280849Scyis the reported 269280849Scy.Em synchronization distance 270280849Scy(in seconds), which represents the maximum error due to all causes. 271280849ScyIf the server does not report valid data needed to calculate the 272280849Scysynchronization distance, this will be reported as 273280849Scy.Ic "'+/- ?'" . 274280849ScyIf the 275280849Scy.Em host 276280849Scyis different from the 277280849Scy.Em IP , 278280849Scyboth will be displayed. 279280849ScyOtherwise, only the 280280849Scy.Em IP 281280849Scyis displayed. 282280849ScyFinally, the 283280849Scy.Em stratum 284280849Scyof the host is reported. 285280849Scy _END_PROG_MDOC_DESCRIP; 286280849Scy}; 287280849Scy 288280849Scydoc-section = { 289280849Scy ds-type = 'USAGE'; 290280849Scy ds-format = 'mdoc'; 291280849Scy ds-text = <<- _END_MDOC_USAGE 292280849Scy.Bl -tag -width indent 293280849Scy.It Li "sntp ntpserver.somewhere" 294280849Scyis the simplest use of this program 295280849Scyand can be run as an unprivileged command 296280849Scyto check the current time and error in the local clock. 297280849Scy.It Li "sntp -Ss -M 128 ntpserver.somewhere" 298280849ScyWith suitable privilege, 299280849Scyrun as a command 300280849Scyor from a 301280849Scy.Xr cron 8 302280849Scyjob, 303280849Scy.Ic "sntp -Ss -M 128 ntpserver.somewhere" 304280849Scywill request the time from the server, 305280849Scyand if that server reports that it is synchronized 306280849Scythen if the offset adjustment is less than 128 milliseconds 307280849Scythe correction will be slewed, 308280849Scyand if the correction is more than 128 milliseconds 309280849Scythe correction will be stepped. 310280849Scy.It Li "sntp -S ntpserver.somewhere" 311280849ScyWith suitable privilege, 312280849Scyrun as a command 313280849Scyor from a 314280849Scy.Xr cron 8 315280849Scyjob, 316280849Scy.Ic "sntp -S ntpserver.somewhere" 317280849Scywill set (step) the local clock from a synchronized specified server, 318280849Scylike the (deprecated) 319280849Scy.Xr ntpdate 1ntpdatemdoc , 320280849Scyor 321280849Scy.Xr rdate 8 322280849Scycommands. 323280849Scy.El 324280849Scy _END_MDOC_USAGE; 325280849Scy}; 326280849Scy 327280849Scydoc-section = { 328280849Scy ds-type = 'AUTHORS'; 329280849Scy ds-format = 'mdoc'; 330280849Scy ds-text = <<- _END_MDOC_AUTHORS 331280849Scy.An "Johannes Maximilian Kuehn" 332280849Scy.An "Harlan Stenn" 333280849Scy.An "Dave Hart" 334280849Scy _END_MDOC_AUTHORS; 335280849Scy}; 336