+@example
+tinc -n @var{netname} edit tinc-up
+@end example
+
+An example @file{tinc-up} script, that would be appropriate for the scenario in the previous section, is:
+
+@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 "ip addr" commands on Linux, don't forget that it doesn't bring the interface up, unlike ifconfig,
+so you need to add @samp{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 @samp{tinc init} and @samp{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
+ConnectTo = BranchA
+@end example
+
+Note here that the internal address (on eth0) doesn't have to be the
+same as on the VPN interface. 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}:
+
+@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
+ConnectTo = BranchA
+@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
+ConnectTo = BranchC
+@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 keypairs:
+
+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{localstatedir}/run/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 --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.
+
+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.
+
+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 keypair.
+@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 keypair.
+Generate new keypairs 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 @samp{ifconfig -a} and @samp{route -n} (or @samp{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{localstatedir}/run/tinc.@var{netname}.pid}.
+
+@item --help
+Display a short reminder of runtime options and commands, then terminate.
+
+@item --version
+Output version information and exit.
+
+@end table