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