ntpdc Command for NTPv4

Purpose

Starts the query or control program for the Network Time Protocol (NTP) daemon.

Syntax

ntpdc [ -46dilnps ] [ -c command ] [ host ] [ ... ]

Description

The ntpdc command is used to query the ntpd daemon about its current state and to request changes in the current state. The program is run either in the interactive mode or controlled by using command-line arguments. Extensive state and statistics information is available through the ntpdc command interface. All the configuration options that are specified during startup by using the configuration file of the ntpd command file can be specified at runtime by using the ntpdc command.

If one or more request options are included when the ntpdc command is run, each request is sent to the NTP servers that run on each of the hosts that are specified. If no request options are given, the ntpdc command attempts to read commands from the standard input and runs those commands on the NTP server that runs on the first host that is specified. The ntpdc command sends the requests to the NTP server that runs on the local host when no other host is specified. The ntpdc command prompts for commands if the standard input is a terminal device.

The ntpdc command can be used to query any compatible server on the network, as the ntpdc command uses NTP mode 7 packets to communicate with the NTP server. Since NTP is a User Datagram Protocol (UDP) protocol, this mode of communication is unreliable over large distances in terms of network topology. The ntpdc command does not retransmit requests and times out the requests if the remote host does not respond within a suitable timeout time.

The operation of the ntpdc command is specific to the implementation of the ntpd daemon. The ntpdc command is expected to work with the ntpd daemon or with the previous versions of the ntpd daemon. Requests from a remote ntpdc program that affect the state of the local server must be authenticated. To authenticate the requests from a remote ntpdc program, both the remote program and local server must share a common key and key identifier.

Flags

A command-line option other than the -i or -n parameter causes the specified query or queries to be sent immediately to the indicated one or more than one host. Otherwise, the ntpdc command attempts to read interactive format commands from the standard input.

ntpdc Internal Commands

Interactive commands

Interactive commands consist of a keyword followed by zero to four arguments. Type enough characters from the entire keyword to identify the command uniquely. The output of a command is normally sent to the standard output. However, the output of the individual commands can be sent to a file by appending an opening angle bracket (<), followed by a file name, to the command.

Various interactive commands are run within the ntpdc program itself and does not send the NTP mode 7 requests to a server. The following list describes the interactive commands:

Table 2. Interactive commands

Item	Description
? [ command_keyword ] or help [ command_keyword ]	A question mark (?) prints a list of all the command keywords that are known to the ntpdc command. A question mark (?) followed by a command keyword prints the function and use of the command.
delay milliseconds	Specifies a time interval to be added to timestamps included in requests that require authentication. This option is used to enable (unreliable) server reconfiguration over long-delay network paths or between machines with clocks that are not synchronized. Note: The delay interactive command is obsolete because currently the server does not need timestamps for authenticated requests.
host hostname	Sets the host to which future queries are sent. The hostname specified is either a hostname or a numeric address.
hostnames [ yes | no ]	Lists the hostnames or the numeric addresses of the hosts. The hostname command can take the following values: yes: Prints the hostnames. This option is the default value unless it is modified by using the -n option. no: Prints the numeric addresses of the hosts.
keyid keyid	Allows the specification of a key number to be used to authenticate configuration requests from the ntpdc command to one or more hosts. This option must correspond to a key number that the host or server is configured to use for authentication purposes. If authentication is not enabled for one or more hosts, the value of the keyid variable must be specified as 0, otherwise the keyid value of the next subsequent addpeer, addserver, or broadcast command is used. The server authentication options are trustedkey and requestkey.
quit	Exits the ntpdc command.
passwd	Prompts to type in a password that is used to authenticate the configuration requests. The password must correspond to the key that the NTP server uses for authentication, so that the configuration requests are authenticated successfully.
timeout milliseconds	Specifies a timeout period for responses to the server queries. The default timeout period is 8000 milliseconds. Note: The total waiting time for a timeout period is twice the timeout value that you set, as the ntpdc command retries each server query once after a timeout.

Control message commands

The query commands result in NTP mode 7 packets that contain requests for information to be sent to the server. These commands are read-only commands that do not modify the server configuration state.

Table 3. Control message commands

Item	Description
listpeers	Obtains and prints the list of the peers for which the server is maintaining the status. The list must include all configured peer associations and the peers that the server considers as possible synchronization candidates.
peers	Obtains a list of peers for which the server maintains the status, along with a summary of the status. The summary information includes the following data: Address of the remote peer. Address of the local interface. If a local address is not determined, a value of 0.0.0.0 is displayed. Stratum of the remote peer. A stratum value of 16 indicates that the remote peer is not synchronized. Polling interval, in seconds. Reachability register, in octal. Current estimated delay, offset, and dispersion of the peer, all in seconds. The character in the left margin of the list that is displayed indicates the mode that the peer entry is operating in. The different characters that are displayed are described in the following list: Plus sign (+): This character indicates that the peer is symmetric active. Hyphen (-): This character indicates that the peer is symmetric passive. Equal sign (=): This character indicates that the remote server is being polled in client mode. Caret (^): This character indicates that the server is broadcasting to this address. Tilde (~): This character indicates that the remote peer is sending broadcasts. Asterisk (*): This character marks the peer that the server is synchronizing to. The following list describes the contents of the host field: A hostname. An IP address. The implementation name of the reference clock with its parameter. The REFCLK, which is the implementation number of the reference clock with its parameter. If the hostnames no command is specified, only the IP addresses of the hosts are displayed.
dmpeers	Obtains a peer summary list that is little different from the list that is obtained by using the peers command. The output of the dmpeers command is identical to the output of the peers command, except for the character in the leftmost column in the output of the peers command. In the dmpeers command output, the characters appear next to the peers that were included in the final stage of the clock selection algorithm. The different characters that are displayed are described in the following list: Period (.): This character indicates that this peer was cast off in the falseticker detection. Plus sign (+): This character indicates that the peer made it through. Asterisk (*): This character denotes the peer that the server is synchronizing to.
showpeer peer_address [...]	Shows a detailed display of the current peer variables for one or more peers. Most of these values are described in the NTP Version 2 specification.
pstats peer_address [...]	Displays per-peer statistic counters that are associated with one or more specified peers.
clockstat clock_peer_address [...]	Obtains and prints information that concerns a peer clock. The values obtained by using this option provide information regarding the setting of fudge factors and the performance of the peer clock.
kerninfo	Obtains and prints the operating parameters of the kernel phase-lock loop. This information is available only if the kernel is specially modified for a precision timekeeping function.
loopinfo [ oneline | multiline ]	Prints the value of the selected loop filter variables. The following information is displayed by the loopinfo command: Loop filter: The loop filter is the part of NTP that deals with adjusting the local system clock. Offset: The offset is the last offset given to the loop filter by the packet processing code. Frequency: The frequency is the frequency error of the local clock in parts-per-million (ppm). time_cons: The time_cons value controls the stiffness of the phase-lock loop and thus the speed at which it can adapt to oscillator drift. Watchdog timer: The watchdog timer value is the number of seconds that elapsed since the last sample offset was given to the loop filter. The oneline and multiline options of the loopinfo command specifies the format in which the information must be printed. The default format is multiline.
sysinfo	Prints various system state variables. The system state variable is the state that is related to the local server. All except the last four lines are described in the NTP Version 3 specification, RFC-1305. The system flags field in the display shows various system flags, some of which can be set and cleared by the enable and disable configuration commands. The following system flags are displayed: auth bclient monitor pll pps stats For more information about the system flags, see the Miscellaneous Options section of the NTP Configuration File User’s Manual. The kernel_pll and kernel_pps flags are read only flags. The kernel_pll and kernel_pps flags indicate the synchronization status when the modifications of the precision time kernel are in use. The kernel_pll flag indicates that the local clock is being disciplined by the kernel, while the kernel_pps flag indicates that the kernel discipline is provided by the pulse per second (PPS) signal. The stability field is the residual frequency error that remains after the system frequency correction is applied and is intended for maintenance and debugging. In most architectures, this value initially decreases from as high as 500 ppm to a nominal value in the range 0.01 to 0.1 ppm. If the stability field value remains high for sometime after the daemon starts, the local clock might be faulty, or the value of the kernel variable tick might be incorrect. The broadcastdelay field shows the default broadcast delay, as set by the broadcastdelay configuration command. The authdelay field shows the default authentication delay, as set by the authdelay configuration command.
sysstats	Prints statistics counters that are maintained in the protocol module.
memstats	Prints statistics counters that are related to memory allocation code.
iostats	Prints statistics counters that are maintained in the input or output module.
timerstats	Prints statistics counters that are maintained in the timer or support code of the event queue.
reslist	Obtains and prints the restriction list of the server. This list is printed in a sorted order and helps to understand how the restrictions are applied.
ifstats	Lists the interface statistics for interfaces used by the ntpd command for network communication.
ifreload	Forces the scan of the current system interfaces and displays the output of interface statistics for interfaces that might possibly change. Marks the unchanged interfaces with a period (.), added interfaces with a plus sign (+), and deleted interfaces with a hyphen (-).
monlist [ version ]	Obtains and prints the traffic counts that are collected and maintained by the monitor facility. Normally, the version number is not required. A maximum of 600 entries are displayed by the monlist command.
clkbug clock_peer_address [...]	Obtains debugging information for a reference clock driver. This information is provided only by some clock drivers and cannot be decoded without a copy of the driver source.

Runtime configuration requests

All the requests that cause state changes on the server are authenticated by the server by using a configured NTP key. The authentication can be disabled by the server by not configuring an NTP key. The key number and the corresponding key must be made known to the ntpdc command by using the keyid and passwd commands. The passwd command prompts for a password at the terminal to be used as the encryption key. When you run a command for the first time that results in an authentication request to the server, you are also prompted automatically for both the key number and password. Authentication not only provides verification that the requester has permission to make such changes but also gives an extra degree of protection against transmission errors.

Authenticated requests always include a timestamp in the packet data, which is included in the computation of the authentication code. This timestamp is compared by the server to its received timestamp. If they differ by more than a small amount, the request is rejected for the following benefits:

• It makes simple replay attacks on the server, by someone who might be able to overhear traffic on your LAN, much more difficult.
• It 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 might work adequately between time-synchronized hosts on the same LAN, it works poorly for more distant hosts. If reasonable passwords are chosen, the distribution and protection of keys is done carefully, and appropriate source address restrictions are applied, then the runtime reconfiguration facility provides an adequate level of security.

The following commands run the authenticated requests:

Table 4. Runtime configuration requests

Item	Description
addpeer peer_address [ keyid ] [ version ] [ minpoll# | prefer | iburst | burst | minpoll N | maxpoll N [...]] addpeer peer_address [ prefer | iburst | burst | minpoll N | maxpoll N | keyid N | version N [...]]	Adds a configured peer association at the specified address and operates in symmetric active mode. An existing association with the same peer might be deleted when this command is run, or it might be converted to conform to the new configuration. If the value of the keyid parameter is nonzero, all the outgoing packets to the remote server have an authentication field attached that is encrypted with the key that is specified by the keyid parameter. If the value of the keyid parameter is 0 or is not specified, no authentication is done. If the key number of the ntpdc command is not set by using the keyid command, it is set to the value specified by the keyid parameter. The value of the version parameter can be 1 through 4. The default version is 3. The remaining options are either a numeric value for minpoll or one of the following options: prefer iburst burst minpoll N keyid N version N maxpoll N where N is a numeric value, and have the action as specified in the peer configuration file commands of the ntpd command. Each flag (or its absence) replaces the previous setting. The prefer keyword indicates a preferred peer and is 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, then the PPS signal is also suitable for synchronization.
addserver peer_address [ keyid ] [ version ] [ minpoll# | prefer | iburst | burst | minpoll N | maxpoll N [...]] addserver peer_address [ prefer | iburst | burst | minpoll N | maxpoll N | keyid N | version N [...]]	This command is identical to the addpeer command, except that the operating mode is client.
broadcast peer_address [ keyid ] [ version ] [ prefer ]	This command is identical to the addpeer command, except that the operating mode is broadcast. In this case, a valid nonzero key identifier and a key are required. The peer_address parameter is the broadcast address of the local network or a multicast group address that is assigned to NTP. If the peer_address parameter is a multicast address, a multicast-capable kernel is required.
unconfig peer_address [...]	This command causes the configured bit to be removed from one or more specified peers. Often, this action causes the peer association to be deleted. However, the peer association might continue to exist in an unconfigured mode if the remote peer is willing to continue in this format.
fudge peer_address [ time1 ] [ time2 ] [ stratum ] [ refid ]	This command provides a way to set certain data for a reference clock.
enable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats] disable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]	These commands operate in the same way as the enable and disable configuration file commands of the ntpd command.
restrict address mask flag [ flag ]	This command operates in the same way as the restricted configuration file commands of the ntpd command.
unrestrict address mask flag [ flag ]	Removes the restriction of the matching entry from the restrict list.
delrestrict address mask [ ntpport ]	Deletes the matching entry from the restrict list.
readkeys	Causes the current set of authentication keys to be purged and a new set of authentication keys to be obtained by reading the keys file again. The key file is specified in the ntpd configuration file. This command allows encryption keys to be changed without restarting the server.
trustedkey keyid [...] untrustedkey keyid [...]	These commands operate in the same way as the trustedkey and untrustedkey configuration file commands of the ntpd command.
authinfo	Returns information that concerns the authentication module, including known keys and counts of encryption and decryption that are done.
traps	Displays the traps set in the server.
addtrap [ address [ port ] [ interface ]	Sets a trap for asynchronous messages.
clrtrap [ address [ port ] [ interface]	Clears a trap for asynchronous messages.
reset	Clears the statistics counters in various modules of the server.

Parameters

Exit Status

The ntpdc command returns the following exit values:

Security

Access Control

You must be a part of the system group to run this command.

Auditing Events

N/A

RBAC users

Attention RBAC users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations that are associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

An output similar to the following output is displayed:

     remote              local        st   poll reach  delay     offset   disp

======================================================================================

ausgsa.austin.ibm.com 9.124.101.190    2   64    1    0.29128 -0.013381 2.81735

Files

/usr/sbin/ntp4/ntpdc4

Contains the ntpdc command for NTPv4.

/usr/sbin/ntpdc-->/usr/sbin/ntp4/ntpdc4

The default symbolic link to the NTP version 4 binary file from the /usr/sbin directory.