From: Guus Sliepen Date: Mon, 19 Feb 2018 19:41:21 +0000 (+0100) Subject: Document the control protocol. X-Git-Tag: release-1.1pre16~22 X-Git-Url: https://git.tinc-vpn.org/git/browse?a=commitdiff_plain;h=8f73169567fed6703acbad4f0f5fd5cff700d619;p=tinc Document the control protocol. --- diff --git a/doc/CONTROL b/doc/CONTROL new file mode 100644 index 00000000..72198a82 --- /dev/null +++ b/doc/CONTROL @@ -0,0 +1,146 @@ +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. + +The daemon creates a PID file and a socket in `/var/run` normally (if +`./configure` has been run with `--localstatedir=/var`). They are called: + + /var/run/tinc..pid + /var/run/tinc..socket + +These are only readable by the same user that started the tinc daemon. If the +`--user` option was used, but tinc was started by root, then these files will +still only be readable by root. + +Note, the control protocol is not stable yet, and may change at any point until +version 1.1.0 is released. + +Authentication +-------------- + +When connecting to the UNIX socket, the first line sent by the tinc daemon +looks like: + + 0 17.0 + +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: + + 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. + +If the cookie is accepted, the tinc daemon will respond with a line that looks +like: + + 4 0 + +Message format +-------------- + +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`. + +The tinc daemon will normally respond with: + + 18 + +Where is the same as sent in the request, and is a numeric +result, where 0 normally indicates success, and non-zero values indicate an +error. However, some requests will have other results, see below. + +Requests +-------- + +- `REQ_STOP`: stop the running tinc daemon. +- `REQ_DUMP_NODES`: dump information about all known nodes. See below for the result format. +- `REQ_DUMP_EDGES`: dump information about all known edges. See below for the result format. +- `REQ_DUMP_SUBNET`: dump information about all known subnets. See below for the result format. +- `REQ_DUMP_CONNECTIONS`: dump information about all meta-connections this tinc daemon has. See below for the result format. +- `REQ_PURGE`: purge information about unreachable nodes. +- `REQ_SET_DEBUG `: set the debug level for the default log output to . +- `REQ_RETRY`: retry any pending outgoing connections immediately. +- `REQ_RELOAD`: instructs the running tinc daemon to reload its configuration files. +- `REQ_DISCONNECT `: close any meta-connection with node . Returns 0 if success, -1 for invalid requests, and -2 if there was no meta-connection to this node. +- `REQ_DUMP_TRAFFIC`: dump network traffic statistics. See below for the result format. +- `REQ_PCAP `: start sending a packet capture stream to the control socket, with up to bytes per packet. +- `REQ_LOG `: start sending log output at level to the control socket. + +Dump formats +------------ + +Dumps result in multiple lines, that all start with: + + 18 + +The last line does not contain any parameters, and indicates the end of the dump. +The following sections list the parameters provided for each dump type: + +## REQ_DUMP_NODES + +1. node name +2. node ID (in hexadecimal format) +3. currently active address +4. the word "port" +5. currently active port +6. cipher ID (OpenSSL NID) +7. digest ID (OpenSSL NID) +8. digest length (in bytes) +9. compression level +10. bitfield of enabled options (hexadecimal, see OPTION_* in connection.h) +11. bitfield of current status (hexadecimal, see node_status_t in node.h) +12. nexthop +13. via +14. distance (in hops) +15. current path MTU +16. minimum discovered MTU +17. upper bound for MTU +18. time of last state change (in seconds since 1970-01-01 00:00 UT) + +## REQ_DUMP_EDGES + +1. node name from +2. node name to +3. address of the "to" node +4. the word "port" +5. port of the "to" node +6. local address of the "from" node +7. the word "port" +8: local port of the "from" node +9: bitfield of enabled options (hexadecimal, see OPTION_* in connection.h) +10: edge weight + +## REQ_DUMP_SUBNETS + +1. subnet +2. owner name, or `(broadcast)` for broadcast subnets. + +## REQ_DUMP_CONNECTIONS + +1. node name, or `` for control connections, or `` if no name is known yet +2. address of the node +3. the word "port" +4. port of the node +5. bitfield of enabled options (hexadecimal, see OPTION_* in connection.h) +6. socket fd +7. bitfield of current status (hexadecimal, see connection_status_t in connection.h) + +## REQ_DUMP_TRAFFIC + +1. node name +2. number of packets received from node +3. number of bytes received from node +4. number of packets sent to node +5. number of bytes sent to node