From a9407509603d273b0637f1303a36217e999ffdf3 Mon Sep 17 00:00:00 2001
From: Guido Trotter <ultrotter@google.com>
Date: Fri, 7 Aug 2009 11:05:04 +0100
Subject: [PATCH] design-2.1: detail confd wire protocol
Until now it was being kept too vague, so here we give some real
examples of how things are going to be.
Signed-off-by: Guido Trotter <ultrotter@google.com>
Reviewed-by: Michael Hanselmann <hansmi@google.com>
---
doc/design-2.1.rst | 65 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 65 insertions(+)
diff --git a/doc/design-2.1.rst b/doc/design-2.1.rst
index 4e47b44a2..66b384b96 100644
--- a/doc/design-2.1.rst
+++ b/doc/design-2.1.rst
@@ -131,12 +131,77 @@ expect the answers to be sent with, and clients are supposed to accept only
answers which contain salt generated by them.
The configuration daemon will be able to answer simple queries such as:
+
- master candidates list
- master node
- offline nodes
- instance list
- instance primary nodes
+Wire protocol
+^^^^^^^^^^^^^
+
+A confd query will look like this, on the wire::
+
+ {
+ "msg": "{\"type\": 1,
+ \"rsalt\": \"9aa6ce92-8336-11de-af38-001d093e835f\",
+ \"protocol\": 1,
+ \"query\": \"node1.example.com\"}\n",
+ "salt": "1249637704",
+ "hmac": "4a4139b2c3c5921f7e439469a0a45ad200aead0f"
+ }
+
+Detailed explanation of the various fields:
+
+- 'msg' contains a JSON-encoded query, its fields are:
+
+ - 'protocol', integer, is the confd protocol version (initially just
+ constants.CONFD_PROTOCOL_VERSION, with a value of 1)
+ - 'type', integer, is the query type. For example "node role by name" or
+ "node primary ip by instance ip". Constants will be provided for the actual
+ available query types.
+ - 'query', string, is the search key. For example an ip, or a node name.
+ - 'rsalt', string, is the required response salt. The client must use it to
+ recognize which answer it's getting.
+
+- 'salt' must be the current unix timestamp, according to the client. Servers
+ can refuse messages which have a wrong timing, according to their
+ configuration and clock.
+- 'hmac' is an hmac signature of salt+msg, with the cluster hmac key
+
+If an answer comes back (which is optional, since confd works over UDP) it will
+be in this format::
+
+ {
+ "msg": "{\"status\": 0,
+ \"answer\": 0,
+ \"serial\": 42,
+ \"protocol\": 1}\n",
+ "salt": "9aa6ce92-8336-11de-af38-001d093e835f",
+ "hmac": "aaeccc0dff9328fdf7967cb600b6a80a6a9332af"
+ }
+
+Where:
+
+- 'msg' contains a JSON-encoded answer, its fields are:
+
+ - 'protocol', integer, is the confd protocol version (initially just
+ constants.CONFD_PROTOCOL_VERSION, with a value of 1)
+ - 'status', integer, is the error code. Initially just 0 for 'ok' or '1' for
+ 'error' (in which case answer contains an error detail, rather than an
+ answer), but in the future it may be expanded to have more meanings (eg: 2,
+ the answer is compressed)
+ - 'answer', is the actual answer. Its type and meaning is query specific. For
+ example for "node primary ip by instance ip" queries it will be a string
+ containing an IP address, for "node role by name" queries it will be an
+ integer which encodes the role (master, candidate, drained, offline)
+ according to constants.
+
+- 'salt' is the requested salt from the query. A client can use it to recognize
+ what query the answer is answering.
+- 'hmac' is an hmac signature of salt+msg, with the cluster hmac key
+
Redistribute Config
~~~~~~~~~~~~~~~~~~~
--
GitLab