From: Guus Sliepen Date: Sat, 16 Apr 2016 20:06:47 +0000 (+0200) Subject: Document how invitation files work. X-Git-Tag: release-1.1pre12~20 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=b2200f216658e07ab4e45592fa7de012a2ed96df;p=oweals%2Ftinc.git 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 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 <>$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.