tinc-vpn.org Git - tinc/blob - doc/tinc.8.in

   1 .Dd 2014-01-16
   2 .Dt TINCCTL 8
   3 .\" Manual page created by:
   4 .\" Scott Lamb
   5 .Sh NAME
   6 .Nm tinc
   7 .Nd tinc VPN control
   8 .Sh SYNOPSIS
   9 .Nm
  10 .Op Fl cn
  11 .Op Fl -config Ns = Ns Ar DIR
  12 .Op Fl -net Ns = Ns Ar NETNAME
  13 .Op Fl -pidfile Ns = Ns Ar FILENAME
  14 .Op Fl -help
  15 .Op Fl -version
  16 .Op Ar COMMAND
  17 .Sh DESCRIPTION
  18 This is the control program of tinc, a secure virtual private network (VPN)
  19 project.
  20 .Nm
  21 can start and stop
  22 .Xr tincd 8 ,
  23 and can to alter and inspect the state of a running VPN.
  24 It can also be used to change the configuration,
  25 or to import or export host configuration files from other nodes.
  26
  27 If
  28 .Nm
  29 is started with a
  30 .Ar COMMAND ,
  31 this command is immediately executed, after which
  32 .Nm
  33 exits.
  34 If no
  35 .Ar COMMAND
  36 is given,
  37 .Nm
  38 will act as a shell;
  39 it will display a prompt, and commands can be entered on the prompt.
  40 If
  41 .Nm
  42 is compiled with libreadline, history and command completion are available on the prompt.
  43 One can also pipe a script containing commands through
  44 .Nm .
  45 In that case, lines starting with a # symbol will be ignored.
  46 .Sh OPTIONS
  47 .Bl -tag -width indent
  48 .It Fl n, -net Ns = Ns Ar NETNAME
  49 Communicate with tincd(8) connected with
  50 .Ar NETNAME .
  51 .It Fl -pidfile Ns = Ns Ar FILENAME
  52 Use the cookie from
  53 .Ar FILENAME
  54 to authenticate with a running tinc daemon.
  55 If unspecified, the default is
  56 .Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .pid.
  57 .It Fl -help
  58 Display short list of options.
  59 .It Fl -version
  60 Output version information and exit.
  61 .El
  62 .Sh ENVIRONMENT VARIABLES
  63 .Bl -tag -width indent
  64 .It Ev NETNAME
  65 If no netname is specified on the command line with the
  66 .Fl n
  67 option, the value of this environment variable is used.
  68 .El
  69 .Sh COMMANDS
  70 .Bl -tag -width indent
  71 .It init Op Ar name
  72 Create initial configuration files and RSA and Ed25519 keypairs with default length.
  73 If no
  74 .Ar name
  75 for this node is given, it will be asked for.
  76 .It get Ar variable
  77 Print the current value of configuration variable
  78 .Ar variable .
  79 If more than one variable with the same name exists,
  80 the value of each of them will be printed on a separate line.
  81 .It set Ar variable Ar value
  82 Set configuration variable
  83 .Ar variable
  84 to the given
  85 .Ar value .
  86 All previously existing configuration variables with the same name are removed.
  87 To set a variable for a specific host, use the notation
  88 .Ar host Ns Li . Ns Ar variable .
  89 .It add Ar variable Ar value
  90 As above, but without removing any previously existing configuration variables.
  91 .It del Ar variable Op Ar value
  92 Remove configuration variables with the same name and
  93 .Ar value .
  94 If no
  95 .Ar value
  96 is given, all configuration variables with the same name will be removed.
  97 .It edit Ar filename
  98 Start an editor for the given configuration file.
  99 You do not need to specify the full path to the file.
 100 .It export
 101 Export the host configuration file of the local node to standard output.
 102 .It export-all
 103 Export all host configuration files to standard output.
 104 .It import Op Fl -force
 105 Import host configuration data generated by the
 106 .Nm
 107 export command from standard input.
 108 Already existing host configuration files are not overwritten unless the option
 109 .Fl -force
 110 is used.
 111 .It exchange Op Fl -force
 112 The same as export followed by import.
 113 .It exchange-all Op Fl -force
 114 The same as export-all followed by import.
 115 .It invite Ar name
 116 Prepares an invitation for a new node with the given
 117 .Ar name ,
 118 and prints a short invitation URL that can be used with the join command.
 119 .It join Op Ar URL
 120 Join an existing VPN using an invitation URL created using the invite command.
 121 If no
 122 .Ar URL
 123 is given, it will be read from standard input.
 124 .It start Op tincd options
 125 Start
 126 .Xr tincd 8 ,
 127 optionally with the given extra options.
 128 .It stop
 129 Stop
 130 .Xr tincd 8 .
 131 .It restart Op tincd options
 132 Restart
 133 .Xr tincd 8 ,
 134 optionally with the given extra options.
 135 .It reload
 136 Partially rereads configuration files. Connections to hosts whose host
 137 config files are removed are closed. New outgoing connections specified
 138 in
 139 .Xr tinc.conf 5
 140 will be made.
 141 .It pid
 142 Shows the PID of the currently running
 143 .Xr tincd 8 .
 144 .It generate-keys Op bits
 145 Generate both RSA and Ed25519 keypairs (see below) and exit.
 146 .It generate-ed25519-keys
 147 Generate public/private Ed25519 keypair and exit.
 148 .It generate-rsa-keys Op bits
 149 Generate public/private RSA keypair and exit.
 150 If
 151 .Ar bits
 152 is omitted, the default length will be 2048 bits.
 153 When saving keys to existing files, tinc will not delete the old keys;
 154 you have to remove them manually.
 155 .It dump [reachable] nodes
 156 Dump a list of all known nodes in the VPN.
 157 If the keyword reachable is used, only lists reachable nodes.
 158 .It dump edges
 159 Dump a list of all known connections in the VPN.
 160 .It dump subnets
 161 Dump a list of all known subnets in the VPN.
 162 .It dump connections
 163 Dump a list of all meta connections with ourself.
 164 .It dump graph | digraph
 165 Dump a graph of the VPN in
 166 .Xr dotty 1
 167 format.
 168 Nodes are colored according to their reachability:
 169 red nodes are unreachable, orange nodes are indirectly reachable, green nodes are directly reachable.
 170 Black nodes are either directly or indirectly reachable, but direct reachability has not been tried yet.
 171 .It info Ar node | subnet | address
 172 Show information about a particular node, subnet or address.
 173 If an address is given, any matching subnet will be shown.
 174 .It purge
 175 Purges all information remembered about unreachable nodes.
 176 .It debug Ar N
 177 Sets debug level to
 178 .Ar N .
 179 .It log Op Ar N
 180 Capture log messages from a running tinc daemon.
 181 An optional debug level can be given that will be applied only for log messages sent to
 182 .Nm tinc .
 183 .It retry
 184 Forces
 185 .Xr tincd 8
 186 to try to connect to all uplinks immediately.
 187 Usually
 188 .Xr tincd 8
 189 attempts to do this itself,
 190 but increases the time it waits between the attempts each time it failed,
 191 and if
 192 .Xr tincd 8
 193 didn't succeed to connect to an uplink the first time after it started,
 194 it defaults to the maximum time of 15 minutes.
 195 .It disconnect Ar NODE
 196 Closes the meta connection with the given
 197 .Ar NODE .
 198 .It top
 199 If
 200 .Nm
 201 is compiled with libcurses support, this will display live traffic statistics
 202 for all the known nodes, similar to the UNIX
 203 .Xr top 1
 204 command.
 205 See below for more information.
 206 .It pcap
 207 Dump VPN traffic going through the local tinc node in
 208 .Xr pcap-savefile 5
 209 format to standard output,
 210 from where it can be redirected to a file or piped through a program that can parse it directly,
 211 such as
 212 .Xr tcpdump 8 .
 213 .It network Op Ar netname
 214 If
 215 .Ar netname
 216 is given, switch to that network.
 217 Otherwise, display a list of all networks for which configuration files exist.
 218 .El
 219 .Sh EXAMPLES
 220 Examples of some commands:
 221 .Bd -literal -offset indent
 222 tinc -n vpn dump graph | circo -Txlib
 223 tinc -n vpn pcap | tcpdump -r -
 224 tinc -n vpn top
 225 .Pp
 226 .Ed
 227 Examples of changing the configuration using
 228 .Nm :
 229 .Bd -literal -offset indent
 230 tinc -n vpn init foo
 231 tinc -n vpn add Subnet 192.168.1.0/24
 232 tinc -n vpn add bar.Address bar.example.com
 233 tinc -n vpn add ConnectTo bar
 234 tinc -n vpn export | gpg --clearsign | mail -s "My config" vpnmaster@example.com
 235 .Ed
 236 .Sh TOP
 237 The top command connects to a running tinc daemon and repeatedly queries its per-node traffic counters.
 238 It displays a list of all the known nodes in the left-most column,
 239 and the amount of bytes and packets read from and sent to each node in the other columns.
 240 By default, the information is updated every second.
 241 The behaviour of the top command can be changed using the following keys:
 242 .Bl -tag
 243 .It Ic s
 244 Change the interval between updates.
 245 After pressing the
 246 .Ic s
 247 key, enter the desired interval in seconds, followed by enter.
 248 Fractional seconds are honored.
 249 Intervals lower than 0.1 seconds are not allowed.
 250 .It Ic c
 251 Toggle between displaying current traffic rates (in packets and bytes per second)
 252 and cumulative traffic (total packets and bytes since the tinc daemon started).
 253 .It Ic n
 254 Sort the list of nodes by name.
 255 .It Ic i
 256 Sort the list of nodes by incoming amount of bytes.
 257 .It Ic I
 258 Sort the list of nodes by incoming amount of packets.
 259 .It Ic o
 260 Sort the list of nodes by outgoing amount of bytes.
 261 .It Ic O
 262 Sort the list of nodes by outgoing amount of packets.
 263 .It Ic t
 264 Sort the list of nodes by sum of incoming and outgoing amount of bytes.
 265 .It Ic T
 266 Sort the list of nodes by sum of incoming and outgoing amount of packets.
 267 .It Ic b
 268 Show amount of traffic in bytes.
 269 .It Ic k
 270 Show amount of traffic in kilobytes.
 271 .It Ic M
 272 Show amount of traffic in megabytes.
 273 .It Ic G
 274 Show amount of traffic in gigabytes.
 275 .It Ic q
 276 Quit.
 277 .El
 278 .Sh BUGS
 279 If you find any bugs, report them to tinc@tinc-vpn.org.
 280 .Sh SEE ALSO
 281 .Xr tincd 8 ,
 282 .Xr tinc.conf 5 ,
 283 .Xr dotty 1 ,
 284 .Xr pcap-savefile 5 ,
 285 .Xr tcpdump 8 ,
 286 .Xr top 1 ,
 287 .Pa http://www.tinc-vpn.org/ ,
 288 .Pa http://www.cabal.org/ .
 289 .Pp
 290 The full documentation for tinc is maintained as a Texinfo manual.
 291 If the info and tinc programs are properly installed at your site,
 292 the command
 293 .Ic info tinc
 294 should give you access to the complete manual.
 295 .Pp
 296 tinc comes with ABSOLUTELY NO WARRANTY.
 297 This is free software, and you are welcome to redistribute it under certain conditions;
 298 see the file COPYING for details.
 299 .Sh AUTHORS
 300 .An "Ivo Timmermans"
 301 .An "Guus Sliepen" Aq guus@tinc-vpn.org
 302 .Pp
 303 And thanks to many others for their contributions to tinc!