Move documentation of invitations to the manual.

doc/INVITATIONS

@@ -1,87 +0,0 @@
-Introduction
-------------
-
-Invitations are URLs that encode a tinc server's hostname, port, an ephemeral
-public key and a cookie. This is enough for an invitee to connect to the
-server that generated the invitation, verify that it is indeed connected to the
-right server, and present the cookie to the server as proof that it got the
-invitation. The server then checks whether it has a corresponding invitation
-file in its invitations/ directory. The contents of an invitation file that is
-generated by the "tinc -n vpn invite client" command looks like this:
-
-    Name = client
-    Netname = vpn
-    ConnectTo = server
-    #-------------------------------------#
-    Name = server
-    Ed25519PublicKey = augbnwegoij123587...
-    Address = server.example.com
-
-The file is basically a concatenation of several host config blocks. Each host
-config block starts with "Name = ...".  Lines that look like `#---#` are not
-important, it just makes it easier for humans to read the file.
-
-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 tinc.conf and hosts/client files will be generated; the "tinc
-join" command on the client will automatically separate statements based on
-whether they should be in tinc.conf or in a host config file. Some statements
-are special and are treated differently:
-
-- "Netname" 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.
-
-- (TBI) "Ifconfig" statements are hints for generating a tinc-up script.  The
-  syntax is similar to Subnet statements:
-
-  - "Ifconfig a1:b2:c3:d4:e5:f6" is a MAC address, and hints that the tun/tap
-    interface should get that hardware address.
-  - "Ifconfig 1.2.3.4/16" hints that the tun/tap interface should get IPv4
-    address 1.2.3.4 and netmask 255.255.0.0.
-  - "Ifconfig 1234::5/48" hints that the tun/tap interface shouldg et IPv6
-    address 1234::5 and prefixlength 48.
-
-  Additionally, the following arguments are supported:
-
-  - "Ifconfig dhcp" hints that the tun/tap interface should get an IPv4 address
-    and netmask from DHCP.
-  - "Ifconfig dhcp6" hints that the tun/tap interface should get an IPv6
-    address and netmask from DHCP.
-  - "Ifconfig slaac" hints that the tun/tap interface should get an IPv6
-    address and netmask from SLAAC.  Multiple Ifconfig statements are allowed.
-
-  How a tinc-up script is generated depends on the operating system the client
-  is using.
-
-- (TBI) "Route" statements are similar to "Ifconfig" statements but add routes
-  instead of addresses. These only allow IPv4 and IPv6 routes.
-
-Subsequent host config blocks are copied verbatim into their respective files
-in hosts/. The invitation file generated by "tinc invite" will normally only
-contain two blocks; one for the client and one for the server.
-
-Writing an invitation-created script
-------------------------------------
-
-When an invitation is generated, the "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 aproximately recreates the default invitation file:
-
-    #!/bin/sh
-    
-    cat >$INVITATION_FILE <<EOF
-    Name = $NODE
-    Netname = $NETNAME
-    ConnectTo = $NAME
-    #----------------#
-    EOF
-    
-    tinc export >>$INVITATION_FILE
-
-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.

doc/tinc.texi

@@ -15,7 +15,7 @@
 
 This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
 
-Copyright @copyright{} 1998-2015 Ivo Timmermans,
+Copyright @copyright{} 1998-2016 Ivo Timmermans,
 Guus Sliepen <guus@@tinc-vpn.org> and
 Wessel Dankers <wsl@@tinc-vpn.org>.
 
@@ -43,7 +43,7 @@ permission notice identical to this one.
 @vskip 0pt plus 1filll
 This is the info manual for @value{PACKAGE} version @value{VERSION}, a Virtual Private Network daemon.
 
-Copyright @copyright{} 1998-2015 Ivo Timmermans,
+Copyright @copyright{} 1998-2016 Ivo Timmermans,
 Guus Sliepen <guus@@tinc-vpn.org> and
 Wessel Dankers <wsl@@tinc-vpn.org>.
 
@@ -70,6 +70,7 @@ permission notice identical to this one.
 * Configuration::
 * Running tinc::
 * Controlling tinc::
+* Invitations::
 * Technical information::
 * Platform specific information::
 * About us::
@@ -2600,6 +2601,159 @@ 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 @code{tinc invite} command, which
+generates a relatively short URL which can be given to someone else, who uses
+the @code{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 @code{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 @code{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 @code{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 @code{Name = ...}.  Lines that look like @code{#---#}
+are not important, it just makes it easier for humans to read the file.
+
+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 @code{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 "dhcp", a command will be added to start a DHCP client on the VPN interface.
+If it is the word dhcpv6, it will be a DHCPv6 client.
+If it is "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 @code{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 "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 aproximately 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