Move documentation of invitations to the manual.
This commit is contained in:
Guus Sliepen
parent
51a0dc5145
commit
6805b15731
2 changed files with 156 additions and 89 deletions
|
|
@ -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 <<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.
|
||||
158
doc/tinc.texi
158
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 <guus@@tinc-vpn.org> and
|
||||
Wessel Dankers <wsl@@tinc-vpn.org>.
|
||||
|
||||
|
|
@ -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 <guus@@tinc-vpn.org> and
|
||||
Wessel Dankers <wsl@@tinc-vpn.org>.
|
||||
|
||||
|
|
@ -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 <<EOF
|
||||
Name = $NODE
|
||||
Netname = $NETNAME
|
||||
ConnectTo = $NAME
|
||||
#----------------#
|
||||
EOF
|
||||
|
||||
tinc export >>$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
|
||||
|
|
|
|||
Loading…
Reference in a new issue