Appendix B. NTP Control Messages
This appendix describes the NTP Control Message format, which provides a mechanism for monitoring and controlling NTP implementations. The control message is an optional feature and need not be implemented in all cases. When implemented, the control message is used only in client/server mode and is not intended for broadcast mode. The control message is formatted as a standard NTP message, with the mode field set to 6 (control message).
The control message provides a simple query/response mechanism for monitoring and controlling NTP implementations. It is intended primarily for use in managing and monitoring the NTP implementation, providing access to the internal variables maintained by the protocol machine. These variables can be examined and, in some cases, modified by external management applications. The control message provides a way to examine the status and performance of the implementation without interfering with normal protocol operations.
B.1. NTP Control Message Format
The NTP Control Message is formatted as follows:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|LI | VN | Mode |R|E|M| OpCode | Sequence |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Status | Association ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Offset | Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
. .
. Data .
. .
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key Identifier (optional) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Message Digest (optional) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Field Descriptions
Leap Indicator (LI): This is a two-bit code warning of an impending leap second as defined in the NTP message format.
Version Number (VN): This is a three-bit integer indicating the NTP version number, currently 3.
Mode: This is a three-bit integer indicating the mode. For control messages, this field is set to 6.
Response Bit (R): Set to 0 for queries, set to 1 for responses.
Error Bit (E): Set to 0 for normal response, set to 1 for error response.
More Bit (M): Set to 1 if more data follows this fragment, set to 0 for the last fragment.
Operation Code (OpCode): This is a five-bit code specifying the operation to be performed:
| Value | Operation |
|---|---|
| 0 | Reserved |
| 1 | Read Status |
| 2 | Read Variables |
| 3 | Write Variables |
| 4 | Read Clock Variables |
| 5 | Write Clock Variables |
| 6 | Set Trap Address |
| 7 | Trap Response |
| 8-31 | Reserved |
Sequence: This is a 16-bit integer used to match requests with responses.
Status: This is a 16-bit code indicating the status of the system, peer or clock.
Association ID: This is a 16-bit integer identifying a particular peer association. A value of 0 indicates the system variables.
Offset: This is a 16-bit integer specifying the offset of the first octet in the data area.
Count: This is a 16-bit integer specifying the number of octets in the data area.
Data: This variable-length field contains the data for the request or response. The format depends on the operation code.
Authenticator (optional): When authentication is implemented, this field contains the Key Identifier and Message Digest as defined in Appendix C.
B.2. Status Words
The status field in the control message header contains a 16-bit code providing information about the system, peer or clock. The format depends on the type of status being reported.
B.2.1. System Status Word
The system status word appears in the status field of the response to a read status command with a zero association identifier. The format is:
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| LI | Source | Count | Code|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Leap Indicator (LI): This is a two-bit code warning of an impending leap second.
Clock Source (Source): This is a four-bit code indicating the current synchronization source:
| Value | Source |
|---|---|
| 0 | unspecified or unknown |
| 1 | atomic clock |
| 2 | VLF radio |
| 3 | HF radio |
| 4 | UHF radio |
| 5 | local net |
| 6 | NTP |
| 7 | UDP/TIME |
| 8 | wristwatch |
| 9 | modem |
System Event Counter (Count): This is a four-bit integer indicating the number of system exception events that have occurred since the last time the system status word was read.
System Event Code (Code): This is a four-bit integer identifying the most recent system exception event:
| Value | Event |
|---|---|
| 0 | unspecified |
| 1 | system restart |
| 2 | system fault |
| 3 | system clock reset |
| 4 | association event |
| 5 | operating mode change |
| 6-15 | reserved |
B.2.2. Peer Status Word
The peer status word appears in the status field of the response to a read status command with a non-zero association identifier. The format is:
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Status | Sel | Count| Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Peer Status (Status): This is a five-bit code indicating the status of the peer:
| Bit | Meaning when set |
|---|---|
| 0 | configured (peer.config) |
| 1 | authentication enabled |
| 2 | authentication okay |
| 3 | reachability okay |
| 4 | reserved |
Peer Selection (Sel): This is a three-bit integer indicating the status of the peer selection process:
| Value | Selection |
|---|---|
| 0 | rejected |
| 1 | passed sanity checks |
| 2 | passed correctness checks |
| 3 | passed candidate checks |
| 4 | passed outlier checks |
| 5 | current synchronization source |
| 6 | backup synchronization source |
| 7 | reserved |
Peer Event Counter (Count): This is a four-bit integer indicating the number of peer exception events.
Peer Event Code (Code): This is a four-bit integer identifying the most recent peer exception event.
B.2.3. Clock Status Word
The clock status word appears in the status field of the response to a read clock variables command. The format is implementation-dependent.
B.2.4. Error Status Word
The error status word appears in the status field of an error response. The format is:
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Error Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Error Code: This is a 16-bit integer identifying the error condition:
| Value | Error |
|---|---|
| 0 | no error |
| 1 | incompatible implementation |
| 2 | unimplemented request |
| 3 | permission denied |
| 4 | invalid message format |
| 5 | invalid message length |
B.3. Commands
The control message commands provide a mechanism for reading and writing the system, peer and clock variables. The following commands are defined:
Read Status: This command returns the status word for the system (association ID = 0) or for a specific peer (association ID != 0).
Read Variables: This command returns the values of one or more variables for the system or for a specific peer. The data field contains a list of variable names separated by commas.
Write Variables: This command sets the values of one or more variables. The data field contains a list of variable=value pairs separated by commas.
Read Clock Variables: This command returns the values of one or more reference clock variables.
Write Clock Variables: This command sets the values of one or more reference clock variables.
Set Trap Address: This command sets the address of a trap receiver. When significant events occur, the implementation sends unsolicited trap response messages to the specified address.
Trap Response: This is an unsolicited message sent to a trap receiver when a significant event occurs.
The control message facility provides a powerful mechanism for monitoring and managing NTP implementations. However, it should be used with care to avoid disrupting normal protocol operations or compromising security.