7. Data Structures
The NTP state machines are defined in the following sections. State variables are separated into classes according to their function in packet headers, peer and poll processes, the system process, and the clock discipline process. Packet variables represent the NTP header values in transmitted and received packets. Peer and poll variables represent the contents of the association for each server separately. System variables represent the state of the server as seen by its dependent clients. Clock discipline variables represent the internal workings of the clock discipline algorithm. An example is described in Appendix A.
7.1. Structure Conventions
In order to distinguish between different variables of the same name but used in different processes, the naming convention summarized in Figure 5 is adopted. A receive packet variable v is a member of the packet structure r with fully qualified name r.v. In a similar manner, x.v is a transmit packet variable, p.v is a peer variable, s.v is a system variable, and c.v is a clock discipline variable. There is a set of peer variables for each association; there is only one set of system and clock variables.
| Name | Description |
|---|---|
| r. | receive packet header variable |
| x. | transmit packet header variable |
| p. | peer/poll variable |
| s. | system variable |
| c. | clock discipline variable |
Figure 5: Prefix Conventions
7.2. Global Parameters
In addition to the variable classes, a number of global parameters are defined in this document, including those shown with values in Figure 6.
| Name | Value | Description |
|---|---|---|
| PORT | 123 | NTP port number |
| VERSION | 4 | NTP version number |
| TOLERANCE | 15e-6 | frequency tolerance PHI (s/s) |
| MINPOLL | 4 | minimum poll exponent (16 s) |
| MAXPOLL | 17 | maximum poll exponent (36 h) |
| MAXDISP | 16 | maximum dispersion (16 s) |
| MINDISP | .005 | minimum dispersion increment (s) |
| MAXDIST | 1 | distance threshold (1 s) |
| MAXSTRAT | 16 | maximum stratum number |
Figure 6: Global Parameters
While these are the only global parameters needed for interoperability, a larger collection is necessary in any implementation. Appendix A.1.1 contains those used by the skeleton for the mitigation algorithms, clock discipline algorithm, and related implementation-dependent functions.
7.3. Packet Header Variables
The most important state variables from an external point of view are the packet header variables described in Figure 7 and below. The NTP packet header consists of an integral number of 32-bit (4 octet) words in network byte order. The packet format consists of three components: the header itself, one or more optional extension fields, and an optional message authentication code (MAC).
| Name | Formula | Description |
|---|---|---|
| leap | leap | leap indicator (LI) |
| version | version | version number (VN) |
| mode | mode | mode |
| stratum | stratum | stratum |
| poll | poll | poll exponent |
| precision | rho | precision exponent |
| rootdelay | delta_r | root delay |
| rootdisp | epsilon_r | root dispersion |
| refid | refid | reference ID |
| reftime | reftime | reference timestamp |
| org | T1 | origin timestamp |
| rec | T2 | receive timestamp |
| xmt | T3 | transmit timestamp |
| dst | T4 | destination timestamp |
| keyid | keyid | key ID |
| dgst | dgst | message digest |
Figure 7: Packet Header Variables
The NTP packet is a UDP datagram [RFC0768]. The NTP packet header shown in Figure 8 has 12 words followed by optional extension fields and finally an optional message authentication code (MAC).
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 | Stratum | Poll | Precision |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Root Delay |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Root Dispersion |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reference ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+ Reference Timestamp (64) +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+ Origin Timestamp (64) +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+ Receive Timestamp (64) +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+ Transmit Timestamp (64) +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
. Extension Field 1 (variable) .
. .
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| dgst (128) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 8: Packet Header Format
Field Interpretations
LI (Leap Indicator, leap): 2-bit integer warning of an impending leap second.
| Value | Meaning |
|---|---|
| 0 | no warning |
| 1 | last minute of the day has 61 seconds |
| 2 | last minute of the day has 59 seconds |
| 3 | unknown (clock unsynchronized) |
Figure 9: Leap Indicator
VN (Version Number, version): 3-bit integer representing the NTP version number, currently 4.
Mode (mode): 3-bit integer representing the mode.
| Value | Meaning |
|---|---|
| 0 | reserved |
| 1 | symmetric active |
| 2 | symmetric passive |
| 3 | client |
| 4 | server |
| 5 | broadcast |
| 6 | NTP control message |
| 7 | reserved for private use |
Figure 10: Association Modes
Stratum (stratum): 8-bit integer representing the stratum.
| Value | Meaning |
|---|---|
| 0 | unspecified or invalid |
| 1 | primary server (e.g., equipped with a GPS receiver) |
| 2-15 | secondary server (via NTP) |
| 16 | unsynchronized |
| 17-255 | reserved |
Figure 11: Packet Stratum
Poll: 8-bit signed integer representing the maximum interval between successive messages, in log2 seconds.
Precision: 8-bit signed integer representing the precision of the system clock, in log2 seconds.
Root Delay (rootdelay): Total round-trip delay to the reference clock, in NTP short format.
Root Dispersion (rootdisp): Total dispersion to the reference clock, in NTP short format.
Reference ID (refid): 32-bit code identifying the particular server or reference clock.
Reference Timestamp (reftime): Time when the system clock was last set or corrected, in NTP timestamp format.
Origin Timestamp (org, T1): Time at the client when the request departed for the server, in NTP timestamp format.
Receive Timestamp (rec, T2): Time at the server when the request arrived from the client, in NTP timestamp format.
Transmit Timestamp (xmt, T3): Time at the server when the response left for the client, in NTP timestamp format.
Destination Timestamp (dst, T4): Time at the client when the reply arrived from the server, in NTP timestamp format.
7.4. The Kiss-o'-Death Packet
If the Stratum field is 0, which implies unspecified or invalid, the Reference Identifier field can be used to convey messages useful for status reporting and access control. These are called Kiss-o'-Death (KoD) packets and the ASCII messages they convey are called kiss codes.
Recipients of kiss codes MUST inspect them and, in the following cases, take these actions:
a. For kiss codes DENY and RSTR, the client MUST demobilize any associations to that server and stop sending packets to that server;
b. For kiss code RATE, the client MUST immediately reduce its polling interval to that server and continue to reduce it each time it receives a RATE kiss code.
c. Kiss codes beginning with the ASCII character "X" are for unregistered experimentation and development and MUST be ignored if not recognized.
d. Other than the above conditions, KoD packets have no protocol significance and are discarded after inspection.
7.5. NTP Extension Field Format
In NTPv4, one or more extension fields can be inserted after the header and before the MAC. An extension field contains a request or response message in the format shown in Figure 14.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Field Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. Value .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Padding (as needed) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 14: Extension Field Format
All extension fields are zero-padded to a word (four octets) boundary. The Length field is a 16-bit unsigned integer that indicates the length of the entire extension field in octets, including the Padding field.