@cindex requirements
@cindex libraries
-Before you can configure or build tinc, you need to have the OpenSSL,
-zlib and lzo libraries installed on your system. If you try to configure tinc without
-having them installed, configure will give you an error message, and stop.
+Before you can configure or build tinc, you need to have the OpenSSL, zlib,
+lzo, curses and readline libraries installed on your system. If you try to
+configure tinc without having them installed, configure will give you an error
+message, and stop.
@menu
* OpenSSL::
@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf} and at least one other file in the directory
@file{@value{sysconfdir}/tinc/@var{netname}/hosts/}.
+An optionnal directory @file{@value{sysconfdir}/tinc/@var{netname}/conf.d} can be added from which
+any .conf file will be read.
+
These file consists of comments (lines started with a #) or assignments
in the form of
@cindex BindToAddress
@item BindToAddress = <@var{address}> [<@var{port}>]
-If your computer has more than one IPv4 or IPv6 address, tinc
-will by default listen on all of them for incoming connections.
-Multiple BindToAddress variables may be specified,
-in which case listening sockets for each specified address are made.
-
-If no @var{port} is specified, the socket will be bound to the port specified by the Port option,
-or to port 655 if neither is given.
-To only bind to a specific port but not to a specific address, use "*" for the @var{address}.
+This is the same as ListenAddress, however the address given with the BindToAddress option
+will also be used for outgoing connections.
+This is useful if your computer has more than one IPv4 or IPv6 address,
+and you want tinc to only use a specific one for outgoing packets.
@cindex BindToInterface
@item BindToInterface = <@var{interface}> [experimental]
Under Windows, this variable is used to select which network interface will be used.
If you specified a Device, this variable is almost always already correctly set.
+@cindex ListenAddress
+@item ListenAddress = <@var{address}> [<@var{port}>]
+If your computer has more than one IPv4 or IPv6 address, tinc
+will by default listen on all of them for incoming connections.
+This option can be used to restrict which addresses tinc listens on.
+Multiple ListenAddress variables may be specified,
+in which case listening sockets for each specified address are made.
+
+If no @var{port} is specified, the socket will listen on the port specified by the Port option,
+or to port 655 if neither is given.
+To only listen on a specific port but not to a specific address, use "*" for the @var{address}.
+
@cindex LocalDiscovery
@item LocalDiscovery = <yes | no> (no)
When enabled, tinc will try to detect peers that are on the same local network.
Increasing the priority may help to reduce latency and packet loss on the VPN.
@cindex Proxy
-@item Proxy = socks4 | socks4 | http | exec @var{...} [experimental]
+@item Proxy = socks4 | socks5 | http | exec @var{...} [experimental]
Use a proxy when making outgoing connections.
The following proxy types are currently supported:
Optionally, a @var{username} can be supplied which will be passed on to the proxy server.
@cindex socks5
-@item socks4 <@var{address}> <@var{port}> [<@var{username}> <@var{password}>]
+@item socks5 <@var{address}> <@var{port}> [<@var{username}> <@var{password}>]
Connect to the proxy using the SOCKS version 5 protocol.
If a @var{username} and @var{password} are given, basic username/password authentication will be used,
otherwise no authentication will be used.
traffic.
@cindex StrictSubnets
-@item StrictSubnets <yes|no> (no) [experimental]
+@item StrictSubnets = <yes|no> (no) [experimental]
When this option is enabled tinc will only use Subnet statements which are
present in the host config files in the local
@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory.
+Subnets learned via connections to other nodes and which are not
+present in the local host config files are ignored.
@cindex TunnelServer
@item TunnelServer = <yes|no> (no) [experimental]
must resolve to the external IP address where the host can be reached,
not the one that is internal to the VPN.
If no port is specified, the default Port is used.
+Multiple Address variables can be specified, in which case each address will be
+tried until a working connection has been established.
@cindex Cipher
@item Cipher = <@var{cipher}> (blowfish)
@cindex scripts
Apart from reading the server and host configuration files,
tinc can also run scripts at certain moments.
-Under Windows (not Cygwin), the scripts should have the extension .bat.
+Under Windows (not Cygwin), the scripts should have the extension @file{.bat} or @file{.cmd}.
@table @file
@cindex tinc-up
@item @value{sysconfdir}/tinc/@var{netname}/subnet-down
This script is started when a Subnet becomes unreachable.
+
+@item @value{sysconfdir}/tinc/@var{netname}/invitation-created
+This script is started when a new invitation has been created.
+
+@item @value{sysconfdir}/tinc/@var{netname}/invitation-accepted
+This script is started when an invitation has been used.
+
@end table
@cindex environment variables
The scripts are started without command line arguments,
but can make use of certain environment variables.
Under UNIX like operating systems the names of environment variables must be preceded by a $ in scripts.
-Under Windows, in @file{.bat} files, they have to be put between % signs.
+Under Windows, in @file{.bat} or @file{.cmd} files, they have to be put between % signs.
@table @env
@cindex NETNAME
@item SUBNET
When a subnet becomes (un)reachable, this is set to the subnet.
+@cindex WEIGHT
+@item WEIGHT
+When a subnet becomes (un)reachable, this is set to the subnet weight.
+
+@cindex INVITATION_FILE
+@item INVITATION_FILE
+When the @file{invitation-created} script is called,
+this is set to the file where the invitation details will be stored.
+
+@cindex INVITATION_URL
+@item INVITATION_URL
+When the @file{invitation-created} script is called,
+this is set to the invitation URL that has been created.
@end table
+Do not forget that under UNIX operating systems,
+you have to make the scripts executable, using the command @samp{chmod a+x script}.
+
@c ==================================================================
@node How to configure
@node Controlling tinc
@chapter Controlling tinc
-You can control and inspect a running tincd through the tinc
+@cindex command line interface
+You can start, stop, control and inspect a running tincd through the tinc
command. A quick example:
@example
tinc -n @var{netname} reload
@end example
+@cindex shell
+If tinc is started without a command, it will act as a shell; it will display a
+prompt, and commands can be entered on the prompt. If tinc is compiled with
+libreadline, history and command completion are available on the prompt. One
+can also pipe a script containing commands through tinc. In that case, lines
+starting with a # symbol will be ignored.
+
@menu
* tinc runtime options::
* tinc environment variables::
@c from the manpage
@table @code
+@cindex init
@item init [@var{name}]
Create initial configuration files and RSA and ECDSA keypairs with default length.
If no @var{name} for this node is given, it will be asked for.
+@cindex get
@item get @var{variable}
Print the current value of configuration variable @var{variable}.
If more than one variable with the same name exists,
the value of each of them will be printed on a separate line.
+@cindex set
@item set @var{variable} @var{value}
Set configuration variable @var{variable} to the given @var{value}.
All previously existing configuration variables with the same name are removed.
To set a variable for a specific host, use the notation @var{host}.@var{variable}.
+@cindex add
@item add @var{variable} @var{value}
As above, but without removing any previously existing configuration variables.
+@cindex del
@item del @var{variable} [@var{value}]
Remove configuration variables with the same name and @var{value}.
If no @var{value} is given, all configuration variables with the same name will be removed.
+@cindex edit
@item edit @var{filename}
Start an editor for the given configuration file.
You do not need to specify the full path to the file.
+@cindex export
@item export
Export the host configuration file of the local node to standard output.
+@cindex export-all
@item export-all
Export all host configuration files to standard output.
+@cindex import
@item import [--force]
Import host configuration file(s) generated by the tinc export command from standard input.
Already existing host configuration files are not overwritten unless the option --force is used.
+@cindex exchange
@item exchange [--force]
The same as export followed by import.
+@cindex exchange-all
@item exchange-all [--force]
The same as export-all followed by import.
+@cindex invite
@item invite @var{name}
Prepares an invitation for a new node with the given @var{name},
and prints a short invitation URL that can be used with the join command.
+@cindex join
@item join [@var{URL}]
Join an existing VPN using an invitation URL created using the invite command.
If no @var{URL} is given, it will be read from standard input.
+@cindex start
@item start [tincd options]
Start @samp{tincd}, optionally with the given extra options.
+@cindex stop
@item stop
Stop @samp{tincd}.
-@item restart
-Restart @samp{tincd}.
+@cindex restart
+@item restart [tincd options]
+Restart @samp{tincd}, optionally with the given extra options.
+@cindex reload
@item reload
Partially rereads configuration files. Connections to hosts whose host
config files are removed are closed. New outgoing connections specified
in @file{tinc.conf} will be made.
+@cindex pid
@item pid
Shows the PID of the currently running @samp{tincd}.
+@cindex generate-keys
@item generate-keys [@var{bits}]
Generate both RSA and ECDSA keypairs (see below) and exit.
tinc will ask where you want to store the files, but will default to the
configuration directory (you can use the -c or -n option).
+@cindex generate-ecdsa-keys
@item generate-ecdsa-keys
Generate public/private ECDSA keypair and exit.
+@cindex generate-rsa-keys
@item generate-rsa-keys [@var{bits}]
Generate public/private RSA keypair and exit. If @var{bits} is omitted, the
default length will be 2048 bits. When saving keys to existing files, tinc
will not delete the old keys; you have to remove them manually.
+@cindex dump
@item dump [reachable] nodes
Dump a list of all known nodes in the VPN.
If the reachable keyword is used, only lists reachable nodes.
@item dump connections
Dump a list of all meta connections with ourself.
+@cindex graph
@item dump graph | digraph
Dump a graph of the VPN in dotty format.
Nodes are colored according to their reachability:
red nodes are unreachable, orange nodes are indirectly reachable, green nodes are directly reachable.
Black nodes are either directly or indirectly reachable, but direct reachability has not been tried yet.
+@cindex info
@item info @var{node} | @var{subnet} | @var{address}
Show information about a particular @var{node}, @var{subnet} or @var{address}.
If an @var{address} is given, any matching subnet will be shown.
+@cindex purge
@item purge
Purges all information remembered about unreachable nodes.
+@cindex debug
@item debug @var{level}
Sets debug level to @var{level}.
+@cindex log
@item log [@var{level}]
Capture log messages from a running tinc daemon.
An optional debug level can be given that will be applied only for log messages sent to tinc.
+@cindex retry
@item retry
Forces tinc to try to connect to all uplinks immediately.
Usually tinc attempts to do this itself,
and if tinc didn't succeed to connect to an uplink the first time after it started,
it defaults to the maximum time of 15 minutes.
+@cindex disconnect
@item disconnect @var{node}
Closes the meta connection with the given @var{node}.
+@cindex top
@item top
If tinc is compiled with libcurses support, this will display live traffic statistics for all the known nodes,
similar to the UNIX top command.
See below for more information.
+@cindex pcap
@item pcap
Dump VPN traffic going through the local tinc node in pcap-savefile format to standard output,
from where it can be redirected to a file or piped through a program that can parse it directly,
tinc -n vpn top
@end example
-Example of configuring tinc using the tinc command:
+Examples of changing the configuration using tinc:
@example
tinc -n vpn init foo
@node tinc top
@section tinc top
+@cindex top
The top command connects to a running tinc daemon and repeatedly queries its per-node traffic counters.
It displays a list of all the known nodes in the left-most column,
and the amount of bytes and packets read from and sent to each node in the other columns.
projects / tinc / blobdiff