+@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.
+
+