+@example
+#!/bin/sh
+ifconfig $INTERFACE 192.168.2.1 netmask 255.255.0.0
+ip addr add fec0:0:0:2::/48 dev $INTERFACE
+@end example
+
+The first command gives the interface an IPv4 address and a netmask.
+The kernel will also automatically add an IPv4 route to this interface, so normally you don't need
+to add route commands to the @file{tinc-up} script.
+The kernel will also bring the interface up after this command.
+@cindex netmask
+The netmask is the mask of the @emph{entire} VPN network, not just your
+own subnet.
+The second command gives the interface an IPv6 address and netmask,
+which will also automatically add an IPv6 route.
+If you only want to use @command{ip addr} commands on Linux, don't forget that it doesn't bring the interface up, unlike ifconfig,
+so you need to add @command{ip link set $INTERFACE up} in that case.
+
+The exact syntax of the ifconfig and route commands differs from platform to platform.
+You can look up the commands for setting addresses and adding routes in @ref{Platform specific information},
+but it is best to consult the manpages of those utilities on your platform.
+
+
+@c ==================================================================
+@node Example configuration
+@section Example configuration
+
+
+@cindex example
+Imagine the following situation. Branch A of our example `company' wants to connect
+three branch offices in B, C and D using the Internet. All four offices
+have a 24/7 connection to the Internet.
+
+A is going to serve as the center of the network. B and C will connect
+to A, and D will connect to C. Each office will be assigned their own IP
+network, 10.x.0.0.
+
+@example
+A: net 10.1.0.0 mask 255.255.0.0 gateway 10.1.54.1 internet IP 1.2.3.4
+B: net 10.2.0.0 mask 255.255.0.0 gateway 10.2.1.12 internet IP 2.3.4.5
+C: net 10.3.0.0 mask 255.255.0.0 gateway 10.3.69.254 internet IP 3.4.5.6
+D: net 10.4.0.0 mask 255.255.0.0 gateway 10.4.3.32 internet IP 4.5.6.7
+@end example
+
+Here, ``gateway'' is the VPN IP address of the machine that is running the
+tincd, and ``internet IP'' is the IP address of the firewall, which does not
+need to run tincd, but it must do a port forwarding of TCP and UDP on port
+655 (unless otherwise configured).
+
+In this example, it is assumed that eth0 is the interface that points to
+the inner (physical) LAN of the office, although this could also be the
+same as the interface that leads to the Internet. The configuration of
+the real interface is also shown as a comment, to give you an idea of
+how these example host is set up. All branches use the netname `company'
+for this particular VPN.
+
+Each branch is set up using the @command{tinc init} and @command{tinc config} commands,
+here we just show the end results:
+
+@subsubheading For Branch A
+
+@emph{BranchA} would be configured like this:
+
+In @file{@value{sysconfdir}/tinc/company/tinc-up}:
+
+@example
+#!/bin/sh
+
+# Real interface of internal network:
+# ifconfig eth0 10.1.54.1 netmask 255.255.0.0
+
+ifconfig $INTERFACE 10.1.54.1 netmask 255.0.0.0
+@end example
+
+and in @file{@value{sysconfdir}/tinc/company/tinc.conf}:
+
+@example
+Name = BranchA
+@end example
+
+On all hosts, @file{@value{sysconfdir}/tinc/company/hosts/BranchA} contains:
+
+@example
+Subnet = 10.1.0.0/16
+Address = 1.2.3.4
+
+-----BEGIN RSA PUBLIC KEY-----
+...
+-----END RSA PUBLIC KEY-----
+@end example
+
+Note that the IP addresses of eth0 and the VPN interface 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 both real internal network interfaces and VPN interfaces the same IP address,
+since that will make things a lot easier to remember and set up.
+
+
+@subsubheading For Branch B
+
+In @file{@value{sysconfdir}/tinc/company/tinc-up}:
+
+@example
+#!/bin/sh
+
+# Real interface of internal network:
+# ifconfig eth0 10.2.43.8 netmask 255.255.0.0
+
+ifconfig $INTERFACE 10.2.1.12 netmask 255.0.0.0
+@end example
+
+and in @file{@value{sysconfdir}/tinc/company/tinc.conf}:
+
+@example
+Name = BranchB
+@end example
+
+Note here that the internal address (on eth0) doesn't have to be the
+same as on the VPN interface.
+
+On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchB}:
+
+@example
+Subnet = 10.2.0.0/16
+Address = 2.3.4.5
+
+-----BEGIN RSA PUBLIC KEY-----
+...
+-----END RSA PUBLIC KEY-----
+@end example
+
+
+@subsubheading For Branch C
+
+In @file{@value{sysconfdir}/tinc/company/tinc-up}:
+
+@example
+#!/bin/sh
+
+# Real interface of internal network:
+# ifconfig eth0 10.3.69.254 netmask 255.255.0.0
+
+ifconfig $INTERFACE 10.3.69.254 netmask 255.0.0.0
+@end example
+
+and in @file{@value{sysconfdir}/tinc/company/tinc.conf}:
+
+@example
+Name = BranchC
+@end example
+
+C already has another daemon that runs on port 655, so they have to
+reserve another port for tinc. It knows the portnumber it has to listen on
+from it's own host configuration file.
+
+On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchC}:
+
+@example
+Address = 3.4.5.6
+Subnet = 10.3.0.0/16
+Port = 2000
+
+-----BEGIN RSA PUBLIC KEY-----
+...
+-----END RSA PUBLIC KEY-----
+@end example
+
+
+@subsubheading For Branch D
+
+In @file{@value{sysconfdir}/tinc/company/tinc-up}:
+
+@example
+#!/bin/sh
+
+# Real interface of internal network:
+# ifconfig eth0 10.4.3.32 netmask 255.255.0.0
+
+ifconfig $INTERFACE 10.4.3.32 netmask 255.0.0.0
+@end example
+
+and in @file{@value{sysconfdir}/tinc/company/tinc.conf}:
+
+@example
+Name = BranchD
+@end example
+
+D will be connecting to C, which has a tincd running for this network on
+port 2000. It knows the port number from the host configuration file.
+
+On all hosts, in @file{@value{sysconfdir}/tinc/company/hosts/BranchD}:
+
+@example
+Subnet = 10.4.0.0/16
+Address = 4.5.6.7
+
+-----BEGIN RSA PUBLIC KEY-----
+...
+-----END RSA PUBLIC KEY-----
+@end example
+
+@subsubheading Key files
+
+A, B, C and D all have their own public/private key pairs:
+
+The private RSA key is stored in @file{@value{sysconfdir}/tinc/company/rsa_key.priv},
+the private Ed25519 key is stored in @file{@value{sysconfdir}/tinc/company/ed25519_key.priv},
+and the public RSA and Ed25519 keys are put into the host configuration file in the @file{@value{sysconfdir}/tinc/company/hosts/} directory.
+
+@subsubheading Starting
+
+After each branch has finished configuration and they have distributed
+the host configuration files amongst them, they can start their tinc daemons.
+They don't necessarily have to wait for the other branches to have started
+their daemons, tinc will try connecting until they are available.
+
+
+@c ==================================================================
+@node Running tinc
+@chapter Running tinc
+
+If everything else is done, you can start tinc by typing the following command:
+
+@example
+tinc -n @var{netname} start
+@end example
+
+@cindex daemon
+Tinc will detach from the terminal and continue to run in the background like a good daemon.
+If there are any problems however you can try to increase the debug level
+and look in the syslog to find out what the problems are.
+
+@menu
+* Runtime options::
+* Signals::
+* Debug levels::
+* Solving problems::
+* Error messages::
+* Sending bug reports::
+@end menu
+
+
+@c ==================================================================
+@node Runtime options
+@section Runtime options
+
+Besides the settings in the configuration file, tinc also accepts some
+command line options.
+
+@cindex command line
+@cindex runtime options
+@cindex options
+@c from the manpage
+@table @option
+@item -c, --config=@var{path}
+Read configuration options from the directory @var{path}. The default is
+@file{@value{sysconfdir}/tinc/@var{netname}/}.
+
+@item -D, --no-detach
+Don't fork and detach.
+This will also disable the automatic restart mechanism for fatal errors.
+
+@cindex debug level
+@item -d, --debug=@var{level}
+Set debug level to @var{level}. The higher the debug level, the more gets
+logged. Everything goes via syslog.
+
+@item -n, --net=@var{netname}
+Use configuration for net @var{netname}.
+This will let tinc read all configuration files from
+@file{@value{sysconfdir}/tinc/@var{netname}/}.
+Specifying . for @var{netname} is the same as not specifying any @var{netname}.
+@xref{Multiple networks}.
+
+@item --pidfile=@var{filename}
+Store a cookie in @var{filename} which allows tinc to authenticate.
+If unspecified, the default is
+@file{@value{runstatedir}/tinc.@var{netname}.pid}.
+
+@item -o, --option=[@var{HOST}.]@var{KEY}=@var{VALUE}
+Without specifying a @var{HOST}, this will set server configuration variable @var{KEY} to @var{VALUE}.
+If specified as @var{HOST}.@var{KEY}=@var{VALUE},
+this will set the host configuration variable @var{KEY} of the host named @var{HOST} to @var{VALUE}.
+This option can be used more than once to specify multiple configuration variables.
+
+@item -L, --mlock
+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}.
+
+@item --pidfile=@var{file}
+Write PID to @var{file} instead of @file{@value{runstatedir}/tinc.@var{netname}.pid}.
+
+@item --bypass-security
+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.
+
+This option is best used in combination with the -U/--user option described below.
+
+You will need to ensure the chroot environment contains all the files necessary
+for tinc to run correctly.
+Most importantly, for tinc to be able to resolve hostnames inside the chroot environment,
+you must copy @file{/etc/resolv.conf} into the chroot directory.
+If you want to be able to run scripts other than @file{tinc-up} in the chroot,
+you must ensure the appropriate shell is also installed in the chroot, along with all its dependencies.
+
+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.
+
+@item --version
+Output version information and exit.
+
+@end table
+
+@c ==================================================================
+@node Signals
+@section Signals
+
+@cindex signals
+You can also send the following signals to a running tincd process:
+
+@c from the manpage
+@table @samp
+
+@item ALRM
+Forces tinc to try to connect to all uplinks immediately.
+Usually tinc attempts to do this itself,
+but increases the time it waits between the attempts each time it failed,
+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.
+
+@item HUP
+Partially rereads configuration files.
+Connections to hosts whose host config file are removed are closed.
+New outgoing connections specified in @file{tinc.conf} will be made.
+If the --logfile option is used, this will also close and reopen the log file,
+useful when log rotation is used.
+
+@end table
+
+@c ==================================================================
+@node Debug levels
+@section Debug levels
+
+@cindex debug levels
+The tinc daemon can send a lot of messages to the syslog.
+The higher the debug level, the more messages it will log.
+Each level inherits all messages of the previous level:
+
+@c from the manpage
+@table @samp
+
+@item 0
+This will log a message indicating tinc has started along with a version number.
+It will also log any serious error.
+
+@item 1
+This will log all connections that are made with other tinc daemons.
+
+@item 2
+This will log status and error messages from scripts and other tinc daemons.
+
+@item 3
+This will log all requests that are exchanged with other tinc daemons. These include
+authentication, key exchange and connection list updates.
+
+@item 4
+This will log a copy of everything received on the meta socket.
+
+@item 5
+This will log all network traffic over the virtual private network.
+
+@end table
+
+@c ==================================================================
+@node Solving problems
+@section Solving problems
+
+If tinc starts without problems, but if the VPN doesn't work, you will have to find the cause of the problem.
+The first thing to do is to start tinc with a high debug level in the foreground,
+so you can directly see everything tinc logs:
+
+@example
+tincd -n @var{netname} -d5 -D
+@end example
+
+If tinc does not log any error messages, then you might want to check the following things:
+
+@itemize
+@item @file{tinc-up} script
+Does this script contain the right commands?
+Normally you must give the interface the address of this host on the VPN, and the netmask must be big enough so that the entire VPN is covered.
+
+@item Subnet
+Does the Subnet (or Subnets) in the host configuration file of this host match the portion of the VPN that belongs to this host?
+
+@item Firewalls and NATs
+Do you have a firewall or a NAT device (a masquerading firewall or perhaps an ADSL router that performs masquerading)?
+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.
+
+@end itemize
+
+
+@c ==================================================================
+@node Error messages
+@section Error messages
+
+What follows is a list of the most common error messages you might find in the logs.
+Some of them will only be visible if the debug level is high enough.
+
+@table @samp
+@item Could not open /dev/tap0: No such device
+
+@itemize
+@item You forgot to `modprobe netlink_dev' or `modprobe ethertap'.
+@item You forgot to compile `Netlink device emulation' in the kernel.
+@end itemize
+
+@item Can't write to /dev/net/tun: No such device
+
+@itemize
+@item You forgot to `modprobe tun'.
+@item You forgot to compile `Universal TUN/TAP driver' in the kernel.
+@item The tun device is located somewhere else in @file{/dev/}.
+@end itemize
+
+@item Network address and prefix length do not match!
+
+@itemize
+@item The Subnet field must contain a @emph{network} address, trailing bits should be 0.
+@item If you only want to use one IP address, set the netmask to /32.
+@end itemize
+
+@item Error reading RSA key file `rsa_key.priv': No such file or directory
+
+@itemize
+@item You forgot to create a public/private key pair.
+@item Specify the complete pathname to the private key file with the @samp{PrivateKeyFile} option.
+@end itemize
+
+@item Warning: insecure file permissions for RSA private key file `rsa_key.priv'!
+
+@itemize
+@item The private key file is readable by users other than root.
+Use chmod to correct the file permissions.
+@end itemize
+
+@item Creating metasocket failed: Address family not supported
+
+@itemize
+@item By default tinc tries to create both IPv4 and IPv6 sockets.
+On some platforms this might not be implemented.
+If the logs show @samp{Ready} later on, then at least one metasocket was created,
+and you can ignore this message.
+You can add @samp{AddressFamily = ipv4} to @file{tinc.conf} to prevent this from happening.
+@end itemize
+
+@item Cannot route packet: unknown IPv4 destination 1.2.3.4
+
+@itemize
+@item You try to send traffic to a host on the VPN for which no Subnet is known.
+@item If it is a broadcast address (ending in .255), it probably is a samba server or a Windows host sending broadcast packets.
+You can ignore it.
+@end itemize
+
+@item Cannot route packet: ARP request for unknown address 1.2.3.4
+
+@itemize
+@item You try to send traffic to a host on the VPN for which no Subnet is known.
+@end itemize
+
+@item Packet with destination 1.2.3.4 is looping back to us!
+
+@itemize
+@item Something is not configured right. Packets are being sent out to the
+virtual network device, but according to the Subnet directives in your host configuration
+file, those packets should go to your own host. Most common mistake is that
+you have a Subnet line in your host configuration file with a prefix length which is
+just as large as the prefix of the virtual network interface. The latter should in almost all
+cases be larger. Rethink your configuration.
+Note that you will only see this message if you specified a debug
+level of 5 or higher!
+@item Chances are that a @samp{Subnet = ...} line in the host configuration file of this tinc daemon is wrong.
+Change it to a subnet that is accepted locally by another interface,
+or if that is not the case, try changing the prefix length into /32.
+@end itemize
+
+@item Node foo (1.2.3.4) is not reachable
+
+@itemize
+@item Node foo does not have a connection anymore, its tinc daemon is not running or its connection to the Internet is broken.
+@end itemize
+
+@item Received UDP packet from unknown source 1.2.3.4 (port 12345)
+
+@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)
+
+@itemize
+@item Node foo does not have the right public/private key pair.
+Generate new key pairs and distribute them again.
+@item An attacker tries to gain access to your VPN.
+@item A network error caused corruption of metadata sent from foo.
+@end itemize
+
+@end table
+
+@c ==================================================================
+@node Sending bug reports
+@section Sending bug reports
+
+If you really can't find the cause of a problem, or if you suspect tinc is not working right,
+you can send us a bugreport, see @ref{Contact information}.
+Be sure to include the following information in your bugreport:
+
+@itemize
+@item A clear description of what you are trying to achieve and what the problem is.
+@item What platform (operating system, version, hardware architecture) and which version of tinc you use.
+@item If compiling tinc fails, a copy of @file{config.log} and the error messages you get.
+@item Otherwise, a copy of @file{tinc.conf}, @file{tinc-up} and all files in the @file{hosts/} directory.
+@item The output of the commands @command{ifconfig -a} and @command{route -n} (or @command{netstat -rn} if that doesn't work).
+@item The output of any command that fails to work as it should (like ping or traceroute).
+@end itemize
+
+@c ==================================================================
+@node Controlling tinc
+@chapter Controlling 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::
+* tinc commands::
+* tinc examples::
+* tinc top::
+@end menu
+
+
+@c ==================================================================
+@node tinc runtime options
+@section tinc runtime options
+
+@c from the manpage
+@table @option
+@item -c, --config=@var{path}
+Read configuration options from the directory @var{path}. The default is
+@file{@value{sysconfdir}/tinc/@var{netname}/}.
+
+@item -n, --net=@var{netname}
+Use configuration for net @var{netname}. @xref{Multiple networks}.
+
+@item --pidfile=@var{filename}
+Use the cookie from @var{filename} to authenticate with a running tinc daemon.
+If unspecified, the default is
+@file{@value{runstatedir}/tinc.@var{netname}.pid}.
+
+@cindex batch
+@item -b, --batch
+Don't ask for anything (non-interactive mode).
+
+@item --force
+Force some commands to work despite warnings.
+
+@item --help
+Display a short reminder of runtime options and commands, then terminate.
+
+@item --version
+Output version information and exit.
+
+@end table
+
+@c ==================================================================
+@node tinc environment variables
+@section tinc environment variables
+
+@table @env
+@cindex NETNAME
+@item NETNAME
+If no netname is specified on the command line with the @option{-n} option,
+the value of this environment variable is used.
+@end table
+
+@c ==================================================================
+@node tinc commands
+@section tinc commands
+
+@c from the manpage
+@table @samp
+
+@cindex init
+@item init [@var{name}]
+Create initial configuration files and RSA and Ed25519 key pairs 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.
+If the variable already exists with the given value, nothing happens.
+
+@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
+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
+The same as export followed by import.
+
+@cindex exchange-all
+@item exchange-all
+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 @command{tincd}, optionally with the given extra options.
+
+@cindex stop
+@item stop
+Stop @command{tincd}.
+
+@cindex restart
+@item restart [tincd options]
+Restart @command{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 @command{tincd}.
+
+@cindex generate-keys
+@item generate-keys [@var{bits}]
+Generate both RSA and Ed25519 key pairs (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-ed25519-keys
+@item generate-ed25519-keys
+Generate public/private Ed25519 key pair and exit.
+
+@cindex generate-rsa-keys
+@item generate-rsa-keys [@var{bits}]
+Generate public/private RSA key pair 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 edges
+Dump a list of all known connections in the VPN.
+
+@item dump subnets
+Dump a list of all known subnets in the VPN.
+
+@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.
+
+@item dump invitations
+Dump a list of outstanding invitations.
+The filename of the invitation, as well as the name of the node that is being invited is shown for each invitation.
+
+@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,
+but increases the time it waits between the attempts each time it failed,
+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,
+such as tcpdump.
+
+@cindex network
+@item network [@var{netname}]
+If @var{netname} is given, switch to that network.
+Otherwise, display a list of all networks for which configuration files exist.
+
+@cindex fsck
+@item fsck
+This will check the configuration files for possible problems,
+such as unsafe file permissions, missing executable bit on script,
+unknown and obsolete configuration variables, wrong public and/or private keys, and so on.
+
+When problems are found, this will be printed on a line with WARNING or ERROR in front of it.
+Most problems must be corrected by the user itself, however in some cases (like file permissions and missing public keys),
+tinc will ask if it should fix the problem.
+
+@cindex sign
+@item sign [@var{filename}]
+Sign a file with the local node's private key.
+If no @var{filename} is given, the file is read from standard input.
+The signed file is written to standard output.
+
+@cindex verify
+@item verify @var{name} [@var{filename}]
+
+Check the signature of a file against a node's public key.
+The @var{name} of the node must be given,
+or can be @samp{.} to check against the local node's public key,
+or @samp{*} to allow a signature from any node whose public key is known.
+If no @var{filename} is given, the file is read from standard input.
+If the verification is successful, a copy of the input with the signature removed is written to standard output, and the exit code will be zero.
+If the verification failed, nothing will be written to standard output, and the exit code will be non-zero.
+
+@end table
+
+@c ==================================================================
+@node tinc examples
+@section tinc examples
+
+Examples of some commands:
+
+@example
+tinc -n vpn dump graph | circo -Txlib
+tinc -n vpn pcap | tcpdump -r -
+tinc -n vpn top
+@end example
+
+Examples of changing the configuration using tinc:
+
+@example
+tinc -n vpn init foo
+tinc -n vpn add Subnet 192.168.1.0/24
+tinc -n vpn add bar.Address bar.example.com
+tinc -n vpn set Mode switch
+tinc -n vpn export | gpg --clearsign | mail -s "My config" vpnmaster@@example.com
+@end example
+
+@c ==================================================================
+@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.
+By default, the information is updated every second.
+The behaviour of the top command can be changed using the following keys:
+
+@table @key
+
+@item s
+Change the interval between updates.
+After pressing the @key{s} key, enter the desired interval in seconds, followed by enter.
+Fractional seconds are honored.
+Intervals lower than 0.1 seconds are not allowed.
+
+@item c
+Toggle between displaying current traffic rates (in packets and bytes per second)
+and cumulative traffic (total packets and bytes since the tinc daemon started).
+
+@item n
+Sort the list of nodes by name.
+
+@item i
+Sort the list of nodes by incoming amount of bytes.
+
+@item I
+Sort the list of nodes by incoming amount of packets.
+
+@item o
+Sort the list of nodes by outgoing amount of bytes.
+
+@item O
+Sort the list of nodes by outgoing amount of packets.
+
+@item t
+Sort the list of nodes by sum of incoming and outgoing amount of bytes.
+
+@item T
+Sort the list of nodes by sum of incoming and outgoing amount of packets.
+
+@item b
+Show amount of traffic in bytes.
+
+@item k
+Show amount of traffic in kilobytes.
+
+@item M
+Show amount of traffic in megabytes.
+
+@item G
+Show amount of traffic in gigabytes.
+
+@item q
+Quit.
+
+@end table
+
+
+@c ==================================================================
+@node Invitations
+@chapter Invitations
+
+Invitations are an easy way to add new nodes to an existing VPN. Invitations
+can be created on an existing node using the @command{tinc invite} command, which
+generates a relatively short URL which can be given to someone else, who uses
+the @command{tinc join} command to automatically set up tinc so it can connect to
+the inviting node. The next sections describe how invitations actually work,
+and how to further automate the invitations.
+
+@menu
+* How invitations work::
+* Invitation file format::
+* Writing an invitation-created script::
+@end menu
+
+
+@c ==================================================================
+@node How invitations work
+@section How invitations work
+
+When an invitation is created on a node (which from now on we will call the
+server) using the @command{tinc invite} command, an invitation file is created
+that contains all the information necessary for the invitee (which we will call
+the client) to create its configuration files. The invitation file is stays on
+the server, but a URL is generated that has enough information for the client
+to contact the server and to retrieve the invitation file. The whole URL is
+around 80 characters long and looks like this:
+
+@example
+server.example.org:12345/cW1NhLHS-1WPFlcFio8ztYHvewTTKYZp8BjEKg3vbMtDz7w4
+@end example
+
+It is composed of four parts:
+
+@example
+hostname : port / keyhash cookie
+@end example
+
+The hostname and port tell the client how to reach the tinc daemon on the server.
+The part after the slash looks like one blob, but is composed of two parts.
+The keyhash is the hash of the public key of the server.
+The cookie is a shared secret that identifies the client to the server.
+
+When the client connects to the server in order to join the VPN, the client and
+server will exchange temporary public keys. The client verifies that the hash
+of the server's public key matches the keyhash from the invitation URL. If
+not, it will immediately exit with an error. Otherwise, an ECDH exchange will
+happen so the client and server can communicate privately with each other. The
+client will then present the cookie to the server. The server uses this to
+look up the corresponding invitation file it generated earlier. If it exists,
+it will send the invitation file to the client. The client will also create a
+permanent public key, and send it to the server. After the exchange is
+completed, the connection is broken. The server creates a host config file for
+the client containing the client's permanent public key, and the client creates
+tinc.conf, host config files and possibly a tinc-up script based on the
+information in the invitation file.
+
+It is important that the invitation URL is kept secret until it is used; if
+another person gets a copy of the invitation URL before the real client runs
+the @command{tinc join} command, then that other person can try to join the VPN.
+
+
+@c ==================================================================
+@node Invitation file format
+@section Invitation file format
+
+The contents of an invitation file that is generated by the @command{tinc invite}
+command looks like this:
+
+@example
+Name = client
+Netname = vpn
+ConnectTo = server
+#-------------------------------------#
+Name = server
+Ed25519PublicKey = augbnwegoij123587...
+Address = server.example.com
+@end example
+
+The file is basically a concatenation of several host config blocks. Each host
+config block starts with @samp{Name = ...}. Lines that look like @samp{#---#}
+are not important, it just makes it easier for humans to read the file.
+However, the first line of an invitation file @emph{must} always start with
+@samp{Name = ...}.
+
+The first host config block is always the one representing the invitee. So the
+first Name statement determines the name that the invitee will get. From the
+first block, the @file{tinc.conf} and @file{hosts/client} files will be
+generated; the @command{tinc join} command on the client will automatically
+separate statements based on whether they should be in @file{tinc.conf} or in a
+host config file. Some statements are special and are treated differently:
+
+@table @asis
+@item Netname = <@var{netname}>
+This is a hint to the invitee which netname to use for the VPN. It is used if
+the invitee did not already specify a netname, and if there is no pre-existing
+configuration with the same netname.
+
+@cindex Ifconfig
+@item Ifconfig = <@var{address}[/@var{netmask}] | dhcp | dhcp6 | slaac>
+This is a hint for generating a @file{tinc-up} script.
+If an address is specified, a command will be added to @file{tinc-up} so the VPN interface will be configured to have the given address.
+If it is the word @samp{dhcp}, a command will be added to start a DHCP client on the VPN interface.
+If it is the word @samp{dhcpv6}, it will be a DHCPv6 client.
+If it is @samp{slaac}, then it will add commands to enable IPv6 stateless address autoconfiguration.
+It is also possible to specify a MAC address, in which case a command will be added to set the MAC address of the VPN interface.
+
+The exact commands added to the @file{tinc-up} script depends on the operating system the client is using.
+Multiple Ifconfig statements can be specified, however one should only use one Ifconfig statement per address family.
+
+@cindex Route
+@item Route = <@var{address}[/@var{netmask}]> [<@var{gateway}>]
+This is a hint for generating a @file{tinc-up} script.
+Route statements are similar to Ifconfig statements, but add routes instead of addresses.
+These only allow IPv4 and IPv6 routes.
+If no gateway address is specified, the route is directed to the VPN interface.
+In general, a gateway is only necessary when running tinc in switch mode.
+@end table
+
+Subsequent host config blocks are copied verbatim into their respective files
+in @file{hosts/}. The invitation file generated by @command{tinc invite} will
+normally only contain two blocks; one for the client and one for the server.
+
+
+@c ==================================================================
+@node Writing an invitation-created script
+@section Writing an invitation-created script
+
+When an invitation is generated, the @file{invitation-created} script is called (if
+it exists) right after the invitation file is written, but before the URL has
+been written to stdout. This allows one to change the invitation file
+automatically before the invitation URL is passed to the invitee. Here is an
+example shell script that approximately recreates the default invitation file:
+
+@example
+#!/bin/sh
+
+cat >$INVITATION_FILE <<EOF
+Name = $NODE
+Netname = $NETNAME
+ConnectTo = $NAME
+#----------------#
+EOF
+
+tinc export >>$INVITATION_FILE
+@end example
+
+You can add more ConnectTo statements, and change `tinc export` to `tinc
+export-all` for example. But you can also use the script to automatically hand
+out a Subnet to the invitee. Note that the script doesn't have to be a shell script,
+you can use any language, it just has to be executable.
+
+
+@c ==================================================================
+@node Technical information
+@chapter Technical information
+
+
+@menu
+* The connection::
+* The meta-protocol::
+* Security::
+@end menu
+
+
+@c ==================================================================
+@node The connection
+@section The connection
+
+@cindex connection
+Tinc is a daemon that takes VPN data and transmit that to another host
+computer over the existing Internet infrastructure.
+
+@menu
+* The UDP tunnel::
+* The meta-connection::
+@end menu
+
+
+@c ==================================================================
+@node The UDP tunnel
+@subsection The UDP tunnel
+
+@cindex virtual network device
+@cindex frame type
+The data itself is read from a character device file, the so-called
+@emph{virtual network device}. This device is associated with a network
+interface. Any data sent to this interface can be read from the device,
+and any data written to the device gets sent from the interface.
+There are two possible types of virtual network devices:
+`tun' style, which are point-to-point devices which can only handle IPv4 and/or IPv6 packets,
+and `tap' style, which are Ethernet devices and handle complete Ethernet frames.
+
+So when tinc reads an Ethernet frame from the device, it determines its
+type. When tinc is in it's default routing mode, it can handle IPv4 and IPv6
+packets. Depending on the Subnet lines, it will send the packets off to their destination IP address.
+In the `switch' and `hub' mode, tinc will use broadcasts and MAC address discovery
+to deduce the destination of the packets.
+Since the latter modes only depend on the link layer information,
+any protocol that runs over Ethernet is supported (for instance IPX and Appletalk).
+However, only `tap' style devices provide this information.
+
+After the destination has been determined,
+the packet will be compressed (optionally),
+a sequence number will be added to the packet,
+the packet will then be encrypted
+and a message authentication code will be appended.
+
+@cindex encapsulating
+@cindex UDP
+When that is done, time has come to actually transport the
+packet to the destination computer. We do this by sending the packet
+over an UDP connection to the destination host. This is called
+@emph{encapsulating}, the VPN packet (though now encrypted) is
+encapsulated in another IP datagram.
+
+When the destination receives this packet, the same thing happens, only
+in reverse. So it checks the message authentication code, decrypts the contents of the UDP datagram,
+checks the sequence number
+and writes the decrypted information to its own virtual network device.
+
+If the virtual network device is a `tun' device (a point-to-point tunnel),
+there is no problem for the kernel to accept a packet.
+However, if it is a `tap' device (this is the only available type on FreeBSD),
+the destination MAC address must match that of the virtual network interface.
+If tinc is in it's default routing mode, ARP does not work, so the correct destination MAC
+can not be known by the sending host.
+Tinc solves this by letting the receiving end detect the MAC address of its own virtual network interface
+and overwriting the destination MAC address of the received packet.
+
+In switch or hub modes ARP does work so the sender already knows the correct destination MAC address.
+In those modes every interface should have a unique MAC address, so make sure they are not the same.
+Because switch and hub modes rely on MAC addresses to function correctly,
+these modes cannot be used on the following operating systems which don't have a `tap' style virtual network device:
+NetBSD, Darwin and Solaris.
+
+
+@c ==================================================================
+@node The meta-connection
+@subsection The meta-connection
+
+Having only a UDP connection available is not enough. Though suitable
+for transmitting data, we want to be able to reliably send other
+information, such as routing and session key information to somebody.
+
+@cindex TCP
+TCP is a better alternative, because it already contains protection
+against information being lost, unlike UDP.
+
+So we establish two connections. One for the encrypted VPN data, and one
+for other information, the meta-data. Hence, we call the second
+connection the meta-connection. We can now be sure that the
+meta-information doesn't get lost on the way to another computer.
+
+@cindex data-protocol
+@cindex meta-protocol
+Like with any communication, we must have a protocol, so that everybody
+knows what everything stands for, and how she should react. Because we
+have two connections, we also have two protocols. The protocol used for
+the UDP data is the ``data-protocol,'' the other one is the
+``meta-protocol.''
+
+The reason we don't use TCP for both protocols is that UDP is much
+better for encapsulation, even while it is less reliable. The real
+problem is that when TCP would be used to encapsulate a TCP stream
+that's on the private network, for every packet sent there would be
+three ACKs sent instead of just one. Furthermore, if there would be
+a timeout, both TCP streams would sense the timeout, and both would
+start re-sending packets.
+
+
+@c ==================================================================
+@node The meta-protocol
+@section The meta-protocol
+
+The meta protocol is used to tie all tinc daemons together, and
+exchange information about which tinc daemon serves which virtual
+subnet.
+
+The meta protocol consists of requests that can be sent to the other
+side. Each request has a unique number and several parameters. All
+requests are represented in the standard ASCII character set. It is
+possible to use tools such as telnet or netcat to connect to a tinc
+daemon started with the --bypass-security option
+and to read and write requests by hand, provided that one
+understands the numeric codes sent.
+
+The authentication scheme is described in @ref{Security}. After a
+successful authentication, the server and the client will exchange all the
+information about other tinc daemons and subnets they know of, so that both
+sides (and all the other tinc daemons behind them) have their information
+synchronised.
+
+@cindex ADD_EDGE
+@cindex ADD_SUBNET
+@example
+message
+------------------------------------------------------------------
+ADD_EDGE node1 node2 21.32.43.54 655 222 0
+ | | | | | +-> options
+ | | | | +----> weight
+ | | | +--------> UDP port of node2
+ | | +----------------> real address of node2
+ | +-------------------------> name of destination node
+ +-------------------------------> name of source node
+
+ADD_SUBNET node 192.168.1.0/24
+ | | +--> prefixlength
+ | +--------> network address
+ +------------------> owner of this subnet
+------------------------------------------------------------------
+@end example
+
+The ADD_EDGE messages are to inform other tinc daemons that a connection between
+two nodes exist. The address of the destination node is available so that
+VPN packets can be sent directly to that node.
+
+The ADD_SUBNET messages inform other tinc daemons that certain subnets belong
+to certain nodes. tinc will use it to determine to which node a VPN packet has
+to be sent.
+
+@cindex DEL_EDGE
+@cindex DEL_SUBNET
+@example
+message
+------------------------------------------------------------------
+DEL_EDGE node1 node2
+ | +----> name of destination node
+ +----------> name of source node
+
+DEL_SUBNET node 192.168.1.0/24
+ | | +--> prefixlength
+ | +--------> network address
+ +------------------> owner of this subnet
+------------------------------------------------------------------
+@end example
+
+In case a connection between two daemons is closed or broken, DEL_EDGE messages
+are sent to inform the other daemons of that fact. Each daemon will calculate a
+new route to the the daemons, or mark them unreachable if there isn't any.
+
+@cindex REQ_KEY
+@cindex ANS_KEY
+@cindex KEY_CHANGED
+@example
+message
+------------------------------------------------------------------
+REQ_KEY origin destination
+ | +--> name of the tinc daemon it wants the key from
+ +----------> name of the daemon that wants the key
+
+ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4
+ | | \______________/ | | +--> MAC length
+ | | | | +-----> digest algorithm
+ | | | +--------> cipher algorithm
+ | | +--> 128 bits key
+ | +--> name of the daemon that wants the key
+ +----------> name of the daemon that uses this key
+
+KEY_CHANGED origin
+ +--> daemon that has changed it's packet key
+------------------------------------------------------------------
+@end example
+
+The keys used to encrypt VPN packets are not sent out directly. This is
+because it would generate a lot of traffic on VPNs with many daemons, and
+chances are that not every tinc daemon will ever send a packet to every
+other daemon. Instead, if a daemon needs a key it sends a request for it
+via the meta connection of the nearest hop in the direction of the
+destination.
+
+@cindex PING
+@cindex PONG
+@example
+daemon message
+------------------------------------------------------------------
+origin PING
+dest. PONG
+------------------------------------------------------------------
+@end example
+
+There is also a mechanism to check if hosts are still alive. Since network
+failures or a crash can cause a daemon to be killed without properly
+shutting down the TCP connection, this is necessary to keep an up to date
+connection list. PINGs are sent at regular intervals, except when there
+is also some other traffic. A little bit of salt (random data) is added
+with each PING and PONG message, to make sure that long sequences of PING/PONG
+messages without any other traffic won't result in known plaintext.
+
+This basically covers what is sent over the meta connection by tinc.
+
+
+@c ==================================================================
+@node Security
+@section Security
+
+@cindex TINC
+@cindex Cabal
+Tinc got its name from ``TINC,'' short for @emph{There Is No Cabal}; the
+alleged Cabal was/is an organisation that was said to keep an eye on the
+entire Internet. As this is exactly what you @emph{don't} want, we named
+the tinc project after TINC.
+
+@cindex SVPN
+But in order to be ``immune'' to eavesdropping, you'll have to encrypt
+your data. Because tinc is a @emph{Secure} VPN (SVPN) daemon, it does
+exactly that: encrypt.
+However, encryption in itself does not prevent an attacker from modifying the encrypted data.
+Therefore, tinc also authenticates the data.
+Finally, tinc uses sequence numbers (which themselves are also authenticated) to prevent an attacker from replaying valid packets.
+
+Since version 1.1pre3, tinc has two protocols used to protect your data; the legacy protocol, and the new Simple Peer-to-Peer Security (SPTPS) protocol.
+The SPTPS protocol is designed to address some weaknesses in the legacy protocol.
+The new authentication protocol is used when two nodes connect to each other that both have the ExperimentalProtocol option set to yes,
+otherwise the legacy protocol will be used.
+
+@menu
+* Legacy authentication protocol::
+* Simple Peer-to-Peer Security::
+* Encryption of network packets::
+* Security issues::
+@end menu
+
+
+@c ==================================================================
+@node Legacy authentication protocol
+@subsection Legacy authentication protocol
+
+@cindex legacy authentication protocol
+
+@cindex ID
+@cindex META_KEY
+@cindex CHALLENGE
+@cindex CHAL_REPLY
+@cindex ACK
+@example
+daemon message
+--------------------------------------------------------------------------
+client <attempts connection>
+
+server <accepts connection>
+
+client ID client 17.2
+ | | +-> minor protocol version
+ | +----> major protocol version
+ +--------> name of tinc daemon
+
+server ID server 17.2
+ | | +-> minor protocol version
+ | +----> major protocol version
+ +--------> name of tinc daemon
+
+client META_KEY 94 64 0 0 5f0823a93e35b69e...7086ec7866ce582b
+ | | | | \_________________________________/
+ | | | | +-> RSAKEYLEN bits totally random string S1,
+ | | | | encrypted with server's public RSA key
+ | | | +-> compression level
+ | | +---> MAC length
+ | +------> digest algorithm NID
+ +---------> cipher algorithm NID
+
+server META_KEY 94 64 0 0 6ab9c1640388f8f0...45d1a07f8a672630
+ | | | | \_________________________________/
+ | | | | +-> RSAKEYLEN bits totally random string S2,
+ | | | | encrypted with client's public RSA key
+ | | | +-> compression level
+ | | +---> MAC length
+ | +------> digest algorithm NID
+ +---------> cipher algorithm NID
+--------------------------------------------------------------------------
+@end example
+
+The protocol allows each side to specify encryption algorithms and parameters,
+but in practice they are always fixed, since older versions of tinc did not
+allow them to be different from the default values. The cipher is always
+Blowfish in OFB mode, the digest is SHA1, but the MAC length is zero and no
+compression is used.
+
+From now on:
+@itemize
+@item the client will symmetrically encrypt outgoing traffic using S1
+@item the server will symmetrically encrypt outgoing traffic using S2
+@end itemize
+
+@example
+--------------------------------------------------------------------------
+client CHALLENGE da02add1817c1920989ba6ae2a49cecbda0
+ \_________________________________/
+ +-> CHALLEN bits totally random string H1
+
+server CHALLENGE 57fb4b2ccd70d6bb35a64c142f47e61d57f
+ \_________________________________/
+ +-> CHALLEN bits totally random string H2
+
+client CHAL_REPLY 816a86
+ +-> 160 bits SHA1 of H2
+
+server CHAL_REPLY 928ffe
+ +-> 160 bits SHA1 of H1
+
+After the correct challenge replies are received, both ends have proved
+their identity. Further information is exchanged.
+
+client ACK 655 123 0
+ | | +-> options
+ | +----> estimated weight
+ +--------> listening port of client
+
+server ACK 655 321 0
+ | | +-> options
+ | +----> estimated weight
+ +--------> listening port of server
+--------------------------------------------------------------------------
+@end example
+
+This legacy authentication protocol has several weaknesses, pointed out by security export Peter Gutmann.
+First, data is encrypted with RSA without padding.
+Padding schemes are designed to prevent attacks when the size of the plaintext is not equal to the size of the RSA key.
+Tinc always encrypts random nonces that have the same size as the RSA key, so we do not believe this leads to a break of the security.
+There might be timing or other side-channel attacks against RSA encryption and decryption, tinc does not employ any protection against those.
+Furthermore, both sides send identical messages to each other, there is no distinction between server and client,
+which could make a MITM attack easier.
+However, no exploit is known in which a third party who is not already trusted by other nodes in the VPN could gain access.
+Finally, the RSA keys are used to directly encrypt the session keys, which means that if the RSA keys are compromised, it is possible to decrypt all previous VPN traffic.
+In other words, the legacy protocol does not provide perfect forward secrecy.
+
+@c ==================================================================
+@node Simple Peer-to-Peer Security
+@subsection Simple Peer-to-Peer Security
+@cindex SPTPS
+
+The SPTPS protocol is designed to address the weaknesses in the legacy protocol.
+SPTPS is based on TLS 1.2, but has been simplified: there is no support for exchanging public keys, and there is no cipher suite negotiation.
+Instead, SPTPS always uses a very strong cipher suite:
+peers authenticate each other using 521 bits ECC keys,
+Diffie-Hellman using ephemeral 521 bits ECC keys is used to provide perfect forward secrecy (PFS),
+AES-256-CTR is used for encryption, and HMAC-SHA-256 for message authentication.
+
+Similar to TLS, messages are split up in records.
+A complete logical record contains the following information:
+
+@itemize
+@item uint32_t seqno (network byte order)
+@item uint16_t length (network byte order)
+@item uint8_t type
+@item opaque data[length]
+@item opaque hmac[HMAC_SIZE] (HMAC over all preceding fields)
+@end itemize
+
+Depending on whether SPTPS records are sent via TCP or UDP, either the seqno or the length field is omitted on the wire
+(but they are still included in the calculation of the HMAC);
+for TCP packets are guaranteed to arrive in-order so we can infer the seqno, but packets can be split or merged, so we still need the length field to determine the boundaries between records;
+for UDP packets we know that there is exactly one record per packet, and we know the length of a packet, but packets can be dropped, duplicated and/or reordered, so we need to include the seqno.
+
+The type field is used to distinguish between application records or handshake records.
+Types 0 to 127 are application records, type 128 is a handshake record, and types 129 to 255 are reserved.
+
+Before the initial handshake, no fields are encrypted, and the HMAC field is not present.
+After the authentication handshake, the length (if present), type and data fields are encrypted, and the HMAC field is present.
+For UDP packets, the seqno field is not encrypted, as it is used to determine the value of the counter used for encryption.
+
+The authentication consists of an exchange of Key EXchange, SIGnature and ACKnowledge messages, transmitted using type 128 records.
+
+Overview:
+
+@example
+Initiator Responder
+---------------------
+KEX ->
+ <- KEX
+SIG ->
+ <- SIG
+
+...encrypt and HMAC using session keys from now on...
+
+App ->
+ <- App
+...
+ ...
+
+...key renegotiation starts here...
+
+KEX ->
+ <- KEX
+SIG ->
+ <- SIG
+ACK ->
+ <- ACK
+
+...encrypt and HMAC using new session keys from now on...
+
+App ->
+ <- App
+...
+ ...
+---------------------
+@end example
+
+Note that the responder does not need to wait before it receives the first KEX message,
+it can immediately send its own once it has accepted an incoming connection.
+
+Key EXchange message:
+
+@itemize
+@item uint8_t kex_version (always 0 in this version of SPTPS)
+@item opaque nonce[32] (random number)
+@item opaque ecdh_key[ECDH_SIZE]
+@end itemize
+
+SIGnature message:
+
+@itemize
+@item opaque ecdsa_signature[ECDSA_SIZE]
+@end itemize
+
+ACKnowledge message:
+
+@itemize
+@item empty (only sent after key renegotiation)
+@end itemize
+
+Remarks:
+
+@itemize
+@item At the start, both peers generate a random nonce and an Elliptic Curve public key and send it to the other in the KEX message.
+@item After receiving the other's KEX message, both KEX messages are concatenated (see below),
+ and the result is signed using ECDSA.
+ The result is sent to the other.
+@item After receiving the other's SIG message, the signature is verified.
+ If it is correct, the shared secret is calculated from the public keys exchanged in the KEX message using the Elliptic Curve Diffie-Helman algorithm.
+@item The shared secret key is expanded using a PRF.
+ Both nonces and the application specific label are also used as input for the PRF.
+@item An ACK message is sent only when doing key renegotiation, and is sent using the old encryption keys.
+@item The expanded key is used to key the encryption and HMAC algorithms.
+@end itemize
+
+The signature is calculated over this string:
+
+@itemize
+@item uint8_t initiator (0 = local peer, 1 = remote peer is initiator)
+@item opaque remote_kex_message[1 + 32 + ECDH_SIZE]
+@item opaque local_kex_message[1 + 32 + ECDH_SIZE]
+@item opaque label[label_length]
+@end itemize
+
+The PRF is calculated as follows:
+
+@itemize
+@item A HMAC using SHA512 is used, the shared secret is used as the key.
+@item For each block of 64 bytes, a HMAC is calculated. For block n: hmac[n] =
+ HMAC_SHA512(hmac[n - 1] + seed)
+@item For the first block (n = 1), hmac[0] is given by HMAC_SHA512(zeroes + seed),
+ where zeroes is a block of 64 zero bytes.
+@end itemize
+
+The seed is as follows:
+
+@itemize
+@item const char[13] "key expansion"
+@item opaque responder_nonce[32]
+@item opaque initiator_nonce[32]
+@item opaque label[label_length]
+@end itemize
+
+The expanded key is used as follows:
+
+@itemize
+@item opaque responder_cipher_key[CIPHER_KEYSIZE]
+@item opaque responder_digest_key[DIGEST_KEYSIZE]
+@item opaque initiator_cipher_key[CIPHER_KEYSIZE]
+@item opaque initiator_digest_key[DIGEST_KEYSIZE]
+@end itemize
+
+Where initiator_cipher_key is the key used by session initiator to encrypt
+messages sent to the responder.
+
+When using 256 bits Ed25519 keys, the AES-256-CTR cipher and HMAC-SHA-256 digest algorithm,
+the sizes are as follows:
+
+@example
+ECDH_SIZE: 32 (= 256/8)
+ECDSA_SIZE: 64 (= 2 * 256/8)
+CIPHER_KEYSIZE: 48 (= 256/8 + 128/8)
+DIGEST_KEYSIZE: 32 (= 256/8)
+@end example
+
+Note that the cipher key also includes the initial value for the counter.
+
+@c ==================================================================
+@node Encryption of network packets
+@subsection Encryption of network packets
+@cindex encryption
+
+A data packet can only be sent if the encryption key is known to both
+parties, and the connection is activated. If the encryption key is not
+known, a request is sent to the destination using the meta connection
+to retrieve it.
+
+@cindex UDP
+The UDP packets can be either encrypted with the legacy protocol or with SPTPS.
+In case of the legacy protocol, the UDP packet containing the network packet from the VPN has the following layout:
+
+@example
+... | IP header | UDP header | seqno | VPN packet | MAC | UDP trailer
+ \___________________/\_____/
+ | |
+ V +---> digest algorithm
+ Encrypted with symmetric cipher
+@end example
+
+
+
+
+So, the entire VPN packet is encrypted using a symmetric cipher, including a 32 bits
+sequence number that is added in front of the actual VPN packet, to act as a unique
+IV for each packet and to prevent replay attacks. A message authentication code
+is added to the UDP packet to prevent alteration of packets.
+Tinc by default encrypts network packets using Blowfish with 128 bit keys in CBC mode
+and uses 4 byte long message authentication codes to make sure
+eavesdroppers cannot get and cannot change any information at all from the
+packets they can intercept. The encryption algorithm and message authentication
+algorithm can be changed in the configuration. The length of the message
+authentication codes is also adjustable. The length of the key for the
+encryption algorithm is always the default length used by LibreSSL/OpenSSL.
+
+The SPTPS protocol is described in @ref{Simple Peer-to-Peer Security}.
+For comparison, this is how SPTPS UDP packets look:
+
+@example
+... | IP header | UDP header | seqno | type | VPN packet | MAC | UDP trailer
+ \__________________/\_____/
+ | |
+ V +---> digest algorithm
+ Encrypted with symmetric cipher
+@end example
+
+The difference is that the seqno is not encrypted, since the encryption cipher is used in CTR mode,
+and therefore the seqno must be known before the packet can be decrypted.
+Furthermore, the MAC is never truncated.
+The SPTPS protocol always uses the AES-256-CTR cipher and HMAC-SHA-256 digest,
+this cannot be changed.
+
+
+@c ==================================================================
+@node Security issues
+@subsection Security issues
+
+In August 2000, we discovered the existence of a security hole in all versions
+of tinc up to and including 1.0pre2. This had to do with the way we exchanged
+keys. Since then, we have been working on a new authentication scheme to make
+tinc as secure as possible. The current version uses the LibreSSL or OpenSSL library and
+uses strong authentication with RSA keys.
+
+On the 29th of December 2001, Jerome Etienne posted a security analysis of tinc
+1.0pre4. Due to a lack of sequence numbers and a message authentication code
+for each packet, an attacker could possibly disrupt certain network services or
+launch a denial of service attack by replaying intercepted packets. The current
+version adds sequence numbers and message authentication codes to prevent such
+attacks.
+
+On the 15th of September 2003, Peter Gutmann posted a security analysis of tinc
+1.0.1. He argues that the 32 bit sequence number used by tinc is not a good IV,
+that tinc's default length of 4 bytes for the MAC is too short, and he doesn't
+like tinc's use of RSA during authentication. We do not know of a security hole
+in the legacy protocol of tinc, but it is not as strong as TLS or IPsec.
+
+The Sweet32 attack affects versions of tinc prior to 1.0.30.
+
+On September 6th, 2018, Michael Yonly contacted us and provided
+proof-of-concept code that allowed a remote attacker to create an
+authenticated, one-way connection with a node, and also that there was a
+possibility for a man-in-the-middle to force UDP packets from a node to be sent
+in plaintext. The first issue was trivial to exploit on tinc versions prior to
+1.0.30, but the changes in 1.0.30 to mitigate the Sweet32 attack made this
+weakness much harder to exploit. These issues have been fixed in tinc 1.0.35.
+
+This version of tinc comes with an improved protocol, called Simple
+Peer-to-Peer Security (SPTPS), which aims to be as strong as TLS with one of
+the strongest cipher suites. None of the above security issues affected SPTPS.
+However, be aware that SPTPS is only used between nodes running tinc 1.1pre* or
+later, and in a VPN with nodes running different versions, the security might
+only be as good as that of the oldest version.
+
+Cryptography is a hard thing to get right. We cannot make any
+guarantees. Time, review and feedback are the only things that can
+prove the security of any cryptographic product. If you wish to review
+tinc or give us feedback, you are strongly encouraged to do so.
+
+
+@c ==================================================================
+@node Platform specific information
+@chapter Platform specific information
+
+@menu
+* Interface configuration::
+* Routes::
+* Automatically starting tinc::
+@end menu
+
+@c ==================================================================
+@node Interface configuration
+@section Interface configuration
+
+When configuring an interface, one normally assigns it an address and a
+netmask. The address uniquely identifies the host on the network attached to
+the interface. The netmask, combined with the address, forms a subnet. It is
+used to add a route to the routing table instructing the kernel to send all
+packets which fall into that subnet to that interface. Because all packets for
+the entire VPN should go to the virtual network interface used by tinc, the
+netmask should be such that it encompasses the entire VPN.
+
+For IPv4 addresses:
+
+@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@item Linux
+@tab @command{ifconfig} @var{interface} @var{address} @samp{netmask} @var{netmask}
+@item Linux iproute2
+@tab @command{ip addr add} @var{address}@samp{/}@var{prefixlength} @samp{dev} @var{interface}
+@item FreeBSD
+@tab @command{ifconfig} @var{interface} @var{address} @samp{netmask} @var{netmask}
+@item OpenBSD
+@tab @command{ifconfig} @var{interface} @var{address} @samp{netmask} @var{netmask}
+@item NetBSD
+@tab @command{ifconfig} @var{interface} @var{address} @samp{netmask} @var{netmask}
+@item Solaris
+@tab @command{ifconfig} @var{interface} @var{address} @samp{netmask} @var{netmask}
+@item Darwin (MacOS/X)
+@tab @command{ifconfig} @var{interface} @var{address} @samp{netmask} @var{netmask}
+@item Windows
+@tab @command{netsh interface ip set address} @var{interface} @samp{static} @var{address} @var{netmask}
+@end multitable
+
+For IPv6 addresses:
+
+@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@item Linux
+@tab @command{ifconfig} @var{interface} @samp{add} @var{address}@samp{/}@var{prefixlength}
+@item FreeBSD
+@tab @command{ifconfig} @var{interface} @samp{inet6} @var{address} @samp{prefixlen} @var{prefixlength}
+@item OpenBSD
+@tab @command{ifconfig} @var{interface} @samp{inet6} @var{address} @samp{prefixlen} @var{prefixlength}
+@item NetBSD
+@tab @command{ifconfig} @var{interface} @samp{inet6} @var{address} @samp{prefixlen} @var{prefixlength}
+@item Solaris
+@tab @command{ifconfig} @var{interface} @samp{inet6 plumb up}
+@item
+@tab @command{ifconfig} @var{interface} @samp{inet6 addif} @var{address} @var{address}
+@item Darwin (MacOS/X)
+@tab @command{ifconfig} @var{interface} @samp{inet6} @var{address} @samp{prefixlen} @var{prefixlength}
+@item Windows
+@tab @command{netsh interface ipv6 add address} @var{interface} @samp{static} @var{address}/@var{prefixlength}
+@end multitable
+
+On Linux, it is possible to create a persistent tun/tap interface which will
+continue to exist even if tinc quit, although this is normally not required.
+It can be useful to set up a tun/tap interface owned by a non-root user, so
+tinc can be started without needing any root privileges at all.
+
+@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@item Linux
+@tab @command{ip tuntap add dev} @var{interface} @samp{mode} @var{tun|tap} @samp{user} @var{username}
+@end multitable
+
+@c ==================================================================
+@node Routes
+@section Routes
+
+In some cases it might be necessary to add more routes to the virtual network
+interface. There are two ways to indicate which interface a packet should go
+to, one is to use the name of the interface itself, another way is to specify
+the (local) address that is assigned to that interface (@var{local_address}). The
+former way is unambiguous and therefore preferable, but not all platforms
+support this.
+
+Adding routes to IPv4 subnets:
+
+@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@item Linux
+@tab @command{route add -net} @var{network_address} @samp{netmask} @var{netmask} @var{interface}
+@item Linux iproute2
+@tab @command{ip route add} @var{network_address}@samp{/}@var{prefixlength} @samp{dev} @var{interface}
+@item FreeBSD
+@tab @command{route add} @var{network_address}@samp{/}@var{prefixlength} @var{local_address}
+@item OpenBSD
+@tab @command{route add} @var{network_address}@samp{/}@var{prefixlength} @var{local_address}
+@item NetBSD
+@tab @command{route add} @var{network_address}@samp{/}@var{prefixlength} @var{local_address}
+@item Solaris
+@tab @command{route add} @var{network_address}@samp{/}@var{prefixlength} @var{local_address} @samp{-interface}
+@item Darwin (MacOS/X)
+@tab @command{route add} @var{network_address}@samp{/}@var{prefixlength} @var{local_address}
+@item Windows
+@tab @command{netsh routing ip add persistentroute} @var{network_address} @var{netmask} @var{interface} @var{local_address}
+@end multitable
+
+Adding routes to IPv6 subnets:
+
+@multitable {Darwin (MacOS/X)} {ifconfig route add -bla network address netmask netmask prefixlength interface}
+@item Linux
+@tab @command{route add -A inet6} @var{network_address}@samp{/}@var{prefixlength} @var{interface}
+@item Linux iproute2
+@tab @command{ip route add} @var{network_address}@samp{/}@var{prefixlength} @samp{dev} @var{interface}
+@item FreeBSD
+@tab @command{route add -inet6} @var{network_address}@samp{/}@var{prefixlength} @var{local_address}
+@item OpenBSD
+@tab @command{route add -inet6} @var{network_address} @var{local_address} @samp{-prefixlen} @var{prefixlength}
+@item NetBSD
+@tab @command{route add -inet6} @var{network_address} @var{local_address} @samp{-prefixlen} @var{prefixlength}
+@item Solaris
+@tab @command{route add -inet6} @var{network_address}@samp{/}@var{prefixlength} @var{local_address} @samp{-interface}
+@item Darwin (MacOS/X)
+@tab ?
+@item Windows
+@tab @command{netsh interface ipv6 add route} @var{network address}/@var{prefixlength} @var{interface}
+@end multitable
+
+@c ==================================================================
+@node Automatically starting tinc
+@section Automatically starting tinc
+
+@menu
+* Linux::
+* Windows::
+* Other platforms::
+@end menu
+
+@c ==================================================================
+@node Linux
+@subsection Linux
+
+@cindex systemd
+There are many Linux distributions, and historically, many of them had their
+own way of starting programs at boot time. Today, a number of major Linux
+distributions have chosen to use systemd as their init system. Tinc ships with
+systemd service files that allow you to start and stop tinc using systemd.
+There are two service files: @samp{tinc.service} is used to globally enable or
+disable all tinc daemons managed by systemd, and
+@samp{tinc@@@var{netname}.service} is used to enable or disable specific tinc
+daemons. So if one has created a tinc network with netname @samp{foo}, then
+you have to run the following two commands to ensure it is started at boot
+time:
+
+@example
+systemctl enable tinc
+systemctl enable tinc@@foo
+@end example
+
+To start the tinc daemon immediately if it wasn't already running, use the
+following command:
+
+@example
+systemctl start tinc@@foo
+@end example
+
+You can also use @command{systemctl start tinc}, this will start all tinc daemons
+that are enabled. You can stop and disable tinc networks in the same way.
+
+If your system is not using systemd, then you have to look up your
+distribution's way of starting tinc at boot time.
+
+@c ==================================================================
+@node Windows
+@subsection Windows
+
+On Windows, if tinc is started with the @command{tinc start} command without using
+the @option{-D} or @option{--no-detach} option, it will automatically register
+itself as a service that is started at boot time. When tinc is stopped using
+the @command{tinc stop} command, it will also automatically unregister itself.
+Once tinc is registered as a service, it is also possible to stop and start
+tinc using the Windows Services Manager.
+
+@c ==================================================================
+@node Other platforms
+@subsection Other platforms
+
+On platforms other than the ones mentioned in the earlier sections, you have to
+look up your platform's way of starting programs at boot time.
+
+@c ==================================================================
+@node About us
+@chapter About us
+
+
+@menu
+* Contact information::
+* Authors::
+@end menu
+
+
+@c ==================================================================
+@node Contact information
+@section Contact information
+
+@cindex website
+Tinc's website is at @url{https://www.tinc-vpn.org/},
+this server is located in the Netherlands.
+
+@cindex IRC
+We have an IRC channel on the FreeNode and OFTC IRC networks. Connect to
+@uref{https://freenode.net/, irc.freenode.net}
+or
+@uref{https://www.oftc.net/, irc.oftc.net}
+and join channel #tinc.
+
+
+@c ==================================================================
+@node Authors
+@section Authors
+
+@table @asis
+@item Ivo Timmermans (zarq)
+@item Guus Sliepen (guus) (@email{guus@@tinc-vpn.org})
+@end table
+
+We have received a lot of valuable input from users. With their help,
+tinc has become the flexible and robust tool that it is today. We have
+composed a list of contributions, in the file called @file{THANKS} in
+the source distribution.