idnits 2.17.1 draft-ietf-ntp-mode-6-cmds-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 28, 2020) is 1305 days in the past. Is this intentional? Checking references for intended status: Historic ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 1305 (Obsoleted by RFC 5905) -- Obsolete informational reference (is this intentional?): RFC 2460 (Obsoleted by RFC 8200) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Haberman, Ed. 3 Internet-Draft JHU 4 Intended status: Historic September 28, 2020 5 Expires: April 1, 2021 7 Control Messages Protocol for Use with Network Time Protocol Version 4 8 draft-ietf-ntp-mode-6-cmds-10 10 Abstract 12 This document describes the structure of the control messages that 13 were historically used with the Network Time Protocol before the 14 advent of more modern control and management approaches. These 15 control messages have been used to monitor and control the Network 16 Time Protocol application running on any IP network attached 17 computer. The information in this document was originally described 18 in Appendix B of RFC 1305. The goal of this document is to provide 19 an updated description of the control messages described in RFC 1305 20 in order to conform with the updated Network Time Protocol 21 specification documented in RFC 5905. 23 The publication of this document is not meant to encourage the 24 development and deployment of these control messages. This document 25 is only providing a current reference for these control messages 26 given the current status of RFC 1305. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on April 1, 2021. 45 Copyright Notice 47 Copyright (c) 2020 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 This document may contain material from IETF Documents or IETF 61 Contributions published or made publicly available before November 62 10, 2008. The person(s) controlling the copyright in some of this 63 material may not have granted the IETF Trust the right to allow 64 modifications of such material outside the IETF Standards Process. 65 Without obtaining an adequate license from the person(s) controlling 66 the copyright in such materials, this document may not be modified 67 outside the IETF Standards Process, and derivative works of it may 68 not be created outside the IETF Standards Process, except to format 69 it for publication as an RFC or to translate it into languages other 70 than English. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 1.1. Control Message Overview . . . . . . . . . . . . . . . . 3 76 1.2. Remote Facility Message Overview . . . . . . . . . . . . 5 77 2. NTP Control Message Format . . . . . . . . . . . . . . . . . 5 78 3. Status Words . . . . . . . . . . . . . . . . . . . . . . . . 7 79 3.1. System Status Word . . . . . . . . . . . . . . . . . . . 8 80 3.2. Peer Status Word . . . . . . . . . . . . . . . . . . . . 10 81 3.3. Clock Status Word . . . . . . . . . . . . . . . . . . . . 12 82 3.4. Error Status Word . . . . . . . . . . . . . . . . . . . . 12 83 4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 13 84 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 86 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18 87 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 88 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 89 9.1. Normative References . . . . . . . . . . . . . . . . . . 18 90 9.2. Informative References . . . . . . . . . . . . . . . . . 19 91 Appendix A. NTP Remote Facility Message Format . . . . . . . . . 19 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 94 1. Introduction 96 RFC 1305 [RFC1305] described a set of control messages for use within 97 the Network Time Protocol (NTP) when a comprehensive network 98 management solution was not available. The definitions of these 99 control messages were not promulgated to RFC 5905 [RFC5905] when NTP 100 version 4 was documented. These messages were intended for use only 101 in systems where no other management facilities were available or 102 appropriate, such as in dedicated-function bus peripherals. Support 103 for these messages is not required in order to conform to RFC 5905 104 [RFC5905]. The control messages are described here as a current 105 reference for use with an RFC 5905 implementation of NTP. 107 The publication of this document is not meant to encourage the 108 development and deployment of these control messages. This document 109 is only providing a current reference for these control messages 110 given the current status of RFC 1305. 112 1.1. Control Message Overview 114 The NTP Mode 6 control messages are used by NTP management programs 115 (e.g., ntpq) when a more robust network management facility (e.g., 116 SNMP) is not available. These control messages provide rudimentary 117 control and monitoring functions to manage a running instance of an 118 NTP server. These commands are not designed to be used for 119 communication between instances of running NTP servers. 121 The NTP Control Message has the value 6 specified in the mode field 122 of the first octet of the NTP header and is formatted as shown in 123 Figure 1. The format of the data field is specific to each command 124 or response; however, in most cases the format is designed to be 125 constructed and viewed by humans and so is coded in free-form ASCII. 126 This facilitates the specification and implementation of simple 127 management tools in the absence of fully evolved network-management 128 facilities. As in ordinary NTP messages, the authenticator field 129 follows the data field. If the authenticator is used the data field 130 is zero-padded to a 32-bit boundary, but the padding bits are not 131 considered part of the data field and are not included in the field 132 count. 134 IP hosts are not required to reassemble datagrams over a certain size 135 (576 octets for IPv4 [RFC0791] and 1280 octets for IPv6 [RFC2460]); 136 however, some commands or responses may involve more data than will 137 fit into a single datagram. Accordingly, a simple reassembly feature 138 is included in which each octet of the message data is numbered 139 starting with zero. As each fragment is transmitted the number of 140 its first octet is inserted in the offset field and the number of 141 octets is inserted in the count field. The more-data (M) bit is set 142 in all fragments except the last. 144 Most control functions involve sending a command and receiving a 145 response, perhaps involving several fragments. The sender chooses a 146 distinct, nonzero sequence number and sets the status field and "R" 147 and "E" bits to zero. The responder interprets the opcode and 148 additional information in the data field, updates the status field, 149 sets the "R" bit to one and returns the three 32-bit words of the 150 header along with additional information in the data field. In case 151 of invalid message format or contents the responder inserts a code in 152 the status field, sets the "R" and "E" bits to one and, optionally, 153 inserts a diagnostic message in the data field. 155 Some commands read or write system variables (e.g., s.offset) and 156 peer variables (e.g., p.stratum) for an association identified in the 157 command. Others read or write variables associated with a radio 158 clock or other device directly connected to a source of primary 159 synchronization information. To identify which type of variable and 160 association the Association ID is used. System variables are 161 indicated by the identifier zero. As each association is mobilized a 162 unique, nonzero identifier is created for it. These identifiers are 163 used in a cyclic fashion, so that the chance of using an old 164 identifier which matches a newly created association is remote. A 165 management entity can request a list of current identifiers and 166 subsequently use them to read and write variables for each 167 association. An attempt to use an expired identifier results in an 168 exception response, following which the list can be requested again. 170 Some exception events, such as when a peer becomes reachable or 171 unreachable, occur spontaneously and are not necessarily associated 172 with a command. An implementation may elect to save the event 173 information for later retrieval or to send an asynchronous response 174 (called a trap) or both. In case of a trap the IP address and port 175 number is determined by a previous command and the sequence field is 176 set as described below. Current status and summary information for 177 the latest exception event is returned in all normal responses. Bits 178 in the status field indicate whether an exception has occurred since 179 the last response and whether more than one exception has occurred. 181 Commands need not necessarily be sent by an NTP peer, so ordinary 182 access-control procedures may not apply; however, the optional mask/ 183 match mechanism suggested in Section Section 6 elsewhere in this 184 document provides the capability to control access by mode number, so 185 this could be used to limit access for control messages (mode 6) to 186 selected address ranges. 188 1.2. Remote Facility Message Overview 190 The original development of the NTP daemon included a remote facility 191 for monitoring and configuration. This facility used mode 7 commands 192 to communicate with the NTP daemon. This document illustrates the 193 mode 7 packet format only. The commands embedded in the mode 7 194 messages are implementation specific and not standardized in any way. 195 The mode 7 message format is described in Appendix A. 197 2. NTP Control Message Format 199 The format of the NTP Control Message header, which immediately 200 follows the UDP header, is shown in Figure 1. Following is a 201 description of its fields. 203 0 1 2 3 204 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 205 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 206 |LI | VN |Mode |R|E|M| OpCode | Sequence Number | 207 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 208 | Status | Association ID | 209 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 210 | Offset | Count | 211 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 212 | | 213 / Data (up to 468 bytes) / 214 | | 215 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 216 | Padding (optional) | 217 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 218 | | 219 / Authenticator (optional, 20 or 24 bits) / 220 | | 221 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 223 Figure 1: NTP Control Message Header 225 Leap Indicator (LI): This is a two-bit integer that is set to b00 for 226 control message requests and responses. The Leap Indicator value 227 used at this position in most NTP modes is in the System Status Word 228 provided in some control message responses. 230 Version Number (VN): This is a three-bit integer indicating a minimum 231 NTP version number. NTP servers do not respond to control messages 232 with an unrecognized version number. Requests may intentionally use 233 a lower version number to enable interoperability with earlier 234 versions of NTP. Responses carry the same version as the 235 corresponding request. 237 Mode: This is a three-bit integer indicating the mode. The value 6 238 indicates an NTP control message. 240 Response Bit (R): Set to zero for commands, one for responses. 242 Error Bit (E): Set to zero for normal response, one for error 243 response. 245 More Bit (M): Set to zero for last fragment, one for all others. 247 Operation Code (OpCode): This is a five-bit integer specifying the 248 command function. Values currently defined include the following: 250 +-------+--------------------------------------------------+ 251 | Code | Meaning | 252 +-------+--------------------------------------------------+ 253 | 0 | reserved | 254 | 1 | read status command/response | 255 | 2 | read variables command/response | 256 | 3 | write variables command/response | 257 | 4 | read clock variables command/response | 258 | 5 | write clock variables command/response | 259 | 6 | set trap address/port command/response | 260 | 7 | trap response | 261 | 8 | runtime configuration command/response | 262 | 9 | export configuration to file command/response | 263 | 10 | retrieve remote address stats command/response | 264 | 11 | retrieve ordered list command/response | 265 | 12 | request client-specific nonce command/response | 266 | 13-30 | reserved | 267 | 31 | unset trap address/port command/response | 268 +-------+--------------------------------------------------+ 270 Sequence Number: This is a 16-bit integer indicating the sequence 271 number of the command or response. Each request uses a different 272 sequence number. Each response carries the same sequence number as 273 its corresponding request. For asynchronous trap responses, the 274 responder increments the sequence number by one for each response, 275 allowing trap receivers to detect missing trap responses. The 276 sequence number of each fragment of a multiple-datagram response 277 carries the same sequence number, copied from the request. 279 Status: This is a 16-bit code indicating the current status of the 280 system, peer or clock, with values coded as described in following 281 sections. 283 Association ID: This is a 16-bit unsigned integer identifying a valid 284 association, or zero for the system clock. 286 Offset: This is a 16-bit unsigned integer indicating the offset, in 287 octets, of the first octet in the data area. The offset is set to 288 zero in requests. Responses spanning multiple datagrams use a 289 positive offset in all but the first datagram. 291 Count: This is a 16-bit unsigned integer indicating the length of the 292 data field, in octets. 294 Data: This contains the message data for the command or response. 295 The maximum number of data octets is 468. 297 Padding (optional): Contains zero to three octets with value zero, as 298 needed to ensure the overall control message size is a multiple of 4 299 octets. 301 Authenticator (optional): When the NTP authentication mechanism is 302 implemented, this contains the authenticator information defined in 303 Appendix C of [RFC1305]. 305 3. Status Words 307 Status words indicate the present status of the system, associations 308 and clock. They are designed to be interpreted by network-monitoring 309 programs and are in one of four 16-bit formats shown in Figure 2 and 310 described in this section. System and peer status words are 311 associated with responses for all commands except the read clock 312 variables, write clock variables and set trap address/port commands. 313 The association identifier zero specifies the system status word, 314 while a nonzero identifier specifies a particular peer association. 315 The status word returned in response to read clock variables and 316 write clock variables commands indicates the state of the clock 317 hardware and decoding software. A special error status word is used 318 to report malformed command fields or invalid values. 320 0 1 321 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 322 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 323 | LI| Clock Src | Count | Code | 324 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 325 System Status Word 327 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 328 | Status | SEL | Count | Code | 329 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 330 Peer Status Word 332 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 333 | Clock Status | Code | 334 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 335 Radio Status Word 337 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 338 | Error Code | Reserved | 339 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 340 Error Status Word 342 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 343 | Reserved | Count | Code | 344 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 345 Clock Status Word 347 Figure 2: Status Word Formats 349 3.1. System Status Word 351 The system status word appears in the status field of the response to 352 a read status or read variables command with a zero association 353 identifier. The format of the system status word is as follows: 355 Leap Indicator (LI): This is a two-bit code warning of an impending 356 leap second to be inserted/deleted in the last minute of the current 357 day, with bit 0 and bit 1, respectively, coded as follows: 359 +------+------------------------------------------------------------+ 360 | LI | Meaning | 361 +------+------------------------------------------------------------+ 362 | 00 | no warning | 363 | 01 | insert second after 23:59:59 of the current day | 364 | 10 | delete second 23:59:59 of the current day | 365 | 11 | unsynchronized | 366 +------+------------------------------------------------------------+ 367 Clock Source (Clock Src): This is a six-bit integer indicating the 368 current synchronization source, with values coded as follows: 370 +-------+-----------------------------------------------------------+ 371 | Code | Meaning | 372 +-------+-----------------------------------------------------------+ 373 | 0 | unspecified or unknown | 374 | 1 | Calibrated atomic clock (e.g., PPS, HP 5061) | 375 | 2 | VLF (band 4) or LF (band 5) radio (e.g., OMEGA,, WWVB) | 376 | 3 | HF (band 7) radio (e.g., CHU, MSF, WWV/H) | 377 | 4 | UHF (band 9) satellite (e.g., GOES, GPS) | 378 | 5 | local net (e.g., DCN, TSP, DTS) | 379 | 6 | UDP/NTP | 380 | 7 | UDP/TIME | 381 | 8 | eyeball-and-wristwatch | 382 | 9 | telephone modem (e.g., NIST) | 383 | 10-63 | reserved | 384 +-------+-----------------------------------------------------------+ 386 System Event Counter (Count): This is a four-bit integer indicating 387 the number of system events occurring since the last time the System 388 Event Code changed. Upon reaching 15, subsequent events with the 389 same code are not counted. 391 System Event Code (Code): This is a four-bit integer identifying the 392 latest system exception event, with new values overwriting previous 393 values, and coded as follows: 395 +------+---------------------------------------------------------+ 396 | Code | Meaning | 397 +------+---------------------------------------------------------+ 398 | 0 | unspecified | 399 | 1 | frequency correction (drift) file not available | 400 | 2 | frequency correction started (frequency stepped) | 401 | 3 | spike detected and ignored, starting stepout timer | 402 | 4 | frequency training started | 403 | 5 | clock synchronized | 404 | 6 | system restart | 405 | 7 | panic stop (required step greater than panic threshold) | 406 | 8 | no system peer | 407 | 9 | leap second insertion/deletion armed for the | 408 | | of the current month | 409 | 10 | leap second disarmed | 410 | 11 | leap second inserted or deleted | 411 | 12 | clock stepped (stepout timer expired) | 412 | 13 | kernel loop discipline status changed | 413 | 14 | leapseconds table loaded from file | 414 | 15 | leapseconds table outdated, updated file needed | 415 +------+---------------------------------------------------------+ 417 3.2. Peer Status Word 419 A peer status word is returned in the status field of a response to a 420 read status, read variables or write variables command and appears 421 also in the list of association identifiers and status words returned 422 by a read status command with a zero association identifier. The 423 format of a peer status word is as follows: 425 Peer Status (Status): This is a five-bit code indicating the status 426 of the peer determined by the packet procedure, with bits assigned as 427 follows: 429 +-------------+---------------------------------------------------+ 430 | Peer Status | Meaning | 431 | bit | | 432 +-------------+---------------------------------------------------+ 433 | 0 | configured (peer.config) | 434 | 1 | authentication enabled (peer.authenable) | 435 | 2 | authentication okay (peer.authentic) | 436 | 3 | reachability okay (peer.reach != 0) | 437 | 4 | broadcast association | 438 +-------------+---------------------------------------------------+ 440 Peer Selection (SEL): This is a three-bit integer indicating the 441 status of the peer determined by the clock-selection procedure, with 442 values coded as follows: 444 +-----+-------------------------------------------------------------+ 445 | Sel | Meaning | 446 +-----+-------------------------------------------------------------+ 447 | 0 | rejected | 448 | 1 | discarded by intersection algorithm | 449 | 2 | discarded by table overflow (not currently used) | 450 | 3 | discarded by the cluster algorithm | 451 | 4 | included by the combine algorithm | 452 | 5 | backup source (with more than sys.maxclock survivors) | 453 | 6 | system peer (synchronization source) | 454 | 7 | PPS (pulse per second) peer | 455 +-----+-------------------------------------------------------------+ 457 Peer Event Counter (Count): This is a four-bit integer indicating the 458 number of peer exception events that occurred since the last time the 459 peer event code changed. Upon reaching 15, subsequent events with 460 the same code are not counted. 462 Peer Event Code (Code): This is a four-bit integer identifying the 463 latest peer exception event, with new values overwriting previous 464 values, and coded as follows: 466 +-------+--------------------------------------------------------+ 467 | Peer | | 468 | Event | Meaning | 469 | Code | | 470 +-------+--------------------------------------------------------+ 471 | 0 | unspecified | 472 | 1 | association mobilized | 473 | 2 | association demobilized | 474 | 3 | peer unreachable (peer.reach was nonzero now zero) | 475 | 4 | peer reachable (peer.reach was zero now nonzero) | 476 | 5 | association restarted or timed out | 477 | 6 | no reply (only used with one-shot clock set command) | 478 | 7 | peer rate limit exceeded (kiss code RATE received) | 479 | 8 | access denied (kiss code DENY received) | 480 | 9 | leap second insertion/deletion at month's end armed | 481 | | by peer vote | 482 | 10 | became system peer (sys.peer) | 483 | 11 | reference clock event (see clock status word) | 484 | 12 | authentication failed | 485 | 13 | popcorn spike suppressed by peer clock filter register | 486 | 14 | entering interleaved mode | 487 | 15 | recovered from interleave error | 488 +-------+--------------------------------------------------------+ 490 3.3. Clock Status Word 492 There are two ways a reference clock can be attached to a NTP service 493 host, as a dedicated device managed by the operating system and as a 494 synthetic peer managed by NTP. As in the read status command, the 495 association identifier is used to identify which one, zero for the 496 system clock and nonzero for a peer clock. Only one system clock is 497 supported by the protocol, although many peer clocks can be 498 supported. A system or peer clock status word appears in the status 499 field of the response to a read clock variables or write clock 500 variables command. This word can be considered an extension of the 501 system status word or the peer status word as appropriate. The 502 format of the clock status word is as follows: 504 Reserved: An eight-bit integer that is ignored by requesters and 505 zeroed by responders. 507 Count: This is a four-bit integer indicating the number of clock 508 events that occurred since the last time the clock event code 509 changed. Upon reaching 15, subsequent events with the same code are 510 not counted. 512 Clock Code (Code): This is a four-bit integer indicating the current 513 clock status, with values coded as follows: 515 +--------------+--------------------------------------------------+ 516 | Clock Status | Meaning | 517 +--------------+--------------------------------------------------+ 518 | 0 | clock operating within nominals | 519 | 1 | reply timeout | 520 | 2 | bad reply format | 521 | 3 | hardware or software fault | 522 | 4 | propagation failure | 523 | 5 | bad date format or value | 524 | 6 | bad time format or value | 525 | 7-15 | reserved | 526 +--------------+--------------------------------------------------+ 528 3.4. Error Status Word 530 An error status word is returned in the status field of an error 531 response as the result of invalid message format or contents. Its 532 presence is indicated when the E (error) bit is set along with the 533 response (R) bit in the response. It consists of an eight-bit 534 integer coded as follows: 536 +--------------+--------------------------------------------------+ 537 | Error Status | Meaning | 538 +--------------+--------------------------------------------------+ 539 | 0 | unspecified | 540 | 1 | authentication failure | 541 | 2 | invalid message length or format | 542 | 3 | invalid opcode | 543 | 4 | unknown association identifier | 544 | 5 | unknown variable name | 545 | 6 | invalid variable value | 546 | 7 | administratively prohibited | 547 | 8-255 | reserved | 548 +--------------+--------------------------------------------------+ 550 4. Commands 552 Commands consist of the header and optional data field shown in 553 Figure 1. When present, the data field contains a list of 554 identifiers or assignments in the form 555 <>[=<>],<>[=<>],... where 556 <> is the ASCII name of a system or peer variable such as 557 the ones specified in RFC 5905 and <> is expressed as a 558 decimal, hexadecimal or string constant in the syntax of the C 559 programming language. Where no ambiguity exists, the "sys." or 560 "peer." prefixes can be suppressed. Whitespace (ASCII nonprinting 561 format effectors) can be added to improve readability for simple 562 monitoring programs that do not reformat the data field. Internet 563 addresses are represented as follows: IPv4 addresses are written in 564 the form [n.n.n.n], where n is in decimal notation and the brackets 565 are optional; IPv6 addresses are formulated based on the guidelines 566 defined in [RFC5952]. Timestamps, including reference, originate, 567 receive and transmit values, as well as the logical clock, are 568 represented in units of seconds and fractions, preferably in 569 hexadecimal notation. Delay, offset, dispersion and distance values 570 are represented in units of milliseconds and fractions, preferably in 571 decimal notation. All other values are represented as-is, preferably 572 in decimal notation. 574 Implementations may define variables other than those described in 575 RFC 5905. Called extramural variables, these are distinguished by 576 the inclusion of some character type other than alphanumeric or "." 577 in the name. For those commands that return a list of assignments in 578 the response data field, if the command data field is empty, it is 579 expected that all available variables defined in RFC 5905 will be 580 included in the response. For the read commands, if the command data 581 field is nonempty, an implementation may choose to process this field 582 to individually select which variables are to be returned. 584 Commands are interpreted as follows: 586 Read Status (1): The command data field is empty or contains a list 587 of identifiers separated by commas. The command operates in two ways 588 depending on the value of the association identifier. If this 589 identifier is nonzero, the response includes the peer identifier and 590 status word. Optionally, the response data field may contain other 591 information, such as described in the Read Variables command. If the 592 association identifier is zero, the response includes the system 593 identifier (0) and status word, while the data field contains a list 594 of binary-coded pairs <> <>, one 595 for each currently defined association. 597 Read Variables (2): The command data field is empty or contains a 598 list of identifiers separated by commas. If the association 599 identifier is nonzero, the response includes the requested peer 600 identifier and status word, while the data field contains a list of 601 peer variables and values as described above. If the association 602 identifier is zero, the data field contains a list of system 603 variables. If a peer has been selected as the synchronization 604 source, the response includes the peer identifier and status word; 605 otherwise, the response includes the system identifier (0) and status 606 word. 608 Write Variables (3): The command data field contains a list of 609 assignments as described above. The variables are updated as 610 indicated. The response is as described for the Read Variables 611 command. 613 Read Clock Variables (4): The command data field is empty or contains 614 a list of identifiers separated by commas. The association 615 identifier selects the system clock variables or peer clock variables 616 in the same way as in the Read Variables command. The response 617 includes the requested clock identifier and status word and the data 618 field contains a list of clock variables and values, including the 619 last timecode message received from the clock. 621 Write Clock Variables (5): The command data field contains a list of 622 assignments as described above. The clock variables are updated as 623 indicated. The response is as described for the Read Clock Variables 624 command. 626 Set Trap Address/Port (6): The command association identifier, status 627 and data fields are ignored. The address and port number for 628 subsequent trap messages are taken from the source address and port 629 of the control message itself. The initial trap counter for trap 630 response messages is taken from the sequence field of the command. 631 The response association identifier, status and data fields are not 632 significant. Implementations should include sanity timeouts which 633 prevent trap transmissions if the monitoring program does not renew 634 this information after a lengthy interval. 636 Trap Response (7): This message is sent when a system, peer or clock 637 exception event occurs. The opcode field is 7 and the R bit is set. 638 The trap counter is incremented by one for each trap sent and the 639 sequence field set to that value. The trap message is sent using the 640 IP address and port fields established by the set trap address/port 641 command. If a system trap the association identifier field is set to 642 zero and the status field contains the system status word. If a peer 643 trap the association identifier field is set to that peer and the 644 status field contains the peer status word. Optional ASCII-coded 645 information can be included in the data field. 647 Configure (8): The command data is parsed and applied as if supplied 648 in the daemon configuration file. 650 Save Configuration (9): Write a snapshot of the current configuration 651 to the file name supplied as the command data. Further, the command 652 is refused unless a directory in which to store the resulting files 653 has been explicitly configured by the operator. 655 Read Most Recently Used (MRU) list (10): Retrieves records of 656 recently seen remote addresses and associated statistics. Command 657 data consists of name=value pairs controlling the selection of 658 records, as well as a requestor-specific nonce previously retrieved 659 using this command or opcode 12, Request Nonce. The response 660 consists of name=value pairs where some names can appear multiple 661 times using a dot followed by a zero-based index to distinguish them, 662 and to associate elements of the same record with the same index. A 663 new nonce is provided with each successful response. 665 Read ordered list (11): Retrieves a list ordered by IP address (IPv4 666 information precedes IPv6 information). If the command data is empty 667 or the seven characters "ifstats", the associated statistics, status 668 and counters for each local address are returned. If the command 669 data is the characters "addr_restrictions" then the set of IPv4 670 remote address restrictions followed by the set of IPv6 remote 671 address restrictions (access control lists) are returned. Other 672 command data returns error code 5 (unknown variable name). Similar 673 to Read MRU, response information uses zero-based indexes as part of 674 the variable name preceding the equals sign and value, where each 675 index relates information for a single address or network. This 676 opcode requires authentication. 678 Request Nonce (12): Retrieves a 96-bit nonce specific to the 679 requesting remote address, which is valid for a limited period. 681 Command data is not used in the request. The nonce consists of a 682 64-bit NTP timestamp and 32 bits of hash derived from that timestamp, 683 the remote address, and salt known only to the server which varies 684 between daemon runs. Inclusion of the nonce by a management agent 685 demonstrates to the server that the agent can receive datagrams sent 686 to the source address of the request, making source address 687 "spoofing" more difficult in a similar way as TCP's three-way 688 handshake. 690 Unset Trap (31): Removes the requesting remote address and port from 691 the list of trap receivers. Command data is not used in the request. 692 If the address and port are not in the list of trap receivers, the 693 error code is 4, bad association. 695 5. IANA Considerations 697 This document makes no request of IANA. 699 Note to RFC Editor: this section may be removed on publication as an 700 RFC. 702 6. Security Considerations 704 A number of security vulnerabilities have been identified with these 705 control messages. 707 NTP's control query interface allows reading and writing of system, 708 peer, and clock variables remotely from arbitrary IP addresses using 709 commands mentioned in Section 4. Traditionally, overwriting these 710 variables, but not reading them, requires authentication by default. 711 However, this document argues that an NTP host must authenticate all 712 control queries and not just ones that overwrite these variables. 713 Alternatively, the host can use an access control list to explicitly 714 list IP addresses that are allowed to control query the clients. 715 These access controls are required for the following reasons: 717 o NTP as a Distributed Denial-of-Service (DDoS) vector. NTP timing 718 query and response packets (modes 1-2, 3-4, 5) are usually short 719 in size. However, some NTP control queries generate a very long 720 packet in response to a short query. As such, there is a history 721 of use of NTP's control queries, which exhibit such behavior, to 722 perform DDoS attacks. These off-path attacks exploit the large 723 size of NTP control queries to cause UDP-based amplification 724 attacks (e.g., mode 7 monlist command generates a very long packet 725 in response to a small query [CVE-DOS]). These attacks only use 726 NTP as a vector for DoS attacks on other protocols, but do not 727 affect the time service on the NTP host itself. To limit the 728 sources of these malicious commands, NTP server operators are 729 recommended to deploy ingress filtering [RFC3704]. 731 o Time-shifting attacks through information leakage/overwriting. 732 NTP hosts save important system and peer state variables. An off- 733 path attacker who can read these variables remotely can leverage 734 the information leaked by these control queries to perform time- 735 shifting and DoS attacks on NTP clients. These attacks do affect 736 time synchronization on the NTP hosts. For instance, 738 * In the client/server mode, the client stores its local time 739 when it sends the query to the server in its xmt peer variable. 740 This variable is used to perform TEST2 to non-cryptographically 741 authenticate the server, i.e., if the origin timestamp field in 742 the corresponding server response packet matches the xmt peer 743 variable, then the client accepts the packet. An off-path 744 attacker, with the ability to read this variable can easily 745 spoof server response packets for the client, which will pass 746 TEST2, and can deny service or shift time on the NTP client. 747 The specific attack is described in [CVE-SPOOF]. 749 * The client also stores its local time when the server response 750 is received in its rec peer variable. This variable is used 751 for authentication in interleaved-pivot mode. An off-path 752 attacker with the ability to read this state variable can 753 easily shift time on the client by passing this test. This 754 attack is described in [CVE-SHIFT]. 756 o Fast-Scanning. NTP mode 6 control messages are usually small UDP 757 packets. Fast-scanning tools like ZMap can be used to spray the 758 entire (potentially reachable) Internet with these messages within 759 hours to identify vulnerable hosts. To make things worse, these 760 attacks can be extremely low-rate, only requiring a control query 761 for reconnaissance and a spoofed response to shift time on 762 vulnerable clients. 764 o The mode 6 and 7 messages are vulnerable to replay attacks 765 [CVE-Replay]. If an attacker observes mode 6/7 packets that 766 modify the configuration of the server in any way, the attacker 767 can apply the same change at any time later simply by sending the 768 packets to the server again. The use of the nonce (Request Nonce 769 command) provides limited protection against replay attacks. 771 NTP best practices recommend configuring NTP with the no-query 772 parameter. The no-query parameter blocks access to all remote 773 control queries. However, sometimes the hosts do not want to block 774 all queries and want to give access for certain control queries 775 remotely. This could be for the purpose of remote management and 776 configuration of the hosts in certain scenarios. Such hosts tend to 777 use firewalls or other middleboxes to blacklist certain queries 778 within the network. 780 Significantly fewer hosts respond to mode 7 monlist queries as 781 compared to other control queries because it is a well-known and 782 exploited control query. These queries are likely blocked using 783 blacklists on firewalls and middleboxes rather than the no-query 784 option on NTP hosts. The remaining control queries that can be 785 exploited likely remain out of the blacklist because they are 786 undocumented in the current NTP specification [RFC5905]. 788 This document describes all of the mode 6 control queries allowed by 789 NTP and can help administrators make informed decisions on security 790 measures to protect NTP devices from harmful queries and likely make 791 those systems less vulnerable. Regardless of which mode 6 commands 792 an administrator may elect to allow, remote access to this facility 793 needs to be protected from unauthorized access (e.g., strict ACLs). 795 7. Contributors 797 Dr. David Mills specified the vast majority of the mode 6 commands 798 during the development of RFC 1305 [RFC1305] and deserves the credit 799 for their existence and use. 801 8. Acknowledgements 803 Tim Plunkett created the original version of this document. Aanchal 804 Malhotra provided the initial version of the Security Considerations 805 section. 807 Karen O'Donoghue, David Hart, Harlan Stenn, and Philip Chimento 808 deserve credit for portions of this document due to their earlier 809 efforts to document these commands. 811 Miroshav Lichvar, Ulrich Windl, Dieter Sibold, J Ignacio Alvarez- 812 Hamelin, and Alex Campbell provided valuable comments on various 813 versions of this document. 815 9. References 817 9.1. Normative References 819 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 820 Specification, Implementation and Analysis", RFC 1305, 821 DOI 10.17487/RFC1305, March 1992, 822 . 824 [RFC3704] Baker, F. and P. Savola, "Ingress Filtering for Multihomed 825 Networks", BCP 84, RFC 3704, DOI 10.17487/RFC3704, March 826 2004, . 828 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 829 "Network Time Protocol Version 4: Protocol and Algorithms 830 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 831 . 833 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 834 Address Text Representation", RFC 5952, 835 DOI 10.17487/RFC5952, August 2010, 836 . 838 9.2. Informative References 840 [CVE-DOS] NIST National Vulnerability Database, "CVE-2013-5211, 841 https://nvd.nist.gov/vuln/detail/CVE-2013-5211", January 842 2014. 844 [CVE-Replay] 845 NIST National Vulnerability Database, "CVE-2015-8140, 846 https://nvd.nist.gov/vuln/detail/CVE-2015-8140", January 847 2015. 849 [CVE-SHIFT] 850 NIST National Vulnerability Database, "CVE-2016-1548, 851 https://nvd.nist.gov/vuln/detail/CVE-2016-1548", January 852 2017. 854 [CVE-SPOOF] 855 NIST National Vulnerability Database, "CVE-2015-8139, 856 https://nvd.nist.gov/vuln/detail/CVE-2015-8139", January 857 2017. 859 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 860 DOI 10.17487/RFC0791, September 1981, 861 . 863 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 864 (IPv6) Specification", RFC 2460, DOI 10.17487/RFC2460, 865 December 1998, . 867 Appendix A. NTP Remote Facility Message Format 869 The format of the NTP Remote Facility Message header, which 870 immediately follows the UDP header, is shown in Figure 3. Following 871 is a description of its fields. Bit positions marked as zero are 872 reserved and should always be transmitted as zero. 874 0 1 2 3 875 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 876 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 877 |R|M| VN |Mode |A| Sequence | Implementation| Req Code | 878 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 879 | Err | Count | MBZ | Size | 880 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 881 | | 882 / Data (up to 500 bytes) / 883 | | 884 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 885 | Encryption KeyID (when A bit set) | 886 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 887 | | 888 / Message Authentication Code (when A bit set) / 889 | | 890 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 892 Figure 3: NTP Remote Facility Message Header 894 Response Bit (R) : Set to 0 if the packet is a request. Set to 1 if 895 the packet is a response. 897 More Bit (M) : Set to 0 if this is the last packet in a response, 898 otherwise set to 1 in responses requiring more than one packet. 900 Version Number (VN) : Set to the version number of the NTP daemon. 902 Mode : Set to 7 for Remote Facility messages. 904 Authenticated Bit (A) : If set to 1, this packet contains 905 authentication information. 907 Sequence : For a multi-packet response, this field contains the 908 sequence number of this packet. Packets in a multi-packet response 909 are numbered starting with 0. The More Bit is set to 1 for all 910 packets but the last. 912 Implementation : The version number of the implementation that 913 defined the request code used in this message. An implementation 914 number of 0 is used for a Request Code supported by all versions of 915 the NTP daemon. The value 255 is reserved for future extensions. 917 Request Code (Req Code) : An implementation-specific code which 918 specifies the operation being requested. A Request Code definition 919 includes the format and semantics of the data included in the packet. 921 Error (Err) : Set to 0 for a request. For a response, this field 922 contains an error code relating to the request. If the Error is non- 923 zero, the operation requested wasn't performed. 925 0 - no error 927 1 - incompatible implementation number 929 2 - unimplemented request code 931 3 - format error 933 4 - no data available 935 7 - authentication failure 937 Count : The number of data items in the packet. Range is 0 to 500. 939 Must Be Zero (MBZ) : A reserved field set to 0 in requests and 940 responses. 942 Size : The size of each data item in the packet. Range is 0 to 500. 944 Data : A variable-sized field containing request/response data. For 945 requests and responses, the size in octets must be greater than or 946 equal to the product of the number of data items (Count) and the size 947 of a data item (Size). For requests, the data area is exactly 40 948 octets in length. For responses, the data area will range from 0 to 949 500 octets, inclusive. 951 Encryption KeyID : A 32-bit unsigned integer used to designate the 952 key used for the Message Authentication Code. This field is included 953 only when the A bit is set to 1. 955 Message Authentication Code : An optional Message Authentication Code 956 defined by the version of the NTP daemon indicated in the 957 Implementation field. This field is included only when the A bit is 958 set to 1. 960 Author's Address 961 Brian Haberman (editor) 962 JHU 964 Email: brian@innovationslab.net