idnits 2.17.1 draft-odonoghue-ntpv4-control-02.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 : ---------------------------------------------------------------------------- ** There are 92 instances of too long lines in the document, the longest one being 9 characters in excess of 72. 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 (October 2013) is 3846 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC5906' is defined on line 712, but no explicit reference was found in the text == Unused Reference: 'RFC5907' is defined on line 715, but no explicit reference was found in the text == Unused Reference: 'RFC5908' is defined on line 719, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. L. . Mills 3 Internet-Draft University of Delaware 4 Intended status: Informational K.F. O'Donoghue, Ed. 5 Expires: April 02, 2014 Internet Society 6 D. L. . Hart 7 H. M. . Stenn 8 Network Time Foundation, Inc. 9 P.F. Chimento, Ed. 10 Johns Hopkins University/APL 11 October 2013 13 Control Messages Protocol for Use with Network Time Protocol Version 4 14 draft-odonoghue-ntpv4-control-02 16 Abstract 18 This document describes the structure of the control messages used 19 with the Network Time Protocol. These control messages can be used 20 to monitor and control the Network Time Protocol application running 21 on any IP network attached computer. The information in this 22 informational RFC was originally described in Appendix B of RFC 1305. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 02, 2014. 41 Copyright Notice 43 Copyright (c) 2013 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents (http://trustee.ietf.org/ 48 license-info) in effect on the date of publication of this document. 49 Please review these documents carefully, as they describe your rights 50 and restrictions with respect to this document. Code Components 51 extracted from this document must include Simplified BSD License text 52 as described in Section 4.e of the Trust Legal Provisions and are 53 provided without warranty as described in the Simplified BSD License. 55 This document may contain material from IETF Documents or IETF 56 Contributions published or made publicly available before November 57 10, 2008. The person(s) controlling the copyright in some of this 58 material may not have granted the IETF Trust the right to allow 59 modifications of such material outside the IETF Standards Process. 60 Without obtaining an adequate license from the person(s) controlling 61 the copyright in such materials, this document may not be modified 62 outside the IETF Standards Process, and derivative works of it may 63 not be created outside the IETF Standards Process, except to format 64 it for publication as an RFC or to translate it into languages other 65 than English. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 70 2. NTP Control Message Format . . . . . . . . . . . . . . . . . . 4 71 3. Status Words . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 3.1. System Status Word . . . . . . . . . . . . . . . . . . . . 7 73 3.2. Peer Status Word . . . . . . . . . . . . . . . . . . . . . 9 74 3.3. Clock Status Word . . . . . . . . . . . . . . . . . . . . 11 75 3.4. Error Status Word . . . . . . . . . . . . . . . . . . . . 12 76 4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 78 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 79 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 16 80 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 81 8.1. Normative References . . . . . . . . . . . . . . . . . . . 16 82 8.2. Informative References . . . . . . . . . . . . . . . . . . 16 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 85 1. Introduction 87 Editor's Note (to be removed prior to publication): The text below is 88 taken directly from RFC 1305. Input is requested to update the text 89 to reflect current practice. This is required to fully obsolete RFC 90 1305. 92 In a comprehensive network-management environment, facilities are 93 presumed available to perform routine NTP control and monitoring 94 functions, such as setting the leap-indicator bits at the primary 95 servers, adjusting the various system parameters and monitoring 96 regular operations. Ordinarily, these functions can be implemented 97 using a network-management protocol such as SNMP and suitable 98 extensions to the MIB database. However, in those cases where such 99 facilities are not available, these functions can be implemented 100 using special NTP control messages described herein. These messages 101 are intended for use only in systems where no other management 102 facilities are available or appropriate, such as in dedicated- 103 function bus peripherals. Support for these messages is not required 104 in order to conform to this specification. 106 The NTP Control Message has the value 6 specified in the mode field 107 of the first octet of the NTP header and is formatted as shown below. 108 The format of the data field is specific to each command or response; 109 however, in most cases the format is designed to be constructed and 110 viewed by humans and so is coded in free-form ASCII. This facilitates 111 the specification and implementation of simple management tools in 112 the absence of fully evolved network-management facilities. As in 113 ordinary NTP messages, the authenticator field follows the data 114 field. If the authenticator is used the data field is zero-padded to 115 a 32-bit boundary, but the padding bits are not considered part of 116 the data field and are not included in the field count. 118 IP hosts are not required to reassemble datagrams larger than 576 119 octets; however, some commands or responses may involve more data 120 than will fit into a single datagram. Accordingly, a simple 121 reassembly feature is included in which each octet of the message 122 data is numbered starting with zero. As each fragment is transmitted 123 the number of its first octet is inserted in the offset field and the 124 number of octets is inserted in the count field. The more-data (M) 125 bit is set in all fragments except the last. 127 Most control functions involve sending a command and receiving a 128 response, perhaps involving several fragments. The sender chooses a 129 distinct, nonzero sequence number and sets the status field and R and 130 E bits to zero. The responder interprets the opcode and additional 131 information in the data field, updates the status field, sets the R 132 bit to one and returns the three 32-bit words of the header along 133 with additional information in the data field. In case of invalid 134 message format or contents the responder inserts a code in the status 135 field, sets the R and E bits to one and, optionally, inserts a 136 diagnostic message in the data field. 138 Some commands read or write system variables and peer variables for 139 an association identified in the command. Others read or write 140 variables associated with a radio clock or other device directly 141 connected to a source of primary synchronization information. To 142 identify which type of variable and association a 16-bit association 143 identifier is used. System variables are indicated by the identifier 144 zero. As each association is mobilized a unique, nonzero identifier 145 is created for it. These identifiers are used in a cyclic fashion, 146 so that the chance of using an old identifier which matches a newly 147 created association is remote. A management entity can request a 148 list of current identifiers and subsequently use them to read and 149 write variables for each association. An attempt to use an expired 150 identifier results in an exception response, following which the list 151 can be requested again. 153 Some exception events, such as when a peer becomes reachable or 154 unreachable, occur spontaneously and are not necessarily associated 155 with a command. An implementation may elect to save the event 156 information for later retrieval or to send an asynchronous response 157 (called a trap) or both. In case of a trap the IP address and port 158 number is determined by a previous command and the sequence field is 159 set as described below. Current status and summary information for 160 the latest exception event is returned in all normal responses. Bits 161 in the status field indicate whether an exception has occurred since 162 the last response and whether more than one exception has occurred. 164 Commands need not necessarily be sent by an NTP peer, so ordinary 165 access-control procedures may not apply; however, the optional mask/ 166 match mechanism suggested in [RFC5905] provides the capability to 167 limit mode 6 processing to selected address ranges. 169 The Network Time Protocol reference implementation maintained by the 170 University of Delaware and ntp.org provides a utility program, ntpq 171 which enables management and configuration of the ntpd daemon using 172 NTP Control Messages (mode 6). A related utility program, ntpdc, uses 173 an earlier, deprecated implementation-specific binary management 174 protocol using NTP mode 7 datagrams. Due to the implementation 175 complexity of the earlier protocol, the reference implementation has 176 added support for all operations that previously were exposed only 177 via mode 7 to the preferred mode 6 interface. Support for mode 7 178 requests is likely to be disabled by default in the reference 179 implementation's daemon. 181 2. NTP Control Message Format 183 The format of the NTP Control Message header, which immediately 184 follows the UDP header, is shown below. Following is a description 185 of its fields. Bit positions marked as zero are reserved and should 186 always be transmitted as zero. 188 0 1 2 3 189 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 190 +---+-----+-----+-----+---------+-------------------------------+ 191 |LI | VN |Mode |R E M| Op | Sequence | 192 +---+-----+-----+-----+---------+-------------------------------+ 193 | Status | Association ID | 194 +-------------------------------+-------------------------------+ 195 | Offset | Count | 196 +-------------------------------+-------------------------------+ 197 | | 198 | Data | 199 | (468 octets or less) | 200 | | 201 | +-----------------------------------------------+ 202 | | Padding as needed to next multiple of 32 bits | 203 +---------------+-----------------------------------------------+ 204 | Authenticator (optional, 96 octets or less) | 205 +---------------------------------------------------------------+ 207 LI: This is a two-bit integer that must be zero for control message 208 requests and responses. The Leap Indicator value used at this 209 position in most NTP modes is in the System Status Word provided in 210 some control message responses. 212 Version Number (VN): This is a three-bit integer indicating a minimum 213 NTP version number. NTP servers should not respond to control 214 messages with an unrecognized version number. Requests may 215 intentionally use a lower version number to enable interoperability 216 with earlier versions. The reference implementation utility ntpq 217 uses version 2 by default. Responses must carry the same version as 218 the corresponding request. 220 Mode: This is a three-bit integer indicating the mode. It must have 221 the value 6, indicating an NTP control message. 223 Response Bit (R): Set to zero for commands, one for responses. 225 Error Bit (E): Set to zero for normal response, one for error 226 response. 228 More Bit (M): Set to zero for last fragment, one for all others. 230 Operation Code (Op): This is a five-bit integer specifying the 231 command function. The values are: 233 +-------+--------------------------------------------------+ 234 | Code | Meaning | 235 +-------+--------------------------------------------------+ 236 | 0 | reserved | 237 | 1 | read status command/response | 238 | 2 | read variables command/response | 239 | 3 | write variables command/response | 240 | 4 | read clock variables command/response | 241 | 5 | write clock variables command/response | 242 | 6 | set trap address/port command/response | 243 | 7 | trap response | 244 | 8 | runtime configuration command/response | 245 | 9 | export configuration to file command/response | 246 | 10 | retrieve remote address stats command/response | 247 | 11 | retrieve ordered list | 248 | 12 | request client-specific nonce command/response | 249 | 13-30 | reserved for future use | 250 | 31 | unset trap address/port command/response | 251 +-------+--------------------------------------------------+ 253 Sequence: This is a 16-bit integer indicating the sequence number. 254 Each request should use a different sequence number. Each response 255 carries the same sequence number as its corresponding request. For 256 asynchronous trap responses, the responder increments the sequence 257 number by one each response, allowing trap receivers to detect 258 missing trap responses. Note the sequence number of each fragment in 259 a multiple-datagram response carries the same sequence number, copied 260 from the request. 262 Status: This is a 16-bit code indicating the current status of the 263 system, peer or clock, with values coded as described in following 264 sections. 266 Association ID: This is a 16-bit unsigned integer identifying a valid 267 association, or zero for the system clock. 269 Offset: This is a 16-bit unsigned integer indicating the offset, in 270 octets, of the first octet in the data area. The offset must be zero 271 in requests. Responses spanning multiple datagrams use a positive 272 offset in all but the first datagram. 274 Count: This is a 16-bit unsigned integer indicating the length of the 275 data, in octets 277 Data: This contains the message data for the command or response. 278 The maximum number of data octets is 468. 280 Padding: Contains zero to three octets with value zero, as needed to 281 ensure the overall control message size is a multiple of 4 octets. 283 Authenticator (optional): When an NTP authentication mechanism is 284 used, this contains the message authenticator information defined in 285 section 7.3 of [RFC5905]. 287 3. Status Words 289 Status words indicate the present status of the system, associations 290 and clock. They are designed to be interpreted by network-monitoring 291 programs and are in one of four 16-bit formats shown in Figure 6 and 292 described in this section. System and peer status words are 293 associated with responses for all commands except the read clock 294 variables, write clock variables and set trap address/port commands. 295 The association identifier zero specifies the system status word, 296 while a nonzero identifier specifies a particular peer association. 297 The status word returned in response to read clock variables and 298 write clock variables commands indicates the state of the clock 299 hardware and decoding software. A special error status word is used 300 to report malformed command fields or invalid values. 302 3.1. System Status Word 304 The system status word appears in the status field of the response to 305 a read status or read variables command with a zero association 306 identifier. The format of the system status word is as follows: 308 0 1 309 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 310 +---+-----------+-------+-------+ 311 |LI | ClockSrc | Count | Code | 312 +---+-----------+-------+-------+ 314 Leap Indicator (LI): This is a two-bit code warning of an impending 315 leap second to be inserted/deleted in the last minute of the current 316 day, with bit 0 and bit 1, respectively, coded as follows: (EDITOR: 317 this could refer to RFC 5905 section 7.3 figure 9 instead.) 319 +------+------------------------------------------------------------+ 320 | LI | Meaning | 321 +------+------------------------------------------------------------+ 322 | 00 | no warning | 323 | 01 | insert second after 23:59:59 of the current day | 324 | 10 | delete second 23:59:59 of the current day | 325 | 11 | unsynchronized | 326 +------+------------------------------------------------------------+ 328 ClockSrc: This is a six-bit integer indicating the current 329 synchronization source, with values coded as follows: 331 +-------+-----------------------------------------------------------+ 332 | Code | Meaning | 333 +-------+-----------------------------------------------------------+ 334 | 0 | unspecified or unknown | 335 | 1 | Calibrated atomic clock (e.g., PPS, HP 5061) | 336 | 2 | VLF (band 4) or LF (band 5) radio (e.g., OMEGA, WWVB) | 337 | 3 | HF (band 7) radio (e.g., CHU, MSF, WWV/H) | 338 | 4 | UHF (band 9) satellite (e.g., GOES, GPS) | 339 | 5 | local net (e.g., DCN, TSP, DTS) | 340 | 6 | UDP/NTP | 341 | 7 | UDP/TIME | 342 | 8 | eyeball-and-wristwatch | 343 | 9 | telephone modem (e.g., NIST) | 344 | 10-63 | reserved | 345 +-------+-----------------------------------------------------------+ 347 System Event Counter: This is a four-bit integer indicating the 348 number of system events occurring since the last time the System 349 Event Code changed. Upon reaching 15, subsequent events with the 350 same code are not counted. 352 System Event Code: This is a four-bit integer identifying the latest 353 system exception event, with new values overwriting previous values, 354 and coded as follows: 356 +-------+---------------------------------------------------------------+ 357 | Code | Meaning | 358 +-------+---------------------------------------------------------------+ 359 | 0 | unspecified | 360 | 1 | frequency correction (drift) file not available | 361 | 2 | frequency correction started (frequency stepped) | 362 | 3 | spike detected and ignored, starting stepout timer | 363 | 4 | frequency training started | 364 | 5 | clock synchronized | 365 | 6 | system restart | 366 | 7 | panic stop (required step greater than panic threshold) | 367 | 8 | no system peer | 368 | 9 | leap second insertion/deletion armed for end of current month | 369 | 10 | leap second disarmed | 370 | 11 | leap second inserted or deleted | 371 | 12 | clock stepped (stepout timer expired) | 372 | 13 | kernel loop discipline status changed | 373 | 14 | leapseconds table loaded from file | 374 | 15 | leapseconds table outdated, updated file needed | 375 +-------+---------------------------------------------------------------+ 377 3.2. Peer Status Word 379 A peer status word is returned in the status field of a response to a 380 read status, read variables or write variables command and appears 381 also in the list of association identifiers and status words returned 382 by a read status command with a zero association identifier. The 383 format of a peer status word is as follows: 385 0 1 386 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 387 +---------+-----+-------+-------+ 388 | Flags | Sel | Count | Code | 389 +---------+-----+-------+-------+ 391 Peer Status Flags: This is a set of five bits indicating the status 392 of the peer determined by the packet procedure, with bits assigned as 393 follows: 395 +--------+--------+--------------------------------------------------------+ 396 | Peer | | | 397 | Status | | | 398 | Flag | | | 399 | Bit | Value | Meaning | 400 +--------+--------+--------------------------------------------------------+ 401 | 0 | 0x8000 | configured (peer.config) | 402 | 1 | 0x4000 | authentication enabled (peer.authenable) | 403 | 2 | 0x2000 | authentication okay (peer.authentic) | 404 | 3 | 0x1000 | reachable (peer.reach != 0) | 405 | 4 | 0x0800 | broadcast association | 406 +--------+--------+--------------------------------------------------------+ 408 Peer Selection (Sel): This is a three-bit integer indicating the 409 status of the peer determined by the clock-selection procedure, with 410 values coded as follows: 412 +-------+-----------------------------------------------------------------+ 413 | Peer | | 414 | Sel | Meaning | 415 +-------+-----------------------------------------------------------------+ 416 | 0 | rejected | 417 | 1 | discarded by intersection algorithm | 418 | 2 | discarded by table overflow (not currently used) | 419 | 3 | discarded by the cluster algorithm | 420 | 4 | included by the combine algorithm | 421 | 5 | backup source (with more than sys.maxclock survivors) | 422 | 6 | system peer (synchronization source) | 423 | 7 | PPS (pulse per second) peer | 424 +-------+-----------------------------------------------------------------+ 426 Peer Event Counter: This is a four-bit integer indicating the number 427 of peer events that occurred since the last time the peer event code 428 changed. Upon reaching 15, subsequent events with the same code are 429 not counted. 431 Peer Event Code: This is a four-bit integer identifying the latest 432 peer exception event, with new values overwriting previous values, 433 and coded as follows: 435 +-------+--------------------------------------------------------------------+ 436 | Peer | | 437 | Event | Meaning | 438 | Code | | 439 +-------+--------------------------------------------------------------------+ 440 | 0 | unspecified | 441 | 1 | association mobilized | 442 | 2 | association demobilized | 443 | 3 | peer unreachable | 444 | 4 | peer reachable | 445 | 5 | association restarted or timed out | 446 | 6 | no reply (used only with one-shot ntpd -q, known as ntpdate mode) | 447 | 7 | peer rate limit exceeded (kiss code RATE received) | 448 | 8 | access denied (kiss code DENY received), not currently implemented | 449 | 9 | leap second insertion/deletion at month's end armed by peer vote | 450 | 10 | became system peer (sys.peer) | 451 | 11 | reference clock event (see clock status word) | 452 | 12 | authentication failed | 453 | 13 | popcorn spike suppressed by peer clock filter register | 454 | 14 | entering interleaved mode | 455 | 15 | recovered from interleave error | 456 +-------+--------------------------------------------------------------------+ 458 3.3. Clock Status Word 460 There are two ways a reference clock can be attached to a NTP service 461 host, as an dedicated device managed by the operating system and as a 462 synthetic peer managed by NTP. As in the read status command, the 463 association identifier is used to identify which one, zero for the 464 system clock and nonzero for a peer clock. Only one system clock is 465 supported by the protocol, although many peer clocks can be 466 supported. A system or peer clock status word appears in the status 467 field of the response to a read clock variables or write clock 468 variables command. This word can be considered an extension of the 469 system status word or the peer status word as appropriate. The 470 format of the clock status word is as follows: 472 0 1 473 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 474 +---------------+-------+-------+ 475 | Reserved | Count | Code | 476 +---------------+-------+-------+ 478 Reserved: An eight-bit integer that should be ignored by requesters 479 and zeroed by responders. 481 Clock Event Counter: This is a four-bit integer indicating the number 482 of clock events that occurred since the last time the clock event 483 code changed. Upon reaching 15, subsequent events with the same code 484 are not counted. 486 Clock Event Code: This is a four-bit integer indicating the current 487 clock status, with values coded as follows: 489 +--------------+----------------------------------------------------------+ 490 | Clock Status | Meaning | 491 +--------------+----------------------------------------------------------+ 492 | 0 | clock operating within nominals | 493 | 1 | reply timeout | 494 | 2 | bad reply format | 495 | 3 | hardware or software fault | 496 | 4 | propagation failure (loss of signal) | 497 | 5 | bad date format or value | 498 | 6 | bad time format or value | 499 | 7-15 | reserved | 500 +--------------+----------------------------------------------------------+ 502 3.4. Error Status Word 504 An error status word is returned in the status field of an error 505 response as the result of invalid message format or contents. Its 506 presence is indicated when the E (error) bit is set along with the 507 response (R) bit in the response. The format of the Error Status 508 Word is: 510 0 1 511 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 512 +---------------+---------------+ 513 | Error Code | Reserved | 514 +---------------+---------------+ 516 Error code: an eight-bit integer coded as follows: 518 +--------------+----------------------------------------------------------+ 519 | Error Status | Meaning | 520 +--------------+----------------------------------------------------------+ 521 | 0 | unspecified | 522 | 1 | authentication failure | 523 | 2 | invalid message length or format | 524 | 3 | invalid opcode | 525 | 4 | unknown association identifier | 526 | 5 | unknown variable name | 527 | 6 | invalid variable value | 528 | 7 | administratively prohibited | 529 | 8-255 | reserved | 530 +--------------+----------------------------------------------------------+ 532 Reserved: Responders should use zero. Requesters should ignore the 533 Reserved value to preserve the possibility of future use. 535 4. Commands 536 Commands consist of the header and optional data field shown in 537 Section 3. When present, the data field contains a list of 538 identifiers or assignments in the form 539 <>[=<>],<>[=<>],... where 540 <> is the ASCII name of a system or peer variable 541 specified in Sections 9.1 and 11.1 of RFC 5905 and <> is 542 expressed as a decimal, hexadecimal or string constant in the syntax 543 of the C programming language. Where no ambiguity exists, the "s." 544 or "p." prefixes shown in Figure 5 of Section 7.1 of RFC 5905 545 [RFC5905] can be suppressed. Whitespace (ASCII nonprinting format 546 effectors) can be added to improve readability for simple monitoring 547 programs that do not reformat the data field. Internet Protocol 548 version 4 addresses are represented as four decimal octets without 549 leading zeros, separated by dots. Internet Protocol version 6 550 addresses are represented as mandated by [RFC5952], without 551 surrounding square brackets unless a port specification is combined 552 with the address. Timestamps, including reference, originate, 553 receive and transmit values, as well as the logical clock, are 554 represented in units of seconds and fractions, preferably in 555 hexadecimal notation, while delay, offset, dispersion and distance 556 values are represented in units of milliseconds and fractions, 557 preferably in decimal notation. All other values are represented as- 558 is, preferably in decimal notation. 560 Implementations may define variables other than those listed in 561 Figures 6, 7, 16, 17, 18, 19, 27 and 29 of RFC 5905. Called 562 extramural variables, these are distinguished by the inclusion of 563 some character type other than alphanumeric or "." in the name. For 564 those commands that return a list of assignments in the response data 565 field, if the command data field is empty, it is expected that all 566 available variables defined in Figures 6, 7 and 17 of RFC 5905 will 567 be included in the response. For the read commands, if the command 568 data field is nonempty, an implementation may choose to process this 569 field to individually select which variables are to be returned. 571 Commands are interpreted as follows: 573 Read Status (1): The command data field is empty or contains a list 574 of identifiers separated by commas. The command operates in two ways 575 depending on the value of the association identifier. If this 576 identifier is nonzero, the response includes the peer identifier and 577 status word. Optionally, the response data field may contain other 578 information, such as described in the Read Variables command. If the 579 association identifier is zero, the response includes the system 580 identifier (0) and status word, while the data field contains a list 581 of binary-coded pairs <> <>, one 582 for each currently defined association. 584 Read Variables (2): The command data field is empty or contains a 585 list of identifiers separated by commas. If the association 586 identifier is nonzero, the response includes the requested peer 587 identifier and status word, while the data field contains a list of 588 peer variables and values as described above. If the association 589 identifier is zero, the data field contains a list of system 590 variables and values. If a peer has been selected as the 591 synchronization source, the response includes the peer identifier and 592 status word; otherwise, the response includes the system identifier 593 (0) and status word. 595 Write Variables (3): The command data field contains a list of 596 assignments as described above. The variables are updated as 597 indicated. The response is as described for the Read Variables 598 command. 600 Read Clock Variables (4): The command data field is empty or contains 601 a list of identifiers separated by commas. The association 602 identifier selects the system clock variables or peer clock variables 603 in the same way as in the Read Variables command. The response 604 includes the requested clock identifier and status word and the data 605 field contains a list of clock variables and values, including the 606 last timecode message received from the clock. 608 Write Clock Variables (5): The command data field contains a list of 609 assignments as described above. The clock variables are updated as 610 indicated. The response is as described for the Read Clock Variables 611 command. The reference implementation daemon requires authentication 612 for this command. 614 Set Trap Address/Port (6): The command association identifier, status 615 and data fields are ignored. The address and port number for 616 subsequent trap messages are taken from the source address and port 617 of the control message itself. The initial trap counter for trap 618 response messages is taken from the sequence field of the command. 619 The response association identifier, status and data fields are not 620 significant. Implementations should include sanity timeouts which 621 prevent trap transmissions if the monitoring program does not renew 622 this information after a lengthy interval. 624 Trap Response (7): This command differs from the others described 625 here, which are initiated by a management agent (such as ntpq) and 626 responded to by a NTP daemon. Trap Response is sent by a NTP daemon 627 to any registered trap receivers when a system, peer or clock 628 exception event occurs. The opcode field is 7 and the R bit is set. 629 The trap counter is incremented by one for each trap sent and the 630 sequence field set to that value. The trap message is sent using the 631 IP address and port fields established by the set trap address/port 632 command. If a system trap the association identifier field is set to 633 zero and the status field contains the system status word. If a peer 634 trap the association identifier field is set to that peer and the 635 status field contains the peer status word. Optional ASCII-coded 636 information can be included in the data field. 638 Configure (8): The command data is parsed and applied as if supplied 639 in the daemon configuration file. The reference implementation 640 daemon requires authentication for this command. 642 Save Configuration (9): Write a snapshot of the current configuration 643 to the file name supplied as the command data. The reference 644 implementation daemon requires authentication for this command. 645 Further, the command is refused unless a directory in which to store 646 the resulting files has been explicitly configured by the operator. 648 Read MRU (10): Retrieves records of recently seen remote addresses 649 and associated statistics. Command data consists of name=value pairs 650 controlling the selection of records, as well as a requestor-specific 651 nonce previously retrieved using this command or opcode 12, Request 652 Nonce. The response consists of name=value pairs where some names 653 can appear multiple times using a dot followed by a zero-based index 654 to distinguish them, and to associate elements of the same record 655 with the same index. A new nonce is provided with each successful 656 response. 658 Read ordered list (11): Retrieves an ordered list. If the command 659 data is empty or the seven characters "ifstats" the associated 660 statistics, status and counters for each local address are returned. 661 If the command data is the characters "addr_restrictions" then the 662 set of IPv4 remote address restrictions followed by the set of IPv6 663 remote address restrictions (access control lists) are returned. 664 Other command data returns error code 5 (unknown variable name). 665 Similar to Read MRU, response information uses zero-based indexes as 666 part of the variable name preceding the equals sign and value, where 667 each index relates information for a single address or network. This 668 opcode requires authentication. 670 Request Nonce (12): Retrieves a 96-bit nonce specific to the 671 requesting remote address, which is valid for a limited period. 672 Command data is not used in the request. The nonce consists of a 673 64-bit NTP timestamp and 32 bits of hash derived from that timestamp, 674 the remote address, and salt known only to the server which varies 675 between daemon runs. The reference implementation honors nonces 676 which were issued less than 16 seconds prior. Regurgitation of the 677 nonce by a managment agent demonstrates to the server that the agent 678 can receive datagrams sent to the source address of the request, 679 making source address "spoofing" more difficult in a similar way as 680 TCP's three-way handshake. 682 Unset Trap (31): Removes the requesting remote address and port from 683 the list of trap receivers. Command data is not used in the request. 684 If the address and port are not in the list of trap receivers, the 685 error code is 4, bad association. 687 5. IANA Considerations 689 Editor's Note: To be reviewed by the working group prior to 690 completion. 692 6. Security Considerations 694 Editor's Note: To be supplied by the working group prior to 695 completion. 697 7. Acknowledgements 699 8. References 701 8.1. Normative References 703 [RFC5905] Mills, D., Martin, J., Burbank, J. and W. Kasch, "Network 704 Time Protocol Version 4: Protocol and Algorithms 705 Specification", RFC 5905, June 2010. 707 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 708 Address Text Representation", RFC 5952, August 2010. 710 8.2. Informative References 712 [RFC5906] Haberman, B. and D. Mills, "Network Time Protocol Version 713 4: Autokey Specification", RFC 5906, June 2010. 715 [RFC5907] Gerstung, H., Elliott, C. and B. Haberman, "Definitions of 716 Managed Objects for Network Time Protocol Version 4 717 (NTPv4)", RFC 5907, June 2010. 719 [RFC5908] Gayraud, R. and B. Lourdelet, "Network Time Protocol (NTP) 720 Server Option for DHCPv6", RFC 5908, June 2010. 722 Authors' Addresses 724 Dr. David L. Mills 725 University of Delaware 726 Newark, Delaware 727 US 729 Email: mills@udel.edu 731 Karen O'Donoghue, editor 732 Internet Society 733 King George, Virginia 734 US 736 Email: odonoghue@isoc.org 738 David L. Hart 739 Redmond, Washington 740 US 742 Email: hart@ntp.org 743 Harlan M. Stenn 744 Network Time Foundation, Inc. 745 Talent, Oregon 746 US 748 Email: stenn@ntp.org 750 Philip F. Chimento, editor 751 Johns Hopkins University/APL 752 11100 Johns Hopkins Road 753 Laurel, Maryland 20723 754 US 756 Email: Philip.Chimento@jhuapl.edu