This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
-Copyright @copyright{} 1998-2012 Ivo Timmermans,
+Copyright @copyright{} 1998-2013 Ivo Timmermans,
Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
@vskip 0pt plus 1filll
This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
-Copyright @copyright{} 1998-2012 Ivo Timmermans,
+Copyright @copyright{} 1998-2013 Ivo Timmermans,
Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
@cindex release
For an up to date list of supported platforms, please check the list on
our website:
-@uref{http://www.tinc-vpn.org/platforms}.
+@uref{http://www.tinc-vpn.org/platforms/}.
@c
@c
* OpenSSL::
* zlib::
* lzo::
-* libevent::
+* libcurses::
+* libreadline::
@end menu
by the OpenSSL library.
If this library is not installed, you wil get an error when configuring
-tinc for build. Support for running tinc without having OpenSSL
+tinc for build. Support for running tinc with other cryptographic libraries
installed @emph{may} be added in the future.
You can use your operating system's package manager to install this if
For the optional compression of UDP packets, tinc uses the functions provided
by the zlib library.
-If this library is not installed, you wil get an error when configuring
-tinc for build. Support for running tinc without having zlib
-installed @emph{may} be added in the future.
+If this library is not installed, you wil get an error when running the
+configure script. You can either install the zlib library, or disable support
+for zlib compression by using the "--disable-zlib" option when running the
+configure script. Note that if you disable support for zlib, the resulting
+binary will not work correctly on VPNs where zlib compression is used.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
@subsection lzo
@cindex lzo
-Another form of compression is offered using the lzo library.
+Another form of compression is offered using the LZO library.
-If this library is not installed, you wil get an error when configuring
-tinc for build. Support for running tinc without having lzo
-installed @emph{may} be added in the future.
+If this library is not installed, you wil get an error when running the
+configure script. You can either install the LZO library, or disable support
+for LZO compression by using the "--disable-lzo" option when running the
+configure script. Note that if you disable support for LZO, the resulting
+binary will not work correctly on VPNs where LZO compression is used.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
@c ==================================================================
-@node libevent
-@subsection libevent
+@node libcurses
+@subsection libcurses
-@cindex libevent
-For the main event loop, tinc uses the libevent library.
+@cindex libcurses
+For the "tinc top" command, tinc requires a curses library.
-If this library is not installed, you wil get an error when configuring
-tinc for build.
+If this library is not installed, you wil get an error when running the
+configure script. You can either install a suitable curses library, or disable
+all functionality that depends on a curses library by using the
+"--disable-curses" option when running the configure script.
+
+There are several curses libraries. It is recommended that you install
+"ncurses" (@url{http://invisible-island.net/ncurses/}),
+however other curses libraries should also work.
+In particular, "PDCurses" (@url{http://pdcurses.sourceforge.net/})
+is recommended if you want to compile tinc for Windows.
+
+You can use your operating system's package manager to install this if
+available. Make sure you install the development AND runtime versions
+of this package.
+
+
+@c ==================================================================
+@node libreadline
+@subsection libreadline
+
+@cindex libreadline
+For the "tinc" command's shell functionality, tinc uses the readline library.
+
+If this library is not installed, you wil get an error when running the
+configure script. You can either install a suitable readline library, or
+disable all functionality that depends on a readline library by using the
+"--disable-readline" option when running the configure script.
You can use your operating system's package manager to install this if
available. Make sure you install the development AND runtime versions
of this package.
-If you have to install libevent manually, you can get the source code
-from @url{http://monkey.org/~provos/libevent/}. Instructions on how to configure,
-build and install this package are included within the package. Please
-make sure you build development and runtime libraries (which is the
-default).
+If you have to install libreadline manually, you can get the source code from
+@url{http://www.gnu.org/software/readline/}. Instructions on how to configure,
+build and install this package are included within the package. Please make
+sure you build development and runtime libraries (which is the default).
@c
If you cannot use one of the precompiled packages, or you want to compile tinc
for yourself, you can use the source. The source is distributed under
the GNU General Public License (GPL). Download the source from the
-@uref{http://www.tinc-vpn.org/download, download page}, which has
+@uref{http://www.tinc-vpn.org/download/, download page}, which has
the checksums of these files listed; you may wish to check these with
md5sum before continuing.
In order to build tinc on Darwin, you need to install the MacOS/X Developer Tools
from @uref{http://developer.apple.com/tools/macosxtools.html} and
-a recent version of Fink from @uref{http://fink.sourceforge.net/}.
+a recent version of Fink from @uref{http://www.finkproject.org/}.
After installation use fink to download and install the following packages:
autoconf25, automake, dlcompat, m4, openssl, zlib and lzo.
Make sure you have an adequate understanding of networks in general.
@cindex Network Administrators Guide
A good resource on networking is the
-@uref{http://www.linuxdoc.org/LDP/nag2/, Linux Network Administrators Guide}.
+@uref{http://www.tldp.org/LDP/nag2/, Linux Network Administrators Guide}.
If you have everything clearly pictured in your mind,
proceed in the following order:
First, create the initial configuration files and public/private keypairs using the following command:
@example
-tincctl -n @var{NETNAME} init @var{NAME}
+tinc -n @var{NETNAME} init @var{NAME}
@end example
-Second, use @samp{tincctl -n @var{NETNAME} config ...} to further configure tinc.
-Finally, export your host configuration file using @samp{tincctl -n @var{NETNAME} export} and send it to those
+Second, use @samp{tinc -n @var{NETNAME} config ...} to further configure tinc.
+Finally, export your host configuration file using @samp{tinc -n @var{NETNAME} export} and send it to those
people or computers you want tinc to connect to.
-They should send you their host configuration file back, which you can import using @samp{tincctl -n @var{NETNAME} import}.
+They should send you their host configuration file back, which you can import using @samp{tinc -n @var{NETNAME} import}.
These steps are described in the subsections below.
but it is recommended that you choose one anyway.
We will asume you use a netname throughout this document.
-This means that you call tincctl with the -n argument,
+This means that you call tinc with the -n argument,
which will specify the netname.
The effect of this option is that tinc will set its configuration
makes it easy to exchange with other nodes.
You can edit the config file manually, but it is recommended that you use
-tincctl to change configuration variables for you.
+tinc to change configuration variables for you.
In the following two subsections all valid variables are listed in alphabetical order.
The default value is given between parentheses,
If any is selected, then depending on the operating system
both IPv4 and IPv6 or just IPv6 listening sockets will be created.
+@cindex AutoConnect
+@item AutoConnect = <count> (0) [experimental]
+If set to a non-zero value,
+tinc will try to only have count meta connections to other nodes,
+by automatically making or breaking connections to known nodes.
+Higher values increase redundancy but also increase meta data overhead.
+When using this option, a good value is 3.
+
@cindex BindToAddress
@item BindToAddress = <@var{address}> [<@var{port}>]
If your computer has more than one IPv4 or IPv6 address, tinc
Ephemeral ECDH will be used for key exchanges,
and ECDSA will be used instead of RSA for authentication.
When enabled, an ECDSA key must have been generated before with
-@samp{tincctl generate-ecdsa-keys}.
+@samp{tinc generate-ecdsa-keys}.
The experimental protocol may change at any time,
and there is no guarantee that tinc will run stable when it is used.
and can also help debugging.
@end table
-@cindex GraphDumpFile
-@item GraphDumpFile = <@var{filename}>
-If this option is present,
-tinc will dump the current network graph to the file @var{filename}
-every minute, unless there were no changes to the graph.
-The file is in a format that can be read by graphviz tools.
-If @var{filename} starts with a pipe symbol |,
-then the rest of the filename is interpreted as a shell command
-that is executed, the graph is then sent to stdin.
-
@cindex Hostnames
@item Hostnames = <yes|no> (no)
This option selects whether IP addresses (both real and on the VPN)
@item router
In this mode Subnet
variables in the host configuration files will be used to form a routing table.
-Only unicast packets of routable protocols (IPv4 and IPv6) are supported in this mode.
+Only packets of routable protocols (IPv4 and IPv6) are supported in this mode.
This is the default mode, and unless you really know you need another mode, don't change it.
@cindex Name
@item Name = <@var{name}> [required]
This is a symbolic name for this connection.
-The name should consist only of alfanumeric and underscore characters (a-z, A-Z, 0-9 and _).
+The name should consist only of alfanumeric and underscore characters (a-z, A-Z, 0-9 and _), and is case sensitive.
If Name starts with a $, then the contents of the environment variable that follows will be used.
In that case, invalid characters will be converted to underscores.
If Name is $HOST, but no such environment variable exist,
-the hostname will be read using the gethostnname() system call.
+the hostname will be read using the gethostname() system call.
@cindex PingInterval
@item PingInterval = <@var{seconds}> (60)
@cindex PrivateKeyFile
@item PrivateKeyFile = <@var{path}> (@file{@value{sysconfdir}/tinc/@var{netname}/rsa_key.priv})
This is the full path name of the RSA private key file that was
-generated by @samp{tincctl generate-keys}. It must be a full path, not a
+generated by @samp{tinc generate-keys}. It must be a full path, not a
relative directory.
-Note that there must be exactly one of PrivateKey
-or PrivateKeyFile
-specified in the configuration file.
-
@cindex ProcessPriority
@item ProcessPriority = <low|normal|high>
When this option is used the priority of the tincd process will be adjusted.
@cindex IndirectData
@item IndirectData = <yes|no> (no)
-This option specifies whether other tinc daemons besides the one you
-specified with ConnectTo can make a direct connection to you. This is
-especially useful if you are behind a firewall and it is impossible to
-make a connection from the outside to your tinc daemon. Otherwise, it
-is best to leave this option out or set it to no.
+When set to yes, other nodes which do not already have a meta connection to you
+will not try to establish direct communication with you.
+It is best to leave this option out or set it to no.
@cindex MACLength
@item MACLength = <@var{bytes}> (4)
@cindex PublicKeyFile
@item PublicKeyFile = <@var{path}> [obsolete]
This is the full path name of the RSA public key file that was generated
-by @samp{tincctl generate-keys}. It must be a full path, not a relative
+by @samp{tinc generate-keys}. It must be a full path, not a relative
directory.
@cindex PEM format
Prefixlength is the number of bits set to 1 in the netmask part; for
example: netmask 255.255.255.0 would become /24, 255.255.252.0 becomes
/22. This conforms to standard CIDR notation as described in
-@uref{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519}
+@uref{http://www.ietf.org/rfc/rfc1519.txt, RFC1519}
A Subnet can be given a weight to indicate its priority over identical Subnets
owned by different nodes. The default weight is 10. Lower values indicate
The initial directory structure, configuration files and public/private keypairs are created using the following command:
@example
-tincctl -n @var{netname} init @var{name}
+tinc -n @var{netname} init @var{name}
@end example
(You will need to run this as root, or use "sudo".)
Then you should run the following command:
@example
-tincctl -n @var{netname} config add subnet 192.168.2.0/24
+tinc -n @var{netname} config add subnet 192.168.2.0/24
@end example
This will add a Subnet statement to your host configuration file.
For example, if you also use the IPv6 subnet fec0:0:0:2::/64, you can add it as well:
@example
-tincctl -n @var{netname} config add subnet fec0:0:0:2::/24
+tinc -n @var{netname} config add subnet fec0:0:0:2::/24
@end example
This will add another line to the file @file{hosts/@var{name}}.
For example, if your hostname is foo.example.org, run:
@example
-tincctl -n @var{netname} config add address foo.example.org
+tinc -n @var{netname} config add address foo.example.org
@end example
If you already know to which daemons your daemon should make meta-connections,
Suppose you want to connect to a daemon named "bar", run:
@example
-tincctl -n @var{netname} config add connectto bar
+tinc -n @var{netname} config add connectto bar
@end example
Note that you specify the Name of the other daemon here, not an IP address or hostname!
(assuming the owner of bar has the email address bar@@example.org):
@example
-tincctl -n @var{netname} export | mail -s "My config file" bar@@example.org
+tinc -n @var{netname} export | mail -s "My config file" bar@@example.org
@end example
If the owner of bar does the same to send his host configuration file to you,
or you can just start this command in a terminal and copy&paste the email:
@example
-tincctl -n @var{netname} import
+tinc -n @var{netname} import
@end example
If you are the owner of bar yourself, and you have SSH access to that computer,
-you can also swap the host configuration files using the following commands:
+you can also swap the host configuration files using the following command:
@example
-tincctl -n @var{netname} export | ssh bar.example.org tincctl -n @var{netname} import
-ssh bar.example.org tincctl -n @var{netname} export | tincctl -n @var{netname} import
+tinc -n @var{netname} export \
+ | ssh bar.example.org tinc -n @var{netname} exchange \
+ | tinc -n @var{netname} import
@end example
You should repeat this for all nodes you ConnectTo, or which ConnectTo you.
You can manually open the script in an editor, or use the following command:
@example
-tincctl -n @var{netname} edit tinc-up
+tinc -n @var{netname} edit tinc-up
@end example
An example @file{tinc-up} script, that would be appropriate for the scenario in the previous section, is:
how these example host is set up. All branches use the netname `company'
for this particular VPN.
-Each branch is set up using the @samp{tincctl init} and @samp{tincctl config} commands,
+Each branch is set up using the @samp{tinc init} and @samp{tinc config} commands,
here we just show the end results:
@subsubheading For Branch A
If everything else is done, you can start tinc by typing the following command:
@example
-tincctl -n @var{netname} start
+tinc -n @var{netname} start
@end example
@cindex daemon
@xref{Multiple networks}.
@item --pidfile=@var{filename}
-Store a cookie in @var{filename} which allows tincctl to authenticate.
+Store a cookie in @var{filename} which allows tinc to authenticate.
If unspecified, the default is
@file{@value{localstatedir}/run/tinc.@var{netname}.pid}.
Lock tinc into main memory.
This will prevent sensitive data like shared private keys to be written to the system swap files/partitions.
+This option is not supported on all platforms.
+
@item --logfile[=@var{file}]
Write log entries to a file instead of to the system logging facility.
If @var{file} is omitted, the default is @file{@value{localstatedir}/log/tinc.@var{netname}.log}.
Note also that tinc can't run scripts anymore (such as tinc-down or host-up),
unless it's setup to be runnable inside chroot environment.
+This option is not supported on all platforms.
@item -U, --user=@var{user}
Switch to the given @var{user} after initialization, at the same time as
chroot is performed (see --chroot above). With this option tinc drops
privileges, for added security.
+This option is not supported on all platforms.
+
@item --help
Display a short reminder of these runtime options and terminate.
@node Controlling tinc
@chapter Controlling tinc
-You can control and inspect a running tincd through the tincctl
+You can control and inspect a running tincd through the tinc
command. A quick example:
@example
-tincctl -n @var{netname} reload
+tinc -n @var{netname} reload
@end example
@menu
-* tincctl runtime options::
-* tincctl environment variables::
-* tincctl commands::
-* tincctl examples::
-* tincctl top::
+* tinc runtime options::
+* tinc environment variables::
+* tinc commands::
+* tinc examples::
+* tinc top::
@end menu
@c ==================================================================
-@node tincctl runtime options
-@section tincctl runtime options
+@node tinc runtime options
+@section tinc runtime options
@c from the manpage
@table @option
@end table
@c ==================================================================
-@node tincctl environment variables
-@section tincctl environment variables
+@node tinc environment variables
+@section tinc environment variables
@table @env
@cindex NETNAME
@end table
@c ==================================================================
-@node tincctl commands
-@section tincctl commands
+@node tinc commands
+@section tinc commands
@c from the manpage
@table @code
Export all host configuration files to standard output.
@item import [--force]
-Import host configuration file(s) from standard input.
+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.
+@item exchange [--force]
+The same as export followed by import.
+
+@item exchange-all [--force]
+The same as export-all followed by import.
+
@item start [tincd options]
Start @samp{tincd}, optionally with the given extra options.
but will default to the configuration directory (you can use the -c or -n
option).
-@item dump nodes
+@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 edges
Dump a list of all known connections in the VPN.
@item dump connections
Dump a list of all meta connections with ourself.
-@item dump 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.
@item info @var{node} | @var{subnet} | @var{address}
Show information about a particular @var{node}, @var{subnet} or @var{address}.
@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 tincctl.
+An optional debug level can be given that will be applied only for log messages sent to tinc.
@item retry
Forces tinc to try to connect to all uplinks immediately.
Closes the meta connection with the given @var{node}.
@item top
-If tincctl is compiled with libcurses support, this will display live traffic statistics for all the known nodes,
+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.
@end table
@c ==================================================================
-@node tincctl examples
-@section tincctl examples
+@node tinc examples
+@section tinc examples
Examples of some commands:
@example
-tincctl -n vpn dump graph | circo -Txlib
-tincctl -n vpn pcap | tcpdump -r -
-tincctl -n vpn top
+tinc -n vpn dump graph | circo -Txlib
+tinc -n vpn pcap | tcpdump -r -
+tinc -n vpn top
@end example
-Example of configuring tinc using tincctl:
+Example of configuring tinc using the tinc command:
@example
-tincctl -n vpn init foo
-tincctl -n vpn config Subnet 192.168.1.0/24
-tincctl -n vpn config bar.Address bar.example.com
-tincctl -n vpn config ConnectTo bar
-tincctl -n vpn export | gpg --clearsign | mail -s "My config" vpnmaster@@example.com
+tinc -n vpn init foo
+tinc -n vpn config Subnet 192.168.1.0/24
+tinc -n vpn config bar.Address bar.example.com
+tinc -n vpn config ConnectTo bar
+tinc -n vpn export | gpg --clearsign | mail -s "My config" vpnmaster@@example.com
@end example
@c ==================================================================
-@node tincctl top
-@section tincctl top
+@node tinc top
+@section tinc 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,
projects / tinc / blobdiff