_EndOfDoc_;
};
-detail = <<- _END_DETAIL
- The
- [= prog-name =]
- utility program is used to query NTP servers which
- implement the standard NTP mode 6 control message formats defined
- in Appendix B of the NTPv3 specification RFC1305, requesting
- information about current state and/or changes in that state.
- The same formats are used in NTPv4, although some of the
- variables have changed and new ones added.
- _END_DETAIL;
+doc-section = {
+ ds-type = 'DESCRIPTION';
+ ds-format = 'mdoc';
+ ds-text = <<- _END_PROG_MDOC_DESCRIP
-prog-man-descrip = <<- _END_PROG_MAN_DESCRIP
- The
- [= prog-name =]
- utility program is used to query NTP servers which
- implement the standard NTP mode 6 control message formats defined
- in Appendix B of the NTPv3 specification RFC1305, requesting
- information about current state and/or changes in that state.
- The same formats are used in NTPv4, although some of the
- variables have changed and new ones added. The description on this
- page is for the NTPv4 variables.
- The program may be run either in interactive mode or controlled using
- command line arguments.
- Requests to read and write arbitrary
- variables can be assembled, with raw and pretty-printed output
- options being available.
- The
- [= prog-name =]
- utility can also obtain and print a
- list of peers in a common format by sending multiple queries to the
- server.
+The
+.Nm
+utility program is used to query NTP servers which
+implement the standard NTP mode 6 control message formats defined
+in Appendix B of the NTPv3 specification RFC1305, requesting
+information about current state and/or changes in that state.
+The same formats are used in NTPv4, although some of the
+variables have changed and new ones added. The description on this
+page is for the NTPv4 variables.
+The program may be run either in interactive mode or controlled using
+command line arguments.
+Requests to read and write arbitrary
+variables can be assembled, with raw and pretty-printed output
+options being available.
+The
+.Nm
+utility can also obtain and print a
+list of peers in a common format by sending multiple queries to the
+server.
- If one or more request options is included on the command line
- when
- [= prog-name =]
- is executed, each of the requests will be sent
- to the NTP servers running on each of the hosts given as command
- line arguments, or on localhost by default.
- If no request options
- are given,
- [= prog-name =]
- will attempt to read commands from the
- standard input and execute these on the NTP server running on the
- first host given on the command line, again defaulting to localhost
- when no other host is specified.
- The
- [= prog-name =]
- utility will prompt for
- commands if the standard input is a terminal device.
+If one or more request options is included on the command line
+when
+.Nm
+is executed, each of the requests will be sent
+to the NTP servers running on each of the hosts given as command
+line arguments, or on localhost by default.
+If no request options
+are given,
+.Nm
+will attempt to read commands from the
+standard input and execute these on the NTP server running on the
+first host given on the command line, again defaulting to localhost
+when no other host is specified.
+The
+.Nm
+utility will prompt for
+commands if the standard input is a terminal device.
- The
- [= prog-name =]
- utility uses NTP mode 6 packets to communicate with the
- NTP server, and hence can be used to query any compatible server on
- the network which permits it.
- Note that since NTP is a UDP protocol
- this communication will be somewhat unreliable, especially over
- large distances in terms of network topology.
- The
- [= prog-name =]
- utility makes
- one attempt to retransmit requests, and will time requests out if
- the remote host is not heard from within a suitable timeout
- time.
+.Nm
+uses NTP mode 6 packets to communicate with the
+NTP server, and hence can be used to query any compatible server on
+the network which permits it.
+Note that since NTP is a UDP protocol
+this communication will be somewhat unreliable, especially over
+large distances in terms of network topology.
+The
+.Nm
+utility makes
+one attempt to retransmit requests, and will time requests out if
+the remote host is not heard from within a suitable timeout
+time.
- Specifying a
- command line option other than
- .Fl i
- or
- .Fl n
- will
- cause the specified query (queries) to be sent to the indicated
- host(s) immediately.
- Otherwise,
- [= prog-name =]
- will attempt to read
- interactive format commands from the standard input.
- .Ss "Internal Commands"
- Interactive format commands consist of a keyword followed by zero
- to four arguments.
- Only enough characters of the full keyword to
- uniquely identify the command need be typed.
+Specifying a
+command line option other than
+.Fl i
+or
+.Fl n
+will
+cause the specified query (queries) to be sent to the indicated
+host(s) immediately.
+Otherwise,
+.Nm
+will attempt to read
+interactive format commands from the standard input.
+.Ss "Internal Commands"
+Interactive format commands consist of a keyword followed by zero
+to four arguments.
+Only enough characters of the full keyword to
+uniquely identify the command need be typed.
- A
- number of interactive format commands are executed entirely within
- the
- [= prog-name =]
- utility itself and do not result in NTP mode 6
- requests being sent to a server.
- These are described following.
- @table @code
- @item ? [command_keyword]
- @itemx help [command_keyword]
- A
- .Ql \&?
- by itself will print a list of all the command
- keywords known to this incarnation of
- [= prog-name =] .
- A
- .Ql \&?
- followed by a command keyword will print function and usage
- information about the command.
- This command is probably a better
- source of information about
- [= prog-name =]
- than this manual
- page.
- @item addvars
- .Ar variable_name [=value] ...
- .Xc
- @item rmvars variable_name ...
- @item clearvars
- The data carried by NTP mode 6 messages consists of a list of
- items of the form
- .Ql variable_name=value ,
- where the
- .Ql =value
- is ignored, and can be omitted,
- in requests to the server to read variables.
- The
- [= prog-name =]
- utility maintains an internal list in which data to be included in control
- messages can be assembled, and sent using the
- .Ic readlist
- and
- .Ic writelist
- commands described below.
- The
- .Ic addvars
- command allows variables and their optional values to be added to
- the list.
- If more than one variable is to be added, the list should
- be comma-separated and not contain white space.
- The
- .Ic rmvars
- command can be used to remove individual variables from the list,
- while the
- .Ic clearlist
- command removes all variables from the
- list.
- @item authenticate [ yes | no ]
- Normally
- [= prog-name =]
- does not authenticate requests unless
- they are write requests.
- The command
- .Ql authenticate yes
- causes
- [= prog-name =]
- to send authentication with all requests it
- makes.
- Authenticated requests causes some servers to handle
- requests slightly differently, and can occasionally melt the CPU in
- fuzzballs if you turn authentication on before doing a
- .Ic peer
- display.
- The command
- .Ql authenticate
- causes
- [= prog-name =]
- to display whether or not
- [= prog-name =]
- is currently autheinticating requests.
- @item cooked
- Causes output from query commands to be "cooked", so that
- variables which are recognized by
- [= prog-name =]
- will have their
- values reformatted for human consumption.
- Variables which
- [= prog-name =]
- thinks should have a decodable value but didn't are
- marked with a trailing
- .Ql \&? .
- .@item debug [
- .Cm more |
- .Cm less |
- .Cm off
- ]
- .Xc
- With no argument, displays the current debug level.
- Otherwise, the debug level is changed to the indicated level.
- @item delay milliseconds
- Specify a time interval to be added to timestamps included in
- requests which require authentication.
- This is used to enable
- (unreliable) server reconfiguration over long delay network paths
- or between machines whose clocks are unsynchronized.
- Actually the
- server does not now require timestamps in authenticated requests,
- so this command may be obsolete.
- @item host hostname
- Set the host to which future queries will be sent.
- Hostname may
- be either a host name or a numeric address.
- @item hostnames Cm yes | Cm no
- If
- .Cm yes
- is specified, host names are printed in
- information displays.
- If
- .Cm no
- is specified, numeric
- addresses are printed instead.
- The default is
- .Cm yes ,
- unless
- modified using the command line
- .Fl n
- switch.
- @item keyid keyid
- This command allows the specification of a key number to be
- used to authenticate configuration requests.
- This must correspond
- to a key number the server has been configured to use for this
- purpose.
- @item ntpversion [
- .Cm 1 |
- .Cm 2 |
- .Cm 3 |
- .Cm 4
- ]
- .Xc
- Sets the NTP version number which
- [= prog-name =]
- claims in
- packets.
- Defaults to 3, Note that mode 6 control messages (and
- modes, for that matter) didn't exist in NTP version 1.
- There appear
- to be no servers left which demand version 1.
- With no argument, displays the current NTP version that will be used
- when communicating with servers.
- @item quit
- Exit
- [= prog-name =] .
- @item passwd
- This command prompts you to type in a password (which will not
- be echoed) which will be used to authenticate configuration
- requests.
- The password must correspond to the key configured for
- use by the NTP server for this purpose if such requests are to be
- successful.
- @item raw
- Causes all output from query commands is printed as received
- from the remote server.
- The only formating/interpretation done on
- the data is to transform nonascii data into a printable (but barely
- understandable) form.
- @item timeout Ar milliseconds
- Specify a timeout period for responses to server queries.
- The
- default is about 5000 milliseconds.
- Note that since
- [= prog-name =]
- retries each query once after a timeout, the total waiting time for
- a timeout will be twice the timeout value set.
- @end table
+A
+number of interactive format commands are executed entirely within
+the
+.Nm
+utility itself and do not result in NTP mode 6
+requests being sent to a server.
+These are described following.
+.Bl -tag -width "? [command_keyword]" -compact -offset indent
+.It Ic ? Op Ar command_keyword
+.It Ic help Op Ar command_keyword
+A
+.Ql \&?
+by itself will print a list of all the command
+keywords known to this incarnation of
+.Nm .
+A
+.Ql \&?
+followed by a command keyword will print function and usage
+information about the command.
+This command is probably a better
+source of information about
+.Nm
+than this manual
+page.
+.It Ic addvars Ar variable_name Xo Op Ic =value
+.Ic ...
+.Xc
+.It Ic rmvars Ar variable_name Ic ...
+.It Ic clearvars
+The data carried by NTP mode 6 messages consists of a list of
+items of the form
+.Ql variable_name=value ,
+where the
+.Ql =value
+is ignored, and can be omitted,
+in requests to the server to read variables.
+The
+.Nm
+utility maintains an internal list in which data to be included in control
+messages can be assembled, and sent using the
+.Ic readlist
+and
+.Ic writelist
+commands described below.
+The
+.Ic addvars
+command allows variables and their optional values to be added to
+the list.
+If more than one variable is to be added, the list should
+be comma-separated and not contain white space.
+The
+.Ic rmvars
+command can be used to remove individual variables from the list,
+while the
+.Ic clearlist
+command removes all variables from the
+list.
+.It Ic authenticate Op yes | no
+Normally
+.Nm
+does not authenticate requests unless
+they are write requests.
+The command
+.Ql authenticate yes
+causes
+.Nm
+to send authentication with all requests it
+makes.
+Authenticated requests causes some servers to handle
+requests slightly differently, and can occasionally melt the CPU in
+fuzzballs if you turn authentication on before doing a
+.Ic peer
+display.
+The command
+.Ql authenticate
+causes
+.Nm
+to display whether or not
+.Nm
+is currently autheinticating requests.
+.It Ic cooked
+Causes output from query commands to be "cooked", so that
+variables which are recognized by
+.Nm
+will have their
+values reformatted for human consumption.
+Variables which
+.Nm
+thinks should have a decodable value but didn't are
+marked with a trailing
+.Ql \&? .
+.It Xo
+.Ic debug
+.Oo
+.Cm more |
+.Cm less |
+.Cm off
+.Oc
+.Xc
+With no argument, displays the current debug level.
+Otherwise, the debug level is changed to the indicated level.
+.It Ic delay Ar milliseconds
+Specify a time interval to be added to timestamps included in
+requests which require authentication.
+This is used to enable
+(unreliable) server reconfiguration over long delay network paths
+or between machines whose clocks are unsynchronized.
+Actually the
+server does not now require timestamps in authenticated requests,
+so this command may be obsolete.
+.It Ic host Ar hostname
+Set the host to which future queries will be sent.
+.Ar hostname
+may be either a host name or a numeric address.
+.It Ic hostnames Op Cm yes | Cm no
+If
+.Cm yes
+is specified, host names are printed in
+information displays.
+If
+.Cm no
+is specified, numeric
+addresses are printed instead.
+The default is
+.Cm yes ,
+unless
+modified using the command line
+.Fl n
+switch.
+.It Ic keyid Ar keyid
+This command allows the specification of a key number to be
+used to authenticate configuration requests.
+This must correspond
+to a key number the server has been configured to use for this
+purpose.
+.It Ic ntpversion Xo Oo
+.Cm 1 |
+.Cm 2 |
+.Cm 3 |
+.Cm 4
+.Oc
+.Xc
+Sets the NTP version number which
+.Nm
+claims in
+packets.
+Defaults to 3, and note that mode 6 control messages (and
+modes, for that matter) didn't exist in NTP version 1.
+There appear
+to be no servers left which demand version 1.
+With no argument, displays the current NTP version that will be used
+when communicating with servers.
+.It Ic quit
+Exit
+.Nm
+.It Ic passwd
+This command prompts you to type in a password (which will not
+be echoed) which will be used to authenticate configuration
+requests.
+The password must correspond to the key configured for
+use by the NTP server for this purpose if such requests are to be
+successful.
+.It Ic raw
+Causes all output from query commands is printed as received
+from the remote server.
+The only formating/interpretation done on
+the data is to transform nonascii data into a printable (but barely
+understandable) form.
+.It Ic timeout Ar milliseconds
+Specify a timeout period for responses to server queries.
+The
+default is about 5000 milliseconds.
+Note that since
+.Nm
+retries each query once after a timeout, the total waiting time for
+a timeout will be twice the timeout value set.
+.El
- _END_PROG_MAN_DESCRIP;
+ _END_PROG_MDOC_DESCRIP;
+};
projects / thirdparty / ntp.git / commitdiff
