From f10e98f5e5a3537b43fbc53f07ab691265de999a Mon Sep 17 00:00:00 2001 From: Guus Sliepen Date: Wed, 21 Feb 2018 20:34:42 +0100 Subject: [PATCH] Update the documentation of the control protocol. --- doc/CONTROL | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/CONTROL b/doc/CONTROL index 72198a82..f52b52d9 100644 --- a/doc/CONTROL +++ b/doc/CONTROL @@ -3,7 +3,8 @@ Control protocol A running tinc daemon is listening on a UNIX socket. Other programs can connect to this socket and send commands to control or query the running daemon. The -messages sent over the socket are simple lines of text. +messages sent over the socket are simple lines of ASCII text, each line ending +with a linefeed character (`\n`). The daemon creates a PID file and a socket in `/var/run` normally (if `./configure` has been run with `--localstatedir=/var`). They are called: @@ -26,22 +27,28 @@ looks like: 0 17.0 +Here, is replaced with the Name of the tinc daemon. The third word, 17.0, is the major.minor version of the protocol used by tinc. -The first sent to the tinc daemon must be of this form: +The first line sent to the tinc daemon MUST be of this form: 0 ^ 0 Where must be replaced by the cookie value found in the PID file created by the tinc daemon. This is the second word of the first line in `/var/run/tinc.netname.pid`. Note, the `^` must still be put in front of the -actual cookie value. +actual cookie value. The cookie MUST be sent within 5 seconds, or the tinc +daemon will close the connection. If the cookie is accepted, the tinc daemon will respond with a line that looks like: 4 0 +Where is the PID of the tinc daemon itself. If the cookie is not +accepted, the tinc daemon will immediately close the connection. No error +message is sent prior to closing the connection. + Message format -------------- @@ -50,8 +57,10 @@ Subsequent messages are always in this format: 18 Where is a numeric code that identifies the type of request, and - is a space-separated list of parameters. The available request -types can be found in the `enum request_type` in `control_common.h`. + is a space-separated list of parameters. Individual parameters +never contain spaces of their own. Consequently, no escaping is done. The +available request types can be found in the `enum request_type` in +`control_common.h`. The tinc daemon will normally respond with: -- 2.20.1