[Git][NTPsec/ntpsec][master] 3 commits: A good start on Mode 6 protocol documentation.
Eric S. Raymond
gitlab at mg.gitlab.com
Sun Oct 30 20:09:16 UTC 2016
Eric S. Raymond pushed to branch master at NTPsec / ntpsec
Commits:
ac158f38 by Eric S. Raymond at 2016-10-30T16:08:12-04:00
A good start on Mode 6 protocol documentation.
Also, in pyntpq, add a command alias mentioned in the doctmentation.
- - - - -
3ebb4372 by Eric S. Raymond at 2016-10-30T16:08:12-04:00
Document more Mode 6 opcodes.
- - - - -
7ffa6144 by Eric S. Raymond at 2016-10-30T16:08:12-04:00
In pyntpq, upper-end implementation of :config and config-from-file.
- - - - -
5 changed files:
- + docs/mode6.txt
- docs/ntpq.txt
- docs/ntpspeak.txt
- + docs/pic/which-way-is.up.jpg
- ntpq/pyntpq
Changes:
=====================================
docs/mode6.txt
=====================================
--- /dev/null
+++ b/docs/mode6.txt
@@ -0,0 +1,226 @@
+= Mode 6 Protocol =
+
+[cols="10%,90%",frame="none",grid="none",style="verse"]
+|==============================
+|image:pic/which-way-is.up.jpg[]|
+http://www.eecis.udel.edu/%7emills/pictures.html[from 'Pogo', Walt Kelly]
+
+Keeping control of the situation.
+
+|==============================
+
+== Related Links ==
+
+include::includes/hand.txt[]
+
+== Table of Contents ==
+
+* link:#intro[Introduction]
+* link:#packet[Mode 6 packet structure]
+* link:#varlists[Variable-Value Lists]
+* link:#opcodes[Mode 6 Opcodes]
+
+'''''
+
+[[intro]]
+== Introduction ==
+
+This page describes the Mode 6 protocol used to get status information
+from a running ntpd and configure some of its behaviors on the fly.
+The protocol is normally used by the 'ntpq' program distributed with
+the suite.
+
+[[packet]]
+== Mode 6 packet structure ==
+
+The protocol uses UDP packets transmitted and received over port 123.
+They use the same structure (header, plus extension, plus optional
+MAC) as time synchronization messages, but the semantics of the header
+fields are different. They are distinguished from time
+synchronization packets by their Mode field, which has the value 6
+(0110).
+
+.Mode 6 packet structure
+-------------------------------------------------------------------------
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |LI | VN |Mode |R|E|M| Opcode | Sequence |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Status | Association ID |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Offset | Count |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | |
+ . .
+ . Payload (variable length) .
+ . .
+ | |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Key Identifier |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | |
+ | dgst (128) |
+ | |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-------------------------------------------------------------------------
+
+In mode 6 packets, the leap indicator (LI) is ignored and normally
+zero. The version (VN) is the protocol major version. Mode is 6.
+The following field interpretations are specific to mode 6:
+
+|=====================================================================
+| Response bit | 1 in a response, 0 in a request
+| Error bit | 1 in an error response, 0 otherwise
+| More | Payload is continued in next packet
+| Sequence | Sequence number for multi-packet reassembly
+| Status | System status word
+| Association ID | Association ID of peer, or 0 for the ntpd host
+| Offset | Byte offset of this fragment in the response
+| Count | Byte count of payload
+|=====================================================================
+
+Requests to ntpd are single UDP packets; ntpd expects them to be
+padded to a 4-octet boundary. Responses may be multiple UDP packets;
+they may arrive out of order, and the client is responsible for
+reassembling the payloads.
+
+Some requests require authentication. This is accomplished by
+shipping a trailer consisting of a key index and an MD5 digest
+generated with that index.
+
+[[varlists]]
+== Variable-Value Lists ==
+
+Several requests and responses use a common textual payload format
+consisting of a comma-separated list of items. An item may be
+textual (ASCII) variable name, or a textual variable name followed by
+an equals sign followed by a textual value. Following any comma
+the format may insert a newline; these are not significant to the
+meaning of the payload, but are placed so that if the payload is
+dumped to an 80-character terminal window the lines will be folded
+in a way conveniwnt for visibility.
+
+Values may be decimal numeric literals, hex numeric literals led with
+"0x", binary literals consisting of the digits 0 and 1, or string
+literals enclosed in double quotes. String literals never contain
+newlines or other control characters. One quirk of the format is that
+a bare variable name without a following "=" may be interpreted in
+context as an instruction to set a string-valued variable to the
+empty string.
+
+Textual responses may end with padding NULs; clients should ignore
+these.
+
+[[opcodes]]
+== Mode 6 Opcodes ==
+
+Request-response types are distinguished by operation codes. The
+table below lists them all. The "Auth?" column tells whether a
+request requires authentication from the client.
+
+[options="header"]
+|=====================================================================
+|Name |Value | Auth? | Use
+|CTL_OP_READSTAT | 1 | No | read system or peer status
+|CTL_OP_READVAR | 2 | No | read system or peer variables
+|CTL_OP_WRITEVAR | 3 | Yes | write variables
+|CTL_OP_READCLOCK | 4 | No | read clock variables
+|CTL_OP_WRITECLOCK | 5 | - | write clock variables
+|CTL_OP_SETTRAP | 6 | - | set trap address (obsolete, unused)
+|CTL_OP_ASYNCMSG | 7 | - | asynchronous message (unused)
+|CTL_OP_CONFIGURE | 8 | Yes | runtime configuration
+|CTL_OP_READ_MRU | 10 | Yes | retrieve MRU (mrulist)
+|CTL_OP_READ_ORDLIST_A | 11 | Yes | ordered list req. auth.
+|CTL_OP_REQ_NONCE | 12 | Yes | request a client nonce
+|CTL_OP_UNSETTRAP | 31 | - | unset trap (obsolete, unused)
+|=====================================================================
+
+The CTRL_OP_TRAP and CTL_OP_UNSETTRAP opcodes relate to an obsolete
+notification facility supported in some older versions of the
+software. CTL_OP_WRITECLOCK is unimplemented and will throw a
+permission error. CTL_OP_ASYNCMSG is reserved for expansion. The
+remaining opcodes are as follows:
+
+=== CTL_OP_READSTAT ===
+
+This requests ntpd to ship up a list of association IDs and status
+words for all peers currently associated with the ntpd instance. It
+does not require authentication.
+
+The normal use case for this request is to discover the current list
+of associations preparatory to querying peer variables for each
+association.
+
+There is no request payload. The response payload is not textual. It
+consists of a sequence of pairs, each consisting of 16-bit association
+ID followed by 16-bit status word, both unsigned in network
+(big-endian) byte order. There is no padding in the response. The
+number of IDs is implicitly given by the payload length in octets,
+divided by 4.
+
+Interpretation of the peer status word is described
+link:decode.html#peer[here].
+
+=== CTL_OP_READVAR ===
+
+This requests ntpd to ship up a list of peer variable settings for an
+association specified by ID, or system variables if the ID is zero. It
+does not require authentication.
+
+The request payload may be empty or a textual variable list of
+variables to be reported in the response. An empty request payload
+calls for a report on all known variables.
+
+The response payload is a textual varlist.
+
+=== CTL_OP_WRITEVAR ===
+
+Some system variable are defined as being settable from a mode 6
+client. This request provides a general way to do that. It requires
+authentication.
+
+The request payload is a textual list of variable settings. Any
+variable name that is unknown or not settable immediately terminates
+processing of the payload. This request is only valid with an
+association ID of 0. There is no response payload.
+
+No system variables are currently settable. This may change in a
+future release.
+
+=== CTL_OP_READCLOCK ===
+
+This requests ntpd to ship up a list of peer variable settings for a
+reference clock association specified by ID. It does not require
+authentication.
+
+The request payload may be empty or a textual variable list of
+variables to be reported in the response. An empty request payload
+calls for a report on all known variables.
+
+The response payload is a textual varlist.
+
+'''''
+
+=== CTL_OP_CONFIGURE ===
+
+This request is used to change the configuration on ntpd without
+restarting the daemon. It requires authentication.
+
+The request payload should be a line of text in the syntax of the
+ntp.conf configuration file. The response payload will be either
+an error message or the string "Config Succeeded".
+
+=== CTL_OP_READ_MRU ===
+
+To be documented.
+
+=== CTL_OP_READ_ORDLIST_A ===
+
+To be documented.
+
+=== CTL_OP_REQ_NONCE ===
+
+To be documented.
+
+include::includes/footer.txt[]
=====================================
docs/ntpq.txt
=====================================
--- a/docs/ntpq.txt
+++ b/docs/ntpq.txt
@@ -17,6 +17,11 @@ include::includes/manual.txt[]
include::includes/ntpq-body.txt[]
+== Mode 6 Protocol ==
+
+The Mode 6 protocol used by ntpq to communicate with ntpd
+is described link:mode6.html[here].
+
'''''
include::includes/footer.txt[]
=====================================
docs/ntpspeak.txt
=====================================
--- a/docs/ntpspeak.txt
+++ b/docs/ntpspeak.txt
@@ -28,6 +28,11 @@ association::
for discovering association partners, creating and maintaining
associations, and preventing attackers from forming associations.
+[[association ID]]
+association ID::
+ A numeric identifier designating an association, normally internal
+ to ntpd but exposed in <<mode 6>> packets.
+
[[atom]]
atom::
Old name for the PPS driver. Origin lost in the mists of history,
@@ -146,6 +151,13 @@ Mills-speak::
http://lists.ntp.org/pipermail/questions/2007-December/016592.html[The
NTP dictionary], though not all those terms are still in use.
+[[mode 6]]
+mode 6::
+ Mode 6 is a control protocol used to get various kinds of
+ status information from a running ntpd and configure it on
+ the fly. So called from the value 6 (0110) in the packet mode
+ field. It is described in detail mode6.html[here].
+
[[NIST]]
NIST::
http://www.nist.gov/[National Institute of Standards and
=====================================
docs/pic/which-way-is.up.jpg
=====================================
Binary files /dev/null and b/docs/pic/which-way-is.up.jpg differ
=====================================
ntpq/pyntpq
=====================================
--- a/ntpq/pyntpq
+++ b/ntpq/pyntpq
@@ -5,9 +5,6 @@
# This is a direct translation of the ntpq C code, initially written to work as
# much like it as possible. Eventually it will replace the C version.
#
-# Due to a limitation of the Python Cmd class, the ":config" and
-# "config-from-file" commands lose their colons/hyphens.
-#
# SPDX-License-Identifier: BSD-2-clause
from __future__ import print_function, division
@@ -154,6 +151,13 @@ class Ntpq(cmd.Cmd):
"Called when an empty line is entered in response to the prompt."
pass
+ def precmd(self, line):
+ if line.startswith(":config"):
+ line = line[1:]
+ elif line.startswith("config-from-file"):
+ line = line.replace("config-from-file ", "config_from_file")
+ return line
+
def say(self, msg):
sys.stdout.write(msg)
@@ -766,6 +770,7 @@ usage: keytype [ digest-name ]
"print list of association IDs and statuses for the server's peers"
if self.__dogetassoc():
self.__printassoc(showall=False)
+ do_as = do_associations # Documentation mentions this alias
def help_associations(self):
self.say("""\
@@ -1126,7 +1131,7 @@ usage: lopeers
def do_config(self, line):
"send a remote configuration command to ntpd"
- pass
+ self.say(self.session.config(line) + "\n")
def help_config(self):
self.say("""\
@@ -1136,7 +1141,11 @@ usage: config <configuration command line>
def do_config_from_file(self, line):
"configure ntpd using the configuration filename"
- pass
+ try:
+ with open(line) as rfp:
+ self.say(self.session.config(rfp.read()))
+ except IOError:
+ self.warn("Could not read %s\n" % line)
def help_config_from_file(self):
self.say("""\
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/80767cb56a3fec69269dd8f8fa93a59ce415bd59...7ffa6144e7b23acda75bf49636bd5e75dd7c6802
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ntpsec.org/pipermail/vc/attachments/20161030/3070428a/attachment.html>
More information about the vc
mailing list