tinc-vpn.org Git - tinc/blob - doc/INVITATIONS

   1 Introduction
   2 ------------
   3
   4 Invitations are URLs that encode a tinc server's hostname, port, an ephemeral
   5 public key and a cookie. This is enough for an invitee to connect to the
   6 server that generated the invitation, verify that it is indeed connected to the
   7 right server, and present the cookie to the server as proof that it got the
   8 invitation. The server then checks whether it has a corresponding invitation
   9 file in its invitations/ directory. The contents of an invitation file that is
  10 generated by the "tinc -n vpn invite client" command looks like this:
  11
  12     Name = client
  13     Netname = vpn
  14     ConnectTo = server
  15     #-------------------------------------#
  16     Name = server
  17     Ed25519PublicKey = augbnwegoij123587...
  18     Address = server.example.com
  19
  20 The file is basically a concatenation of several host config blocks. Each host
  21 config block starts with "Name = ...".  Lines that look like `#---#` are not
  22 important, it just makes it easier for humans to read the file.
  23
  24 The first host config block is always the one representing the invitee. So the
  25 first Name statement determines the name that the invitee will get. From the
  26 first block, the tinc.conf and hosts/client files will be generated; the "tinc
  27 join" command on the client will automatically separate statements based on
  28 whether they should be in tinc.conf or in a host config file. Some statements
  29 are special and are treated differently:
  30
  31 - "Netname" is a hint to the invitee which netname to use for the VPN.  It is
  32   used if the invitee did not already specify a netname, and if there is no
  33   pre-existing configuration with the same netname.
  34
  35 - (TBI) "Ifconfig" statements are hints for generating a tinc-up script.  The
  36   syntax is similar to Subnet statements:
  37
  38   - "Ifconfig a1:b2:c3:d4:e5:f6" is a MAC address, and hints that the tun/tap
  39     interface should get that hardware address.
  40   - "Ifconfig 1.2.3.4/16" hints that the tun/tap interface should get IPv4
  41     address 1.2.3.4 and netmask 255.255.0.0.
  42   - "Ifconfig 1234::5/48" hints that the tun/tap interface shouldg et IPv6
  43     address 1234::5 and prefixlength 48.
  44
  45   Additionally, the following arguments are supported:
  46
  47   - "Ifconfig dhcp" hints that the tun/tap interface should get an IPv4 address
  48     and netmask from DHCP.
  49   - "Ifconfig dhcp6" hints that the tun/tap interface should get an IPv6
  50     address and netmask from DHCP.
  51   - "Ifconfig slaac" hints that the tun/tap interface should get an IPv6
  52     address and netmask from SLAAC.  Multiple Ifconfig statements are allowed.
  53
  54   How a tinc-up script is generated depends on the operating system the client
  55   is using.
  56
  57 - (TBI) "Route" statements are similar to "Ifconfig" statements but add routes
  58   instead of addresses. These only allow IPv4 and IPv6 routes.
  59
  60 Subsequent host config blocks are copied verbatim into their respective files
  61 in hosts/. The invitation file generated by "tinc invite" will normally only
  62 contain two blocks; one for the client and one for the server.
  63
  64 Writing an invitation-created script
  65 ------------------------------------
  66
  67 When an invitation is generated, the "invitation-created" script is called (if
  68 it exists) right after the invitation file is written, but before the URL has
  69 been written to stdout. This allows one to change the invitation file
  70 automatically before the invitation URL is passed to the invitee. Here is an
  71 example shell script that aproximately recreates the default invitation file:
  72
  73     #!/bin/sh
  74
  75     cat >$INVITATION_FILE <<EOF
  76     Name = $NODE
  77     Netname = $NETNAME
  78     ConnectTo = $NAME
  79     #----------------#
  80     EOF
  81
  82     tinc export >>$INVITATION_FILE
  83
  84 You can add more ConnectTo statements, and change `tinc export` to `tinc
  85 export-all` for example. But you can also use the script to automatically hand
  86 out a Subnet to the invitee. Note that the script doesn't have to be a shell script,
  87 you can use any language, it just has to be executable.