[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