1= Mode 6 Protocol 2include::include-html.ad[] 3 4[cols="10%,90%",frame="none",grid="none",style="verse"] 5|============================== 6|image:pic/which-way-is.up.jpg[]| 7{millshome}pictures.html[from 'Pogo', Walt Kelly] 8 9Keeping control of the situation. 10 11|============================== 12 13== Related Links 14 15include::includes/hand.adoc[] 16 17== Table of Contents 18 19* link:#intro[Introduction] 20* link:#packet[Mode 6 packet structure] 21* link:#varlists[Variable-Value Lists] 22* link:#requests[Mode 6 Requests] 23* link:#authentication[Authentication] 24 25''''' 26 27[[intro]] 28== Introduction 29 30This page describes the Mode 6 protocol used to get status information 31from a running ntpd and configure some of its behaviors on the fly. 32The protocol is normally used by the 'ntpq' and 'ntpmon' program 33distributed with the suite. It is fully documented here so that other 34clients can be written. 35 36(Note that the most efficient way to write a new client is to use 37the Python Mode 6 libraries included in the distribution. Both 'ntpq' 38and 'ntpmon' use these.) 39 40[[packet]] 41== Mode 6 packet structure 42 43The protocol uses UDP packets transmitted and received over port 123. 44They use the same structure (header, plus extension, plus optional 45MAC) as time synchronization messages, but the layout and semantics of 46the header fields are different. They are distinguished from time 47synchronization packets by their Mode field, which has the value 6 48(110). 49 50.Mode 6 packet structure 51------------------------------------------------------------------------- 52 0 1 2 3 53 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 54 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 55 |LI | VN |Mode |R|E|M| Opcode | Sequence | 56 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 57 | Status | Association ID | 58 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 59 | Offset | Count | 60 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 61 | | 62 . . 63 . Payload (variable length) . 64 . . 65 | | 66 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 67 | Key Identifier | 68 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 69 | | 70 | MAC (128) | 71 | | 72 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 73------------------------------------------------------------------------- 74 75In mode 6 packets, the leap indicator (LI) is ignored and normally 76zero. The version (VN) is the NTP protocol major version, currently 774. Mode is 6. The following field interpretations are specific to 78mode 6: 79 80|===================================================================== 81| Response bit | 1 in a response, 0 in a request 82| Error bit | 1 in an error response, 0 otherwise 83| More | 1 if payload is continued in next packet, 0 otherwise 84| Sequence | Sequence number for multi-packet reassembly 85| Status | System status word 86| Association ID | Association ID of peer, or 0 for the ntpd host 87| Offset | Octet offset of this fragment in the response 88| Count | Octet count of fragment payload 89|===================================================================== 90 91Requests to ntpd are single UDP packets; ntpd expects them to be 92padded to a 4-octet boundary. Responses may be multiple UDP packets; 93they may arrive out of order, and the client is responsible for 94reassembling the payloads. 95 96All multibyte numeric fields are interpreted as big-endian 972's-complement integers. 98 99The maximum length of the Mode 6 payload is constrained by the 100minimum-maximum UDP payload size of 576. As of late 2018 there is no 101language in the NTP RFCs pinning it down. A draft RFC on Mode 6 says 102it's 500 octets, which is far in excess of any plausible request or 103response size in the actual protocol. 104 105[[varlists]] 106== Variable-Value Lists 107 108Several requests and responses (in fact, all but one) use a common 109textual payload format consisting of a comma-separated list of items. 110An item may be a textual (ASCII) variable name, or a textual variable 111name followed by an equals sign followed by a textual value. Following 112any comma the format may insert a newline; these are not significant 113to the meaning of the payload, but are placed so that if the payload 114is dumped to an 80 character terminal window the lines will be folded 115in a way convenient for visibility. 116 117Values may be decimal numeric literals, decimal float literals, hex 118numeric literals led with "0x", binary literals consisting of exactly 119two of digits 0 and 1, NTP date stamps, or string literals enclosed in 120double quotes. 121 122NTP date stamps are represented by hexadecimal fixed-point literals 123led with "0x", distinguished from hexadecimal integers by the embedded 124radix point ("."). They represent seconds (and fractional seconds) 125since the epoch of the current NTP era. NTP era zero began at 00:00 126of January 1st 1900. 127 128String literals never contain newlines or other control 129characters. One quirk of the format is that a bare variable name 130without a following "=" may be interpreted in context as an 131instruction to set a string-valued variable to the empty string. 132 133Textual responses may end with padding NULs; clients should ignore 134these. 135 136In RFC 5234 ABNF: 137 138----------------------------------------------------------- 139varlist = item [itemtail] LF *%x00 140 141itemtail = "," [1LF] item [itemtail] 142 143item = name / name "=" value 144 145value = 1*DIGIT / 1*DIGIT "." 1*DIGIT / "0x" 1*HEXDIG / 2BIT / quoted-string 146 147quoted-string = %x22 *(%21 | %x23-7E) %x22 148----------------------------------------------------------- 149 150[[requests]] 151== Mode 6 Requests 152 153Request-response types are distinguished by operation codes. The 154table below lists them all. The "Auth?" column tells whether a 155request requires authentication from the client. 156 157[options="header"] 158|===================================================================== 159|Name |Value | Auth? | Use 160|CTL_OP_READSTAT | 1 | No | read system or peer status 161|CTL_OP_READVAR | 2 | No | read system or peer variables 162|CTL_OP_WRITEVAR | 3 | Yes | write variables 163|CTL_OP_READCLOCK | 4 | No | read clock variables 164|CTL_OP_WRITECLOCK | 5 | - | write clock variables 165|CTL_OP_SETTRAP | 6 | - | set trap address (obsolete, unused) 166|CTL_OP_ASYNCMSG | 7 | - | asynchronous message (unused) 167|CTL_OP_CONFIGURE | 8 | Yes | runtime configuration 168|CTL_OP_READ_MRU | 10 | No | retrieve MRU (mrulist) 169|CTL_OP_READ_ORDLIST_A | 11 | Yes | ordered list req. auth. 170|CTL_OP_REQ_NONCE | 12 | No | request a client nonce 171|CTL_OP_UNSETTRAP | 31 | - | unset trap (obsolete, unused) 172|===================================================================== 173 174The CTL_OP_SETTRAP and CTL_OP_UNSETTRAP opcodes relate to an obsolete 175notification facility supported in some older versions of the 176software. CTL_OP_WRITECLOCK is unimplemented and will throw a 177permission error. CTL_OP_ASYNCMSG is reserved for expansion. The 178remaining opcodes are as follows: 179 180=== CTL_OP_READSTAT 181 182This requests ntpd to ship up a list of association IDs and status 183words for all peers currently associated with the ntpd instance. It 184does not require authentication. 185 186The normal use case for this request is to discover the current list 187of associations preparatory to querying peer variables for each 188association. 189 190There is no request payload. The response payload is not textual. It 191consists of a sequence of pairs, each consisting of 16-bit association 192ID followed by 16-bit status word, both unsigned in network 193(big-endian) byte order. There is no padding in the response. The 194number of IDs is implicitly given by the payload length in octets, 195divided by 4. 196 197Interpretation of the peer status word is described 198link:decode.html#peer[here]. 199 200=== CTL_OP_READVAR 201 202This requests ntpd to ship up a list of peer variable settings for an 203association specified by ID, or system variables if the ID is zero. It 204does not require authentication. 205 206The request payload may be empty or a textual variable list of 207variables to be reported in the response. An empty request payload 208calls for a report on all known variables. 209 210The response payload is a textual varlist. 211 212=== CTL_OP_WRITEVAR 213 214Some system variable are defined as being settable from a mode 6 215client. This request provides a general way to do that. It requires 216authentication. 217 218The request payload is a textual list of variable settings. Any 219variable name that is unknown or not settable immediately terminates 220processing of the payload. This request is only valid with an 221association ID of 0. There is no response payload. 222 223No system variables are currently settable. This may change in a 224future release. 225 226=== CTL_OP_READCLOCK 227 228This requests ntpd to ship up a list of peer variable settings for a 229reference clock association specified by ID. It does not require 230authentication. 231 232The request payload may be empty or a textual variable list of 233variables to be reported in the response. An empty request payload 234calls for a report on all known variables. 235 236The response payload is a textual varlist. 237 238=== CTL_OP_CONFIGURE 239 240This request is used to change the configuration of ntpd without 241restarting the daemon. It requires authentication. 242 243The request payload should be a line of text in the syntax of the 244ntp.conf configuration file. The response payload will begin with either 245an error message or the string "Config Succeeded", followed by a NUL. 246 247Note: Due to an implementation error, the response packet may and 248typically will contain trailing garbage. Implementations should 249expect this and truncate it at the first NUL. 250 251=== CTL_OP_READ_MRU 252 253This request is used to retrieve information about recent traffic 254between ntpd and its clients and peers; in NTP-speak this traffic summary is 255called the "MRU list", where MRU stands for "most recently used". It does 256not require authentication. 257 258//Keep this in sync with the big comment in ntpd/ntp_control.c, 259//from which it is derived. 260 261A finite and variable number of entries are retrieved per request, to 262avoid having responses with such large numbers of packets that socket 263buffers are overflowed and packets lost. The entries are retrieved 264oldest-first, taking into account that the MRU list will be changing 265between each request. We can expect to see duplicate entries for 266addresses updated in the MRU list during the fetch operation. In the 267end, the client can assemble a close approximation of the MRU list at 268the point in time the last response was sent by ntpd. The only 269difference is it may be longer, containing some number of oldest 270entries which have since been reclaimed. If necessary, the protocol 271could be extended to zap those from the client snapshot at the end, 272but so far that doesn't seem useful. 273 274To accommodate the changing MRU list, the starting point for requests 275after the first request is supplied as a series of last seen 276timestamps and associated addresses, the newest ones the client has 277received. As long as at least one of those entries hasn't been 278bumped to the head of the MRU list, ntpd can pick up at that point. 279Otherwise, the request is failed and it is up to ntpq to back up and 280provide the next newest entry's timestamps and addresses, conceivably 281backing up all the way to the starting point. 282 283The request payload is a textual varlist that must include 284some of the following variables and may include others: 285 286nonce:: Regurgitated nonce retrieved by the client 287 previously using CTL_OP_REQ_NONCE, demonstrating 288 ability to receive traffic sent to its address. 289 290frags:: Limit on datagrams (fragments) in response. Used 291 by newer ntpq versions instead of limit= when 292 retrieving multiple entries. 293 294limit:: Limit on MRU entries returned. One of frags= or limit= 295 must be provided. limit=1 is a special case: Instead of 296 fetching beginning with the supplied starting point's 297 newer neighbor, fetch the supplied entry, and in that 298 case the #.last timestamp can be zero. This enables 299 fetching a single entry by IP address. When limit is 300 not one and frags= is provided, the fragment limit 301 controls. 302 303mincount:: (decimal) Return entries with packet count >= mincount. 304 305mindrop:: (decimal) Return entries with drop count >= mindrop. 306 307minscore:: (float) Return entries with score >= minscore. 308 309maxlstint:: (decimal seconds) Return entries with lstint <= maxlstint. 310 (lstint is now-time of most recent packet) 311 312minlstint:: (decimal seconds) Return entries with lstint >= minlstint. 313 (lstint is now-time of most recent packet) 314 315laddr:: Return entries associated with the server's IP 316 address given. No port specification is needed, 317 and any supplied is ignored. 318 319recent:: Set the reporting start point to retrieve roughly 320 a specified number of most recent entries 321 'Roughly' because the logic cannot anticipate 322 update volume. Use this to volume-limit the 323 response when you are monitoring something like 324 a pool server with a very long MRU list. 325 326resall:: 0x-prefixed hex restrict bits, which must all be 327 lit for an MRU entry to be included. 328 Has precedence over any resany=. 329 330resany:: 0x-prefixed hex restrict bits, at least one of 331 which must be list for an MRU entry to be 332 included. 333 334last.0:: 0x-prefixed hex l_fp timestamp of newest entry 335 which client previously received. 336 337addr.0:: text of newest entry's IP address and port, 338 IPv6 addresses in bracketed form: [::]:123 339 340last.1:: timestamp of 2nd newest entry client has. 341 342addr.1:: address of 2nd newest entry. 343 344More entries may follow; ntpq provides as many last/addr pairs as will 345fit in a single request packet, except for the first request in a MRU 346fetch operation. 347 348The response begins with a new nonce value to be used for any 349followup request. Following the nonce is the next newer entry than 350referred to by last.0 and addr.0, if the "0" entry has not been 351bumped to the front. If it has, the first entry returned will be the 352next entry newer than referred to by last.1 and addr.1, and so on. 353If none of the referenced entries remain unchanged, the request fails 354and ntpq backs up to the next earlier set of entries to resync. 355 356Except for the first response, each response begins with confirmation 357of the entry that precedes the first additional entry provided: 358 359last.older:: hex l_fp timestamp matching one of the input 360 .last timestamps, which entry now precedes the 361 response 0. entry in the MRU list. 362 363addr.older:: text of address corresponding to older.last. 364 365And in any case, a successful response contains sets of values 366comprising entries, with the oldest numbered 0 and incrementing from 367there: 368 369addr.#:: text of IPv4 or IPv6 address and port 370 371last.#:: hex l_fp timestamp of last receipt 372 373first.#:: hex l_fp timestamp of first receipt 374 375ct.#:: count of packets received 376 377mv.#:: mode and version 378 379rs.#:: restriction mask (RES_* bits) 380 381The client should accept the values in any order, and ignore .# 382values which it does not understand, to allow a smooth path to 383future changes without requiring a new opcode. To ensure this, 384ntpd occasionally issues a randomly-generated tag=value pair. All 385such noise tags are three letters long. 386 387Clients can rely on all *.0 values preceding any *.1 values, that is 388all values for a given index number are together in the response. 389 390The end of the response list is noted with one or two tag=value 391pairs. Unconditionally: 392 393now:: 0x-prefixed l_fp timestamp at the server marking 394 the end of the operation. 395 396If any entries were returned, now= is followed by: 397 398last.newest:: hex l_fp identical to last.# of the prior entry. 399 400Portions of the response side of the protocol (specifically the 401last.older, addr.older, and last.newest attributes) can be ignored by a 402client that is willing to accumulate an entire set of MRU list 403fragments and then perform stale-record elimination of its own before 404displaying or passing on the report (that is, as opposed to 405incremental display with an attempt to suppress stale records on the 406fly). 407 408=== CTL_OP_READ_ORDLIST_A 409 410This request is used for two purposes: to retrieve restriction lists 411and to retrieve interface statistics. For the former use, the request 412payload should be the string "addr_restrictions"; for the latter case, 413the request payload should be "ifstats" or empty. Both uses 414require authentication. The response payload is, in both cases, a 415textual varlist. 416 417A response payload consists of a list of attribute stanzas. Each 418stanza consists of the attributes with tags of the form "name.#', with 419# being replaced by a zero-origin integer literal that is the index of 420the stanza. 421 422Attributes within each stanza are deliberately issued in a random 423order, and ntpd occasionally issues an attribute with a 424randomly-generated name and value. This is an attempt to prevent Mode 4256 clients from making brittle assumptions about the inventory of 426attributes and their transmission order. 427 428Clients can rely on all *.0 values preceding any *.1 values, that is 429all values for a given index number are together in the response. 430 431In a reslist stanza, elicited by "addr_restrictions", the elements are 432as follows: 433 434addr.#:: Address to which the restriction applies. May be IPV4 or 435 IPV6. Has no port suffix 436 437flags.#:: Space-separated list of flag names applying to the address. 438 These flag names are the same as those used in the 439 "restrict" directive of the configuration syntax. 440 441hits.#:: The number of times this rule has been matched. Not updated 442 for default rules. 443 444mask.#:: Subnet mask qualifying the address to express a range. 445 446In an ifstats stanza, elicited by "ifstats" or an empty string, 447attributes are as follows: 448 449addr.#:: Address of the interface. May be IPV4 or 450 IPV6. Has a port suffix. May be a wildcard; extreme cases 451 are 0.0.0.0 and [::]. 452 453bcast.#:: Either a broadcast address associated with the interface or empty. 454 455en.#:: Integer literal. 1 if packets on this interface are processed, 0 456 if they are to be ignored. 457 458flags.#:: A hex literal that is a mask of flag bits on. 459 Flag mask values are described in a following table. 460 461name.#:: The interface name, such as would occur in an ifconfig listing. 462 463pc.#:: Count of peers using this interface. 464 465rx.#:: Packet reception count. 466 467tl.#:: Last time-to-live specified on a send. 468 469tx.#:: Packet transmission count. 470 471txerr.#:: Packet transmission error count. 472 473up.#:: Uptime in seconds. 474 475.Interface flag bits in the flags.# attribute 476|========================================================================== 477|INT_UP | 0x001 | Interface is up 478|INT_PPP | 0x002 | Point-to-point interface 479|INT_LOOPBACK | 0x004 | the loopback interface 480|INT_BROADCAST | 0x008 | can broadcast out this interface 481|INT_MULTICAST | 0x010 | can multicast out this interface (not used) 482|INT_BCASTOPEN | 0x020 | broadcast receive socket is open 483|INT_MCASTOPEN | 0x040 | multicasting enabled (not used) 484|INT_WILDCARD | 0x080 | wildcard interface - usually skipped 485|INT_MCASTIF | 0x100 | bound directly to MCAST address 486|INT_PRIVACY | 0x200 | RFC 4941 IPv6 privacy address 487|INT_BCASTXMIT | 0x400 | socket setup to allow broadcasts 488|========================================================================== 489 490=== CTL_OP_REQ_NONCE 491 492This request is used to initialize an MRU-list conversation. It 493informs ntpd that the Mode 6 client is ready to receive. It does 494not require authentication. 495 496The request retrieves a nonce specific to this client, which will be 497played back to ntpd to demonstrate that the client is capable of 498receiving responses at the source IP address that requested the nonce, 499and is thereby unlikely to be forging the source address. This check 500prevents CTL_OP_READ_MRU from being used for flooding attacks. 501 502The request has no payload. The response will be a textual varlist 503containing one string-valued variable, "nonce". The value need not by 504interpreted by the client, only replayed as part of a following MRU-list 505request. 506 507Each nonce becomes invalid 16 seconds after the request for it was 508received by ntpd. While the issue time is encoded in the nonce, it 509is safer practice not to rely on the nonce format but instead to track 510the last nonce transmission time in your client and re-request based 511on that. 512 513[[auth]] 514== Authentication 515 516Authenticated requests require a MAC (message authentication code) 517trailer following the payload data, if any. Such requests must be 518padded to an 8-octet boundary, with those bytes not included in the 519header count field. 520 521The contents of the MAC trailer consists of: 522 5231. The 32-bit identifier of the signing key in network byte order. 524 5252a. In digest mode, a cryptographic hash of the following octet spans, 526in order. First, the password entered to use the signing key, then the 527request header fields, then the payload. 528 5292b. In CMAC mode, a cryptographic hash of the packet header and 530payload with the crypto algorithim using the key. 531 532The cryptographic hash is 16 octets for MD5 ir AES-CMAC and AES and 20 533octets for SHA-1. Longer digests are truncated. 534 535The key length for AES is 16 bytes. Longer keys are truncated. Shorter 536keys are padded with 0s. MD5 and SHA-1 can use any key length. 537 538== Compatibility Notes 539 540The "recent" parameter of CTL_OP_READ_MRU is not supported in versions 541prior to NTPsec 0.9.6. 542 543Export of the count of control requests (ss_numctlreq) is new in NTPsec. 544 545''''' 546 547include::includes/footer.adoc[] 548