From 6805b157312c1f9adeee0035f540f4cbd63a79fd Mon Sep 17 00:00:00 2001 From: Guus Sliepen Date: Sat, 23 Apr 2016 16:05:41 +0200 Subject: [PATCH] Move documentation of invitations to the manual. --- doc/INVITATIONS | 87 -------------------------- doc/tinc.texi | 158 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 156 insertions(+), 89 deletions(-) delete mode 100644 doc/INVITATIONS diff --git a/doc/INVITATIONS b/doc/INVITATIONS deleted file mode 100644 index a75e39c3..00000000 --- a/doc/INVITATIONS +++ /dev/null @@ -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 <>$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. diff --git a/doc/tinc.texi b/doc/tinc.texi index 8c8c7068..cb50e74a 100644 --- a/doc/tinc.texi +++ b/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 and Wessel Dankers . @@ -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 and Wessel Dankers . @@ -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 <>$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 -- 2.20.1