Split event.c into per-API files
[tinc] / doc / CONTROL
1 Control protocol
2 ----------------
3
4 A running tinc daemon is listening on a UNIX socket. Other programs can connect
5 to this socket and send commands to control or query the running daemon. The
6 messages sent over the socket are simple lines of ASCII text, each line ending
7 with a linefeed character (`\n`).
8
9 The daemon creates a PID file and a socket in `/var/run` normally (if
10 `./configure` has been run with `--localstatedir=/var`).  They are called:
11
12     /var/run/tinc.<netname>.pid
13     /var/run/tinc.<netname>.socket
14
15 These are only readable by the same user that started the tinc daemon. If the
16 `--user` option was used, but tinc was started by root, then these files will
17 still only be readable by root.
18
19 Note, the control protocol is not stable yet, and may change at any point until
20 version 1.1.0 is released.
21
22 Authentication
23 --------------
24
25 When connecting to the UNIX socket, the first line sent by the tinc daemon
26 looks like:
27
28     0 <name> 17.0
29
30 Here, <name> is replaced with the Name of the tinc daemon.
31 The third word, 17.0, is the major.minor version of the protocol used by tinc.
32
33 The first line sent to the tinc daemon MUST be of this form:
34
35     0 ^<cookie> 0
36
37 Where <cookie> must be replaced by the cookie value found in the PID file
38 created by the tinc daemon.  This is the second word of the first line in
39 `/var/run/tinc.netname.pid`. Note, the `^` must still be put in front of the
40 actual cookie value. The cookie MUST be sent within 5 seconds, or the tinc
41 daemon will close the connection.
42
43 If the cookie is accepted, the tinc daemon will respond with a line that looks
44 like:
45
46     4 0 <pid>
47
48 Where <pid> is the PID of the tinc daemon itself. If the cookie is not
49 accepted, the tinc daemon will immediately close the connection. No error
50 message is sent prior to closing the connection.
51
52 Message format
53 --------------
54
55 Subsequent messages are always in this format:
56
57     18 <type> <parameters...>
58
59 Where <type> is a numeric code that identifies the type of request, and
60 <parameters> is a space-separated list of parameters. Individual parameters
61 never contain spaces of their own. Consequently, no escaping is done. The
62 available request types can be found in the `enum request_type` in
63 `control_common.h`.
64
65 The tinc daemon will normally respond with:
66
67     18 <type> <result code>
68
69 Where <type> is the same as sent in the request, and <result code> is a numeric
70 result, where 0 normally indicates success, and non-zero values indicate an
71 error. However, some requests will have other results, see below.
72
73 Requests
74 --------
75
76 - `REQ_STOP`: stop the running tinc daemon.
77 - `REQ_DUMP_NODES`: dump information about all known nodes. See below for the result format.
78 - `REQ_DUMP_EDGES`: dump information about all known edges. See below for the result format.
79 - `REQ_DUMP_SUBNET`: dump information about all known subnets. See below for the result format.
80 - `REQ_DUMP_CONNECTIONS`: dump information about all meta-connections this tinc daemon has. See below for the result format.
81 - `REQ_PURGE`: purge information about unreachable nodes.
82 - `REQ_SET_DEBUG <level>`: set the debug level for the default log output to <level>.
83 - `REQ_RETRY`: retry any pending outgoing connections immediately.
84 - `REQ_RELOAD`: instructs the running tinc daemon to reload its configuration files.
85 - `REQ_DISCONNECT <name>`: close any meta-connection with node <name>. Returns 0 if success, -1 for invalid requests, and -2 if there was no meta-connection to this node.
86 - `REQ_DUMP_TRAFFIC`: dump network traffic statistics. See below for the result format.
87 - `REQ_PCAP <snaplen>`: start sending a packet capture stream to the control socket, with up to <snaplen> bytes per packet.
88 - `REQ_LOG <level>`: start sending log output at level <level> to the control socket.
89
90 Dump formats
91 ------------
92
93 Dumps result in multiple lines, that all start with:
94
95     18 <type> <parameters...>
96
97 The last line does not contain any parameters, and indicates the end of the dump.
98 The following sections list the parameters provided for each dump type:
99
100 ## REQ_DUMP_NODES
101
102 1. node name
103 2. node ID (in hexadecimal format)
104 3. currently active address
105 4. the word "port"
106 5. currently active port
107 6. cipher ID (OpenSSL NID)
108 7. digest ID (OpenSSL NID)
109 8. digest length (in bytes)
110 9. compression level
111 10. bitfield of enabled options (hexadecimal, see OPTION_* in connection.h)
112 11. bitfield of current status (hexadecimal, see node_status_t in node.h)
113 12. nexthop
114 13. via
115 14. distance (in hops)
116 15. current path MTU
117 16. minimum discovered MTU
118 17. upper bound for MTU
119 18. time of last state change (in seconds since 1970-01-01 00:00 UT)
120
121 ## REQ_DUMP_EDGES
122
123 1. node name from
124 2. node name to
125 3. address of the "to" node
126 4. the word "port"
127 5. port of the "to" node
128 6. local address of the "from" node
129 7. the word "port"
130 8: local port of the "from" node
131 9: bitfield of enabled options (hexadecimal, see OPTION_* in connection.h)
132 10: edge weight
133
134 ## REQ_DUMP_SUBNETS
135
136 1. subnet
137 2. owner name, or `(broadcast)` for broadcast subnets.
138
139 ## REQ_DUMP_CONNECTIONS
140
141 1. node name, or `<control>` for control connections, or `<unknown>` if no name is known yet
142 2. address of the node
143 3. the word "port"
144 4. port of the node
145 5. bitfield of enabled options (hexadecimal, see OPTION_* in connection.h)
146 6. socket fd
147 7. bitfield of current status (hexadecimal, see connection_status_t in connection.h)
148
149 ## REQ_DUMP_TRAFFIC
150
151 1. node name
152 2. number of packets received from node
153 3. number of bytes received from node
154 4. number of packets sent to node
155 5. number of bytes sent to node