Document how invitation files work.

This should eventually be merged in to tinc.texi.

diff --git a/doc/INVITATIONS b/doc/INVITATIONS
new file mode 100644 (file)
index 0000000..a75e39c
--- /dev/null
+++ b/doc/INVITATIONS
@@ -0,0 +1,87 @@
+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.