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.