RFC 9327 | NTP Control Messages | November 2022 |
Haberman | Historic | [Page] |
This document describes the structure of the control messages that were historically used with the Network Time Protocol (NTP) before the advent of more modern control and management approaches. These control messages have been used to monitor and control the NTP application running on any IP network attached computer. The information in this document was originally described in Appendix B of RFC 1305. The goal of this document is to provide an updated description of the control messages described in RFC 1305 in order to conform with the updated NTP specification documented in RFC 5905.¶
The publication of this document is not meant to encourage the development and deployment of these control messages. This document is only providing a current reference for these control messages given the current status of RFC 1305.¶
This document is not an Internet Standards Track specification; it is published for the historical record.¶
This document defines a Historic Document for the Internet community. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are candidates for any level of Internet Standard; see Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9327.¶
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.¶
[RFC1305] describes a set of control messages for use within the Network Time Protocol (NTP) when a comprehensive network management solution was not available. The definitions of these control messages were not promulgated to [RFC5905] when NTP version 4 was documented. These messages were intended for use only in systems where no other management facilities were available or appropriate, such as in dedicated-function bus peripherals. Support for these messages is not required in order to conform to [RFC5905]. The control messages are described here as a current reference for use with an implementation of NTP from RFC 5905.¶
The publication of this document is not meant to encourage the development and deployment of these control messages. This document is only providing a current reference for these control messages given the current status of RFC 1305.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The NTP mode 6 control messages are used by NTP management programs (e.g., ntpq) when a more robust network management facility (e.g., SNMP) is not available. These control messages provide rudimentary control and monitoring functions to manage a running instance of an NTP server. These commands are not designed to be used for communication between instances of running NTP servers.¶
The NTP control message has the value 6 specified in the mode field of the first octet of the NTP header and is formatted as shown in Figure 1. The format of the data field is specific to each command or response; however, in most cases, the format is designed to be constructed and viewed by humans and so is coded in free-form ASCII. This facilitates the specification and implementation of simple management tools in the absence of fully evolved network-management facilities. As in ordinary NTP messages, the authenticator field follows the data field. If the authenticator is used, the data field is zero-padded to a 32-bit boundary, but the padding bits are not considered part of the data field and are not included in the field count.¶
IP hosts are not required to reassemble datagrams over a certain size (576 octets for IPv4 [RFC0791] and 1280 octets for IPv6 [RFC8200]); however, some commands or responses may involve more data than will fit into a single datagram. Accordingly, a simple reassembly feature is included in which each octet of the message data is numbered starting with zero. As each fragment is transmitted, the number of its first octet is inserted in the offset field and the number of octets is inserted in the count field. The more-data (M) bit is set in all fragments except the last.¶
Most control functions involve sending a command and receiving a response, perhaps involving several fragments. The sender chooses a distinct, nonzero sequence number and sets the status field, "R" bit, and "E" bit to zero. The responder interprets the opcode and additional information in the data field, updates the status field, sets the "R" bit to one and returns the three 32-bit words of the header along with additional information in the data field. In the case of invalid message format or contents, the responder inserts a code in the status field, sets the "R" and "E" bits to one and, optionally, inserts a diagnostic message in the data field.¶
Some commands read or write system variables (e.g., s.offset) and peer variables (e.g., p.stratum) for an association identified in the command. Others read or write variables associated with a radio clock or other device directly connected to a source of primary synchronization information. To identify which type of variable and association, the Association ID is used. System variables are indicated by the identifier zero. As each association is mobilized a unique, nonzero identifier is created for it. These identifiers are used in a cyclic fashion, so that the chance of using an old identifier that matches a newly created association is remote. A management entity can request a list of current identifiers and subsequently use them to read and write variables for each association. An attempt to use an expired identifier results in an exception response, following which the list can be requested again.¶
Some exception events, such as when a peer becomes reachable or unreachable, occur spontaneously and are not necessarily associated with a command. An implementation may elect to save the event information for later retrieval, to send an asynchronous response (called a trap), or both. In case of a trap, the IP address and port number are determined by a previous command and the sequence field is set as described below. Current status and summary information for the latest exception event is returned in all normal responses. Bits in the status field indicate whether an exception has occurred since the last response and whether more than one exception has occurred.¶
Commands need not necessarily be sent by an NTP peer, so ordinary access-control procedures may not apply; however, the optional mask/match mechanism suggested in Section 6 provides the capability to control access by mode number, so this could be used to limit access for control messages (mode 6) to selected address ranges.¶
The original development of the NTP daemon included a Remote Facility for monitoring and configuration. This facility used mode 7 commands to communicate with the NTP daemon. This document illustrates the mode 7 packet format only. The commands embedded in the mode 7 messages are implementation specific and not standardized in any way. The mode 7 message format is described in Appendix A.¶
The format of the NTP Control Message header, which immediately follows the UDP header, is shown in Figure 1. Following the figure is a description of its header fields.¶
Code | Meaning |
---|---|
0 | reserved |
1 | read status command/response |
2 | read variables command/response |
3 | write variables command/response |
4 | read clock variables command/response |
5 | write clock variables command/response |
6 | set trap address/port command/response |
7 | trap response |
8 | runtime configuration command/response |
9 | export configuration to file command/response |
10 | retrieve remote address stats command/response |
11 | retrieve ordered list command/response |
12 | request client-specific nonce command/response |
13-30 | reserved |
31 | unset trap address/port command/response |
Status words indicate the present status of the system, associations, and clock. They are designed to be interpreted by network-monitoring programs and are in one of four 16-bit formats shown in Figure 2 and described in this section. System and peer status words are associated with responses for all commands except the read clock variables, write clock variables, and set trap address/port commands. The association identifier zero specifies the system status word, while a nonzero identifier specifies a particular peer association. The status word returned in response to read clock variables and write clock variables commands indicates the state of the clock hardware and decoding software. A special error status word is used to report malformed command fields or invalid values.¶
The system status word appears in the status field of the response to a read status or read variables command with a zero association identifier. The format of the system status word is as follows:¶
LI | Meaning |
---|---|
00 | no warning |
01 | insert second after 23:59:59 of the current day |
10 | delete second 23:59:59 of the current day |
11 | unsynchronized |
Code | Meaning |
---|---|
0 | unspecified or unknown |
1 | Calibrated atomic clock (e.g., PPS, HP 5061) |
2 | VLF (band 4) or LF (band 5) radio (e.g., OMEGA,, WWVB) |
3 | HF (band 7) radio (e.g., CHU, MSF, WWV/H) |
4 | UHF (band 9) satellite (e.g., GOES, GPS) |
5 | local net (e.g., DCN, TSP, DTS) |
6 | UDP/NTP |
7 | UDP/TIME |
8 | eyeball-and-wristwatch |
9 | telephone modem (e.g., NIST) |
10-63 | reserved |
Code | Meaning |
---|---|
0 | unspecified |
1 | frequency correction (drift) file not available |
2 | frequency correction started (frequency stepped) |
3 | spike detected and ignored, starting stepout timer |
4 | frequency training started |
5 | clock synchronized |
6 | system restart |
7 | panic stop (required step greater than panic threshold) |
8 | no system peer |
9 | leap second insertion/deletion armed for the current month |
10 | leap second disarmed |
11 | leap second inserted or deleted |
12 | clock stepped (stepout timer expired) |
13 | kernel loop discipline status changed |
14 | leapseconds table loaded from file |
15 | leapseconds table outdated, updated file needed |
A peer status word is returned in the status field of a response to a read status, read variables, or write variables command and appears in the list of Association IDs and status words returned by a read status command with a zero Association ID. The format of a peer status word is as follows:¶
Peer Status bit | Meaning |
---|---|
0 | configured (peer.config) |
1 | authentication enabled (peer.authenable) |
2 | authentication okay (peer.authentic) |
3 | reachability okay (peer.reach != 0) |
4 | broadcast association |
Sel | Meaning |
---|---|
0 | rejected |
1 | discarded by intersection algorithm |
2 | discarded by table overflow (not currently used) |
3 | discarded by the cluster algorithm |
4 | included by the combine algorithm |
5 | backup source (with more than sys.maxclock survivors) |
6 | system peer (synchronization source) |
7 | PPS (pulse per second) peer |
Peer Event Code | Meaning |
---|---|
0 | unspecified |
1 | association mobilized |
2 | association demobilized |
3 | peer unreachable (peer.reach was nonzero now zero) |
4 | peer reachable (peer.reach was zero now nonzero) |
5 | association restarted or timed out |
6 | no reply (only used with one-shot clock set command) |
7 | peer rate limit exceeded (kiss code RATE received) |
8 | access denied (kiss code DENY received) |
9 | leap second insertion/deletion at month's end armed by peer vote |
10 | became system peer (sys.peer) |
11 | reference clock event (see clock status word) |
12 | authentication failed |
13 | popcorn spike suppressed by peer clock filter register |
14 | entering interleaved mode |
15 | recovered from interleave error |
There are two ways a reference clock can be attached to an NTP service host: as a dedicated device managed by the operating system and as a synthetic peer managed by NTP. As in the read status command, the Association ID is used to identify the correct variable for each clock: zero for the system clock and nonzero for a peer clock. Only one system clock is supported by the protocol, although many peer clocks can be supported. A system or peer clock status word appears in the status field of the response to a read clock variables or write clock variables command. This word can be considered to be an extension of the system status word or the peer status word as appropriate. The format of the clock status word is as follows:¶
Clock Status | Meaning |
---|---|
0 | clock operating within nominals |
1 | reply timeout |
2 | bad reply format |
3 | hardware or software fault |
4 | propagation failure |
5 | bad date format or value |
6 | bad time format or value |
7-15 | reserved |
An error status word is returned in the status field of an error response as the result of invalid message format or contents. Its presence is indicated when the E (error) bit is set along with the response (R) bit in the response. It consists of an 8-bit integer coded as follows:¶
Error Status | Meaning |
---|---|
0 | unspecified |
1 | authentication failure |
2 | invalid message length or format |
3 | invalid opcode |
4 | unknown Association ID |
5 | unknown variable name |
6 | invalid variable value |
7 | administratively prohibited |
8-255 | reserved |
Commands consist of the header and optional data field shown in Figure 1. When present, the data field contains a list of identifiers or assignments in the form <<identifier>>[=<<value>>],<<identifier>>[=<<value>>],... where <<identifier>> is the ASCII name of a system or peer variable such as the ones specified in RFC 5905 and <<value>> is expressed as a decimal, hexadecimal, or string constant in the syntax of the C programming language. Where no ambiguity exists, the "sys." or "peer." prefixes can be suppressed. Space characters (ASCII nonprinting format effectors) can be added to improve readability for simple monitoring programs that do not reformat the data field. Representations of note are as follows:¶
Implementations may define variables other than those described in RFC 5905; called "extramural variables", these are distinguished by the inclusion of some character type other than alphanumeric or "." in the name. For those commands that return a list of assignments in the response data field, if the command data field is empty, it is expected that all available variables defined in RFC 5905 will be included in the response. For the read commands, if the command data field is nonempty, an implementation may choose to process this field to individually select which variables are to be returned.¶
Commands are interpreted as follows:¶
This document has no IANA actions.¶
A number of security vulnerabilities have been identified with these control messages.¶
NTP's control query interface allows reading and writing of system, peer, and clock variables remotely from arbitrary IP addresses using commands mentioned in Section 4. Overwriting these variables, but not reading them, requires authentication by default. However, this document argues that an NTP host must authenticate all control queries and not just ones that overwrite these variables. Alternatively, the host can use an access control list to explicitly list IP addresses that are allowed to control query the clients. These access controls are required for the following reasons:¶
NTP best practices recommend configuring NTP with the no-query parameter. The no-query parameter blocks access to all remote control queries. However, sometimes the hosts do not want to block all queries and want to give access for certain control queries remotely. This could be for the purpose of remote management and configuration of the hosts in certain scenarios. Such hosts tend to use firewalls or other middleboxes to blacklist certain queries within the network.¶
Significantly fewer hosts respond to mode 7 monlist queries as compared to other control queries because it is a well-known and exploited control query. These queries are likely blocked using blacklists on firewalls and middleboxes rather than the no-query option on NTP hosts. The remaining control queries that can be exploited likely remain out of the blacklist because they are undocumented in the current NTP specification [RFC5905].¶
This document describes all of the mode 6 control queries allowed by NTP and can help administrators make informed decisions on security measures to protect NTP devices from harmful queries and likely make those systems less vulnerable. The use of the legacy mode 6 interface is NOT RECOMMENDED. Regardless of which mode 6 commands an administrator may elect to allow, remote access to this facility needs to be protected from unauthorized access (e.g., strict Access Control Lists (ACLs)). Additionally, the legacy interface for mode 6 commands SHOULD NOT be utilized in new deployments or implementation of NTP.¶
The format of the NTP Remote Facility Message header, which immediately follows the UDP header, is shown in Figure 3. A description of its fields follows Figure 3. Bit positions marked as zero are reserved and should always be transmitted as zero.¶
Set to 0 for a request. For a response, this field contains an error code relating to the request. If the Error is nonzero, the operation requested wasn't performed.¶
Tim Plunkett created the original version of this document. Aanchal Malhotra provided the initial version of the Security Considerations section.¶
Karen O'Donoghue, David Hart, Harlan Stenn, and Philip Chimento deserve credit for portions of this document due to their earlier efforts to document these commands.¶
Miroshav Lichvar, Ulrich Windl, Dieter Sibold, J Ignacio Alvarez-Hamelin, and Alex Campbell provided valuable comments on various draft versions of this document.¶
Dr. David Mills specified the vast majority of the mode 6 commands during the development of [RFC1305] and deserves the credit for their existence and use.¶