\input texinfo @c -*-texinfo-*-
-@c $Id$
@c %**start of header
@setfilename tinc.info
@settitle tinc Manual
This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
-Copyright @copyright{} 1998-2005 Ivo Timmermans
-<ivo@@tinc-vpn.org>, Guus Sliepen <guus@@tinc-vpn.org> and
+Copyright @copyright{} 1998-2010 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
-$Id$
-
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
@page
@vskip 0pt plus 1filll
-@cindex copyright
This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
-Copyright @copyright{} 1998-2005 Ivo Timmermans
-<ivo@@tinc-vpn.org>, Guus Sliepen <guus@@tinc-vpn.org> and
+Copyright @copyright{} 1998-2010 Ivo Timmermans,
+Guus Sliepen <guus@@tinc-vpn.org> and
Wessel Dankers <wsl@@tinc-vpn.org>.
-$Id$
-
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
@end titlepage
-@ifinfo
+@ifnottex
@c ==================================================================
@node Top
@top Top
* About us::
* Concept Index:: All used terms explained
@end menu
-@end ifinfo
+@end ifnottex
@c ==================================================================
@node Introduction
@section Configuring the kernel
@menu
-* Configuration of Linux kernels 2.1.60 up to 2.4.0::
-* Configuration of Linux kernels 2.4.0 and higher::
+* Configuration of Linux kernels::
* Configuration of FreeBSD kernels::
* Configuration of OpenBSD kernels::
* Configuration of NetBSD kernels::
@c ==================================================================
-@node Configuration of Linux kernels 2.1.60 up to 2.4.0
-@subsection Configuration of Linux kernels 2.1.60 up to 2.4.0
-
-@cindex ethertap
-For kernels up to 2.4.0, you need a kernel that supports the ethertap device.
-Most distributions come with kernels that already support this.
-If not, here are the options you have to turn on when configuring a new kernel:
-
-@example
-Code maturity level options
-[*] Prompt for development and/or incomplete code/drivers
-Networking options
-[*] Kernel/User netlink socket
-<M> Netlink device emulation
-Network device support
-<M> Ethertap network tap
-@end example
-
-If you want to run more than one instance of tinc or other programs that use
-the ethertap, you have to compile the ethertap driver as a module, otherwise
-you can also choose to compile it directly into the kernel.
-
-If you decide to build any of these as dynamic kernel modules, it's a good idea
-to add these lines to @file{/etc/modules.conf}:
-
-@example
-alias char-major-36 netlink_dev
-alias tap0 ethertap
-options tap0 -o tap0 unit=0
-alias tap1 ethertap
-options tap1 -o tap1 unit=1
-...
-alias tap@emph{N} ethertap
-options tap@emph{N} -o tap@emph{N} unit=@emph{N}
-@end example
-
-Add as much alias/options lines as necessary.
-
-
-@c ==================================================================
-@node Configuration of Linux kernels 2.4.0 and higher
-@subsection Configuration of Linux kernels 2.4.0 and higher
+@node Configuration of Linux kernels
+@subsection Configuration of Linux kernels
@cindex Universal tun/tap
-For kernels 2.4.0 and higher, you need a kernel that supports the Universal tun/tap device.
+For tinc to work, you need a kernel that supports the Universal tun/tap device.
Most distributions come with kernels that already support this.
Here are the options you have to turn on when configuring a new kernel:
It's not necessary to compile this driver as a module, even if you are going to
run more than one instance of tinc.
-If you have an early 2.4 kernel, you can choose both the tun/tap driver and the
-`Ethertap network tap' device. This latter is marked obsolete, and chances are
-that it won't even function correctly anymore. Make sure you select the
-universal tun/tap driver.
-
If you decide to build the tun/tap driver as a kernel module, add these lines
to @file{/etc/modules.conf}:
For OpenBSD version 2.9 and higher,
the tun driver is included in the default kernel configuration.
There is also a kernel patch from @uref{http://diehard.n-r-g.com/stuff/openbsd/}
-which adds a tap device to OpenBSD.
-This should work with tinc.
-
+which adds a tap device to OpenBSD which should work with tinc,
+but with recent versions of OpenBSD,
+a tun device can act as a tap device by setting the link0 option with ifconfig.
@c ==================================================================
@node Configuration of NetBSD kernels
@subsection Configuration of Darwin (MacOS/X) kernels
Tinc on Darwin relies on a tunnel driver for its data acquisition from the kernel.
-Tinc supports either the driver from @uref{http://www-user.rhrk.uni-kl.de/~nissler/tuntap/},
+Tinc supports either the driver from @uref{http://tuntaposx.sourceforge.net/},
which supports both tun and tap style devices,
and also the driver from from @uref{http://chrisp.de/en/projects/tunnel.html}.
The former driver is recommended.
@subsection Device files
@cindex device files
-First, you'll need the special device file(s) that form the interface
-between the kernel and the daemon.
-
-The permissions for these files have to be such that only the super user
-may read/write to this file. You'd want this, because otherwise
-eavesdropping would become a bit too easy. This does, however, imply
-that you'd have to run tincd as root.
+Most operating systems nowadays come with the necessary device files by default,
+or they have a mechanism to create them on demand.
-If you use Linux and have a kernel version prior to 2.4.0, you have to make the
-ethertap devices:
+If you use Linux and do not have udev installed,
+you may need to create the following device file if it does not exist:
@example
-mknod -m 600 /dev/tap0 c 36 16
-mknod -m 600 /dev/tap1 c 36 17
-...
-mknod -m 600 /dev/tap@emph{N} c 36 @emph{N+16}
-@end example
-
-There is a maximum of 16 ethertap devices.
-
-If you use the universal tun/tap driver, you have to create the
-following device file (unless it already exist):
-
-@example
-mknod -m 600 /dev/tun c 10 200
+mknod -m 600 /dev/net/tun c 10 200
@end example
-If you use Linux, and you run the new 2.4 kernel using the devfs filesystem,
-then the tun/tap device will probably be automatically generated as
-@file{/dev/net/tun}.
-
-Unlike the ethertap device, you do not need multiple device files if
-you are planning to run multiple tinc daemons.
-
@c ==================================================================
@node Other files
in the `=' sign, but doing so improves readability. If you leave it
out, remember to replace it with at least one space character.
+The server configuration is complemented with host specific configuration (see
+the next section). Although all host configuration options for the local node
+listed in this document can also be put in
+@file{@value{sysconfdir}/tinc/@var{netname}/tinc.conf}, it is recommended to
+put host specific configuration options in the host configuration file, as this
+makes it easy to exchange with other nodes.
+
In this section all valid variables are listed in alphabetical order.
The default value is given between parentheses,
other comments are between square brackets.
This option may not work on all platforms.
-@cindex BlockingTCP
-@item BlockingTCP = <yes|no> (no) [experimental]
-This options selects whether TCP connections, when established, should use blocking writes.
-When turned off, tinc will never block when a TCP connection becomes congested,
-but will have to terminate that connection instead.
-If turned on, tinc will not terminate connections but will block,
-thereby unable to process data to/from other connections.
-Turn this option on if you also use TCPOnly and tinc terminates connections frequently.
-
@cindex ConnectTo
@item ConnectTo = <@var{name}>
Specifies which other tinc daemon to connect to on startup.
Note that you can only use one device per daemon.
See also @ref{Device files}.
+@cindex DeviceType
+@item DeviceType = <tun|tunnohead|tunifhead|tap> (only supported on BSD platforms)
+The type of the virtual network device.
+Tinc will normally automatically select the right type, and this option should not be used.
+However, in case tinc does not seem to correctly interpret packets received from the virtual network device,
+using this option might help.
+
+@table @asis
+@item tun
+Set type to tun.
+Depending on the platform, this can either be with or without an address family header (see below).
+
+@cindex tunnohead
+@item tunnohead
+Set type to tun without an address family header.
+Tinc will expect packets read from the virtual network device to start with an IP header.
+On some platforms IPv6 packets cannot be read from or written to the device in this mode.
+
+@cindex tunifhead
+@item tunifhead
+Set type to tun with an address family header.
+Tinc will expect packets read from the virtual network device
+to start with a four byte header containing the address family,
+followed by an IP header.
+This mode should support both IPv4 and IPv6 packets.
+
+@item tap
+Set type to tap.
+Tinc will expect packets read from the virtual network device
+to start with an Ethernet header.
+@end table
+
+@cindex DirectOnly
+@item DirectOnly = <yes|no> (no) [experimental]
+When this option is enabled, packets that cannot be sent directly to the destination node,
+but which would have to be forwarded by an intermediate node, are dropped instead.
+When combined with the IndirectData option,
+packets for nodes for which we do not have a meta connection with are also dropped.
+
+@cindex Forwarding
+@item Forwarding = <off|internal|kernel> (internal) [experimental]
+This option selects the way indirect packets are forwarded.
+
+@table @asis
+@item off
+Incoming packets that are not meant for the local node,
+but which should be forwarded to another node, are dropped.
+
+@item internal
+Incoming packets that are meant for another node are forwarded by tinc internally.
+
+This is the default mode, and unless you really know you need another forwarding mode, don't change it.
+
+@item kernel
+Incoming packets are always sent to the TUN/TAP device, even if the packets are not for the local node.
+This is less efficient, but allows the kernel to apply its routing and firewall rules on them,
+and can also help debugging.
+@end table
+
+@cindex GraphDumpFile
+@item GraphDumpFile = <@var{filename}> [experimental]
+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)
@cindex Name
@item Name = <@var{name}> [required]
-This is a symbolic name for this connection. It can be anything
+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 _).
-@cindex PingTimeout
-@item PingTimeout = <@var{seconds}> (60)
+@cindex PingInterval
+@item PingInterval = <@var{seconds}> (60)
The number of seconds of inactivity that tinc will wait before sending a
-probe to the other end. If that other end doesn't answer within that
-same amount of seconds, the connection is terminated, and the others
-will be notified of this.
+probe to the other end.
+
+@cindex PingTimeout
+@item PingTimeout = <@var{seconds}> (5)
+The number of seconds to wait for a response to pings or to allow meta
+connections to block. If the other end doesn't respond within this time,
+the connection is terminated, and the others will be notified of this.
@cindex PriorityInheritance
@item PriorityInheritance = <yes|no> (no) [experimental]
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.
+Increasing the priority may help to reduce latency and packet loss on the VPN.
+
+@cindex StrictSubnets
+@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.
+
@cindex TunnelServer
@item TunnelServer = <yes|no> (no) [experimental]
When this option is enabled tinc will no longer forward information between other tinc daemons,
-and will only allow nodes and subnets on the VPN which are present in the
+and will only allow connections with nodes for which host config files are present in the local
@file{@value{sysconfdir}/tinc/@var{netname}/hosts/} directory.
+Setting this options also implicitly sets StrictSubnets.
@end table
@table @asis
@cindex Address
-@item Address = <@var{IP address}|@var{hostname}> [recommended]
+@item Address = <@var{IP address}|@var{hostname}> [<port>] [recommended]
This variable is only required if you want to connect to this host. It
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.
@cindex Cipher
@item Cipher = <@var{cipher}> (blowfish)
Furthermore, specifying "none" will turn off packet encryption.
It is best to use only those ciphers which support CBC mode.
+@cindex ClampMSS
+@item ClampMSS = <yes|no> (yes)
+This option specifies whether tinc should clamp the maximum segment size (MSS)
+of TCP packets to the path MTU. This helps in situations where ICMP
+Fragmentation Needed or Packet too Big messages are dropped by firewalls.
+
@cindex Compression
@item Compression = <@var{level}> (0)
This option sets the level of compression used for UDP packets.
Can be anything from 0
up to the length of the digest produced by the digest algorithm.
+@cindex PMTU
+@item PMTU = <@var{mtu}> (1514)
+This option controls the initial path MTU to this node.
+
+@cindex PMTUDiscovery
+@item PMTUDiscovery = <yes|no> (yes)
+When this option is enabled, tinc will try to discover the path MTU to this node.
+After the path MTU has been discovered, it will be enforced on the VPN.
+
@cindex Port
@item Port = <@var{port}> (655)
This is the port this tinc daemon listens on.
connection with that host.
@cindex Subnet
-@item Subnet = <@var{address}[/@var{prefixlength}]>
+@item Subnet = <@var{address}[/@var{prefixlength}[#@var{weight}]]>
The subnet which this tinc daemon will serve.
Tinc tries to look up which other daemon it should send a packet to by searching the appropiate subnet.
If the packet matches a subnet,
/22. This conforms to standard CIDR notation as described in
@uref{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519}
+@cindex Subnet weight
+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
+higher priority. Packets will be sent to the node with the highest priority,
+unless that node is not reachable, in which case the node with the next highest
+priority will be tried, and so on.
+
@cindex TCPonly
-@item TCPonly = <yes|no> (no) [experimental]
+@item TCPonly = <yes|no> (no) [deprecated]
If this variable is set to yes, then the packets are tunnelled over a
TCP connection instead of a UDP connection. This is especially useful
for those who want to run a tinc daemon from behind a masquerading
firewall, or if UDP packet routing is disabled somehow.
Setting this options also implicitly sets IndirectData.
+
+Since version 1.0.10, tinc will automatically detect whether communication via
+UDP is possible or not.
@end table
@item @value{sysconfdir}/tinc/@var{netname}/hosts/@var{host}-down
This script is started when the tinc daemon with name @var{host} becomes unreachable.
+@item @value{sysconfdir}/tinc/@var{netname}/host-up
+This script is started when any host becomes reachable.
+
+@item @value{sysconfdir}/tinc/@var{netname}/host-down
+This script is started when any host becomes unreachable.
+
@item @value{sysconfdir}/tinc/@var{netname}/subnet-up
This script is started when a Subnet becomes reachable.
The Subnet and the node it belongs to are passed in environment variables.
@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.
+
@end table
Note that the IP addresses of eth0 and tap0 are the same.
This is quite possible, if you make sure that the netmasks of the interfaces are different.
-It is in fact recommended to give give both real internal network interfaces and tap interfaces the same IP address,
+It is in fact recommended to give both real internal network interfaces and tap interfaces the same IP address,
since that will make things a lot easier to remember and set up.
@end example
Note here that the internal address (on eth0) doesn't have to be the
-same as on the tap0 device. Also, ConnectTo is given so that no-one can
-connect to this node.
+same as on the tap0 device. Also, ConnectTo is given so that this node will
+always try to connect to BranchA.
On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchB}:
@item -K, --generate-keys[=@var{bits}]
Generate public/private keypair of @var{bits} length. If @var{bits} is not specified,
-1024 is the default. tinc will ask where you want to store the files,
+2048 is the default. 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
in combination with -K). After that, tinc will quit.
Disables encryption and authentication.
Only useful for debugging.
+@item -R, --chroot
+Change process root directory to the directory where the config file is
+located (@file{@value{sysconfdir}/tinc/@var{netname}/} as determined by
+-n/--net option or as given by -c/--config option), for added security.
+The chroot is performed after all the initialization is done, after
+writing pid files and opening network sockets.
+
+Note that this option alone does not do any good without -U/--user, below.
+
+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.
+
+@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.
+
@item --help
Display a short reminder of these runtime options and terminate.
If so, check that it allows TCP and UDP traffic on port 655.
If it masquerades and the host running tinc is behind it, make sure that it forwards TCP and UDP traffic to port 655 to the host running tinc.
You can add @samp{TCPOnly = yes} to your host config file to force tinc to only use a single TCP connection,
-this works through most firewalls and NATs.
+this works through most firewalls and NATs. Since version 1.0.10, tinc will automatically fall back to TCP if direct communication via UDP is not possible.
@end itemize
@itemize
@item If you see this only sporadically, it is harmless and caused by a node sending packets using an old key.
-@item If you see this often and another node is not reachable anymore, then a NAT (masquerading firewall) is changing the source address of UDP packets.
-You can add @samp{TCPOnly = yes} to host configuration files to force all VPN traffic to go over a TCP connection.
@end itemize
@item Got bad/bogus/unauthorized REQUEST from foo (1.2.3.4 port 12345)
@section Authors
@table @asis
-@item Ivo Timmermans (zarq) (@email{ivo@@tinc-vpn.org})
+@item Ivo Timmermans (zarq)
@item Guus Sliepen (guus) (@email{guus@@tinc-vpn.org})
@end table
projects / tinc / blobdiff