Commands Reference, Volume 6

xntpdc Command

Purpose

Starts the query/control program for the Network Time Protocol daemon, xntpd.

Syntax

xntpdc [ -i ] [ -l ] [ -n ] [ -p ] [ -s ] [ -c SubCommand ] [ Host ... ]

Description

The xntpdc command queries the xntpd daemon about its current state and requests changes to that state. It runs either in interactive mode or by using command-line arguments. The xntpdc command interface displays extensive state and statistics information. Nearly all the configuration options that can be specified at start-up using the xntpd daemon's configuration file, can also be specified at run-time using the xntpdc command.

If you enter the xntpdc command with one or more request flags, the NTP servers running on each of the hosts specified (or defaults to local host) receive each request. If you do not enter any request flags, the xntpdc command tries to read commands from standard input and run them on the NTP server running on the first host specified or on the local host by default. It prompts for subcommands if standard input is the terminal.

The xntpdc command uses NTP mode 7 packets to communicate with the NTP server and can query any compatible server on the network that permits it.

The xntpdc command makes no attempt to retransmit requests, and will time-out requests if the remote host does not respond within a suitable time.

Specifying a flag other than -i or -n sends the queries to the specified hosts immediately. Otherwise, the xntpdc command attempts to read interactive format commands from standard input.

Flags

-c SubCommand	Specifies an interactive format command. This flag adds SubCommand to the list of commands to run on the specified hosts. You can enter multiple -c flags.
-i	Specifies interactive mode. Standard output displays prompt and standard input reads commands.
-l	(lowercase L) Displays a list of the peers known to the servers. This is the same as the listpeers subcommand.
-n	Displays all host addresses in dotted decimal format (0.0.0.0) rather than the canonical host names.
-p	Displays a list of the peers known to the server and a summary of their state. This is the same as the peers subcommand.
-s	Displays a list of the peers known to the server and a summary of their state but in a format different from the -p flag. This is the same as the dmpeers subcommand.

Parameters

Host ...

Specifies the hosts.

Exit Status

This command returns the following exit values:

0	Successful completion.
>0	An error occurred.

Security

Access Control: You must be part of the system group to run this command.

Auditing Events: N/A

Displays per-peer statistic counters associated with the specified peers.

Examples

To start the query/control program for the Network Time Protocol daemon, enter:
```
xntpdc
```

To display the statistic counters of the peer at address 127.127.1.0 on host 9.3.149.107, enter:

xntpdc -c "pstats 127.127.1.0" 9.3.149.107

Output similar to the following is displayed:

remote host:   LOCAL(0)
local interface:   127.0.0.1
time last received:   49s
time until next send:   15s
reachability change:   818s
packets sent:   13
packets received:   13
bad authentication:   0
bogus origin:   0
duplicate:   0
bad dispersion:   4
bad reference time:   0
candidate order:   1

xntpdc Internal Subcommands

You can run a number of interactive format subcommands entirely within the xntpdc command that do not send NTP mode 7 requests to a server. The following subcommands can only be used while running the xntpdc query program.

Interactive Format Subcommands

Interactive format subcommands consist of a keyword followed by zero to four arguments. You only need to type enough characters of the full keyword to uniquely identify the subcommand. The output of a subcommand goes to standard output, but you can redirect the output of individual subcommands to a file by appending a greater-than sign (>), followed by a file name, to the command line.

? [ SubCommand ]	Displays command usage information. When used without SubCommand, displays a list of all the xntpdc command keywords. When used with SubCommand, displays function and usage information about the command.
help [ SubCommand ]	Same as the ? [ Subcommand ] subcommand.
delay Milliseconds	Specifies the time interval to add to timestamps included in requests that require authentication. This subcommand enables unreliable server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
host HostName	Specifies the host to send queries to. HostName may be either a host name or a numeric address. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
hostnames yes \| no	Specifies whether to display the host name (yes) or the numeric address (no). The default is yes unless the -n flag is used. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
keyid Number	Specifies the server key number to use to authenticate configuration requests. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
passwd	Prompts you to type in the NTP server authentication password to use to authenticate configuration requests.
quit	Exits the xntpdc query program.
timeout Milliseconds	Specifies the time-out period for responses to server queries. The default is 8000 milliseconds. If you enter this subcommand without an argument, it prints the current setting for this subcommand.

Query Subcommands

The xntpdc query subcommands result in sending NTP mode 7 packets containing requests to the server. These subcommands are read-only (they do not modify the server configuration state).

clkbug ClockPeerAddress [ Addr2 ] [ Addr3 ] [ Addr4 ]	Displays debugging information for a reference clock driver. Some clock drivers provide this information that is mostly undecodable without a copy of the driver source in hand.
clockbug ClockPeerAddress [ Addr2 ] [ Addr3 ] [ Addr4 ]	Displays information concerning a peer clock. The values obtained provide information on the setting of fudge factors and other clock performance information.
dmpeers	Displays a list of peers for which the server is maintaining state, along with a summary of that state. Identical to the output of the peers subcommand except for the character in the leftmost column. Characters only are displayed beside peers that were included in the final stage of the clock selection algorithm. The possible character in the leftmost column are: . Indicates that this peer was cast off in the falseticker detection. + Indicates that the peer made it through. * Denotes the peer the server is currently synchronizing with.
iostats	Displays statistics counters maintained in the input-output module.
kerninfo	Displays kernel phase-lock loop operating parameters. This information is available only if the kernel of the hosts being generated has been specially modified for a precision timekeeping function.
listpeers	Displays a brief list of the peers for which the server is maintaining state. These include all configured peer associations as well as those peers whose stratum is such that the server considers them to be possible future synchronization candidates.
loopinfo [ oneline \| multiline ]	Displays the values of selected loop filter variables. The loop filter is the part of NTP that adjusts the local system clock. The `offset` is the last offset given to the loop filter by the packet processing code. The `frequency` is the frequency error of the local clock in parts-per-million (ppm). The `poll adjust` controls the stiffness (resistance to change) of the phase-lock loop and the speed at which it can adapt to oscillator drift. The `watchdog timer` is the number of elapsed seconds since the last sample offset given to the loop filter. The oneline and multiline options specify the format to display this information. The multiline option is the default.
memstats	Displays statistics counters related to memory allocation code.
monlist	Displays traffic counts collected and maintained by the monitor facility.
peers	Displays a list of peers for which the server is maintaining state, along with a summary of that state. Summary information includes: address of the remote peer, reference ID (0.0.0.0 for an unknown reference ID), the stratum of the remote peer (a stratum of 16 indicates the remote peer is unsynchronized), the polling interval (seconds), the reachability register (octal), and the current estimated delay, offset and dispersion of the peer (seconds). The character in the left margin indicates the mode this peer entry is in: + symmetric active. - symmetric passive. = remote server polled in client mode. ^ server is broadcasting to this address. ~ remote peer is sending broadcasts. * marks the peer the server is currently synchronizing to. The contents of the host field may be a host name, an IP address, a reference clock implementation name with its parameter or REFCLK (ImplementationNumber, Parameter). Only IP addresses display when using hostnames no.
pstats PeerAddress [ Addr2 ] [ Addr3 ] [ Addr4 ]	Displays per-peer statistic counters associated with the specified peers.
reslist	Displays the server's restriction list which may help to understand how the restrictions are applied.
sysinfo	Displays a variety of system state variables related to the local server. All except the last four lines are described in the NTP Version 3 specification, RFC 1305. The system flags show various system flags, some of which can be set and cleared by the enable and disable configuration statements. The `stability` is the residual frequency error remaining after applying the system frequency correction. You use it for maintenance and debugging. In most architectures, this value will initially decrease from as high as 500 ppm to a nominal value in the range .01 to 0.1 ppm. If it remains high for some time after starting the daemon, something may be wrong with the local clock, or the value of the kernel variable Tick may be incorrect. The `broadcastdelay` shows the default broadcast delay, as set by the broadcastdelay configuration statement, while the `authdelay` shows the default authentication delay, as set by the authdelay configuration statement.
sysstats	Displays statistics counters maintained in the protocol module.
timerstats	Displays statistics counters maintained in the timer/event queue support code.

Runtime Configuration Requests Subcommands

The server authenticates all requests that cause state changes in the server by using a configured NTP key. The server can also disable this facility by not configuring a key. You must make the key number and the corresponding key known to the xtnpdc command. You can do this by using the keyid and passwd subcommands, which prompts at the terminal for a password to use as the encryption key. The xtnpdc command will also prompt you automatically for both the key number and password the first time you give a subcommand that would result in an authenticated request to the server. Authentication not only verifies that the requester has permission to make such changes, but also protects against transmission errors.

Authenticated requests always include a timestamp in the packet data, as does the computation of the authentication code. The server compares this timestamp to the time at which it receives the packet.

The server rejects the request if they differ by more than 10 seconds. This makes simple replay attacks on the server, by someone able to overhear traffic on your LAN, much more difficult. It also makes it more difficult to request configuration changes to your server from topologically remote hosts. While the reconfiguration facility works well with a server on the local host, and may work adequately between time-synchronized hosts on the same LAN, it works very poorly for more distant hosts. So, if you choose reasonable passwords, take care in the distribution and protection of keys and apply appropriate source address restrictions, the run-time reconfiguration facility should provide an adequate level of security.

The following subcommands all make authenticated requests.

addpeer PeerAddress [ Keyid ] [ Version ] [ prefer ]	Adds a configured peer association operating in symmetric active mode at the specified address. You may delete an existing association with the same peer or simply convert an existing association to conform to the new configuration when using this subcommand. If the Keyid is a nonzero integer, all outgoing packets to the remote server will have an authentication field attached encrypted with this key. To specify no authentication , enter Keyid as 0 or leave blank. The values for Version can be 1, 2 or 3, with 3 as the default. The prefer option indicates a preferred peer used primarily for clock synchronization if possible. The preferred peer also determines the validity of the PPS signal. If the preferred peer is suitable for synchronization, so is the PPS signal.
addserver PeerAddress [ Keyid ] [ Version ] [ prefer ]	Same as the addpeer subcommand, except that the operating mode is client.
addtrap Address [ Port ] [ Interface ]	Sets a trap for asynchronous messages at the specified address and port number for sending messages with the specified local interface address. If you do not specify the port number, the value defaults to 18447. If you do not specify the interface address, the value defaults to the source address of the local interface.
authinfo	Displays information concerning the authentication module, including known keys and counts of encryptions and decryptions performed.
broadcast PeerAddress [ Keyid ] [ Version ]	Same as the addpeer subcommand, except that the operating mode is broadcast. The PeerAddress can be the broadcast address of the local network or a multicast group address assigned to NTP (224.0.1.1).
clrtrap Address [ Port ] [ Interface ]	Clears a trap for asynchronous messages at the specified address and port number for sending messages with the specified local interface address. If you do not specify the port number, the value defaults to 18447. If you do not specify the interface address, the value defaults to the source address of the local interface.
delrestrict Address Mask [ ntpport ]	Deletes the matching entry from the restrict list.
disable Option ...	Disables various server options. Does not affect options not mentioned. The enable subcommand describes the options.
enable Option ...	Enables various server options. Does not affect options not mentioned. You can specify one or more of the following values for Option: auth Causes the server to synchronize with unconfigured peers only if the peer has been correctly authenticated using a trusted key and key identifier. The default for this option is disable (off). bclient Causes the server to listen for a message from a broadcast or multicast server, following which an association is automatically instantiated for that server. The default for this argument is disable (off). monitor Enables the monitoring facility, with default enable (on). pll Enables the server to adjust its local clock, with default enable (on). If not set, the local clock free-runs at its intrinsic time and frequency offset. This option is useful when the local clock is controlled by some other device or protocol and NTP is used only to provide synchronization to other clients. stats Enables statistics facility filegen, with default enable (on).
fudge PeerAddress [ Time1 ] [ Time2 ] [ Stratum ] [ Refid ]	Provides a way to set certain data for a reference clock. Time1 and Time2 are in fixed point seconds and used in some clock drivers as calibration constants. Stratum is a number in the range zero to 15 and used to assign a nonstandard operating stratum to the clock. Refid is an ASCII string in the range one to four characters and used to assign a nonstandard reference identifier to the clock.
monitor yes \| no	Enables or disables the monitoring facility. A monitor no subcommand followed by a monitor yes subcommand is a good way of resetting the packet counts.
readkeys	Purges the current set of authentication keys and obtains a new set by rereading the keys file specified in the xntpd configuration file. This allows you to change encryption keys without restarting the server.
reset Module	Clears the statistics counters in various modules of the server. You can specify one or more of the following values for Module: io, sys, mem, timer, auth, allpeers.
restrict Address Mask Option ...	Adds the values of Option to an existing restrict list entry, or adds a new entry to the list with the specified Option. The mask option defaults to 255.255.255.255, meaning that Address is treated as the address of an individual host. You can specify one or more of the following values for Option: ignore Ignore all packets from hosts that match this entry. Does not respond to queries nor time server polls. limited Specifies that these hosts are subject to client limitation from the same net. Net in this context refers to the IP notion of net (class A, class B, class C, etc.). Only accepts the first client_limit hosts that have shown up at the server and that have been active during the last client_limit_period seconds. Rejects requests from other clients from the same net. Only takes into account time request packets. Private, control, and broadcast packets are not subject to client limitation and therefore do not contribute to client count. The monitoring capability of the xntpd daemon keeps a history of clients. When you use this option, monitoring remains active. The default value for client_limit is 3. The default value for client_limit_period is 3600 seconds. lowpriotrap Declare traps set by matching hosts to low priority status. The server can maintain a limited number of traps (the current limit is 3), assigned on a first come, first served basis, and denies service to later trap requestors. This parameter modifies the assignment algorithm by allowing later requests for normal priority traps to override low priority traps. nomodify Ignore all NTP mode 6 and 7 packets that attempt to modify the state of the server (run time reconfiguration). Permits queries that return information. nopeer Provide stateless time service to polling hosts, but not to allocate peer memory resources to these hosts. noquery SIgnore all NTP mode 6 and 7 packets (information queries and configuration requests) from the source. Does not affect time service. noserve Ignore NTP packets whose mode is not 6 or 7. This denies time service, but permits queries. notrap Decline to provide mode 6 control message trap service to matching hosts. The trap service is a subsystem of the mode 6 control message protocol intended for use by remote event logging programs. notrust STreat these hosts normally in other respects, but never use them as synchronization sources. ntpport Match the restriction entry only if the source port in the packet is the standard NTP UDP port (123).
setprecision Precision	Sets the precision that the server advertises. Precision should be a negative integer in the range -4 through -20.
traps	Displays the traps set in the server.
trustkey Keyid ...	Adds one or more keys to the trusted key list. When you enable authentication, authenticates peers with trusted time using a trusted key.
unconfig PeerAddress [ Addr2 ] [ Addr3 ] [ Addr4 ]	Removes the configured bit from the specified peers. In many cases deletes the peer association. When appropriate, however, the association may persist in an unconfigured mode if the remote peer is willing to continue on in this fashion.
unrestrict Address Mask Option ...	Removes the specified options from the restrict list entry indicated by Address and Mask. The restrict subcommand describes the values for Option.
untrustkey Keyid ...	Removes one or more keys from the trusted key list.

Files

/usr/sbin/xntpdc

Contains the xntpdc command.

Related Information

The ntpq, ntpdate, and ntptrace commands.

The xntpd daemon.