Joining or creating a new
network
This short guide explains how to generate an initial
configuration for the new node, generating new private keys on the
device itself.
Step 1:
Bootstrapping the node configuration
A new network and node configuration can be generated by using
the “Generate node
configuration and keys” link on the application’s configuration screen. This
will generate new public and private key pairs for the current node
as well as configuration file templates that can now be
customised.
Step 2: Configuring the
tinc node
The configuration files are located in the application’s networks
configuration directory, which can be accessed through the links on the app’s configuraton
screen.
This directory can be browsed using the system’s built-in file
manager, or alternatively Ghost
Commander. The configuration text files can be edited directly
on the device using third-party text editor apps such as Editor
or Acode.
The paths in the rest of this quickstart guide are relative to
that directory.
2.1. Network interface
configuration
The network interface configuration is specified in
network.conf. A minimal configuration specifying an IP
address for the node and a network prefix for the VPN can be as
short as follows:
networks/$netname/network.conf:
# Assign an IP address to this node:
Address = 10.0.0.100/32
# Route local traffic for the 10.0.0.x prefix to the VPN:
Route = 10.0.0.0/24
2.2. tinc node configuration
The generated host file corresponding to the current tinc node
also needs to be edited to make tinc route the traffic from other
nodes back to this node.
networks/$netname/hosts/$nodename:
# ... other automatically generated configuration parameters ...
# Let tinc route traffic for this node's IP address to this node:
Subnet = 10.0.0.100/32
Step 3: Replicating node
host files
To allow this node to communicate with other ones in the tinc
virtual private network, its node host file
(networks/$netname/hosts/$nodename) needs to be copied
to the hosts directory of other nodes. Reciprocally,
other node host files need to be replicated to the local node’s
networks/$netname/hosts/ directory.
Other nodes can be given a publicly reachable
Address in their corresponding host file to allow
connections to be established. It is also possible to rely on
LocalDiscovery if they’re on the same network.
Quite Easily Done.
Joining a network via
invitation URL
A network can be joined using a tinc 1.1 invitation URL. The node
and its network interface configuration files are automatically
created from the data received from the server. Key pairs are also
automatically generated and exchanged with the inviting server.
Step 1: Generating an
invitation
An invitation can be generated by using the following command on
the “server” side:
$ tinc -n <netname> invite [nodename]
An IP address and some routes can be added to the generated
invitation file with the Ifconfig and
Route parameters:
Name = client
Netname = vpn
ConnectTo = server
Ifconfig = 10.0.0.100/32
Route = 10.0.0.0/24
#-------------------------------------#
Name = server
Ed25519PublicKey = ...
Address = server.example.com
Step 2: Joining using
the invitation
The network can be joined from the configuration screen, by
tapping on “Join network
via invitation URL” and pasting the invitation URL in the
appearing input dialog. This will write the node and network
configuration files, as well as the generated keys into the tinc
network’s configuration directory.
Quite Easily Done.
Migrating from
another tinc Android apps
It is possible to migrate from other Android ports of tinc to
Tinc Mesh VPN while keeping an existing tinc network
configuration with some adjustments, provided that the underlying
tinc daemon was operating in router mode using a
tun device.
Step 1: Restoring the
system’s state
All other VPN applications must be stopped before using Tinc
Mesh VPN, regardless of whether they are using the Android VPN
API. It is recommended to disable any autostart option in the former
ones.
Some applications (such as Vilbrekin’s Tinc GUI) may have
required altering system routing tables to operate correctly. Those
tables must be restored to their original state before using
Tinc Mesh VPN. This can be done simply by rebooting the
device.
Step 2:
Copying the configuration files and keys
An existing tinc network configuration can be imported by copying
it to Tinc Mesh VPN’s networks configuration directory.
This directory is accessible through the links on the app’s configuration
screen. Files can be copied using either Android’s built-in file
manager, or alternatively Ghost
Commander.
Existing files should be copied under
networks/$netname, preserving the previous directory
structure and file names.
Step 3: Adapting the
configuration
The existing configuration files which require adjustments can be
edited on the device itself using third-party text editors such as
Editor
or Acode.
3.1. Adapting the
daemon’s configuration
The tinc daemon configuration file needs to be modified to take
some platform specificities into
account. In particular, the Device,
DeviceType, Interface and
ScriptsInterpreter no longer need to be specified in
tinc.conf.
3.2. Adapting the node’s
configuration
Additionally, an unprivileged port may need to be set in the
current host’s file.
networks/$netname/hosts/$nodename:
# .. other node configuration parameters ...
# Use a port outside of the privileged range,
# because tinc won't run as root anymore.
Port = 1655
3.3. Porting
the network interface configuration
The network interface configuration for IP allocation, route and
DNS servers definition previously done in hook scripts (such as
tinc-up) must converted into parameters in a
declarative network interface definition file, named
network.conf. Available keys are listed in the network interface section of
the manual.
Commands from an example tinc-up file can be
translated into corresponding network.conf parameters
as follows:
Original tinc-up script:
#!/bin/sh
ifconfig $INTERFACE 10.0.0.100
ip route add 10.0.0.0/24 dev $INTERFACE
setprop net.eth0.dns1 10.0.0.1
Equivalent networks/$netname/network.conf:
Address = 10.0.0.100/32
Route = 10.0.0.0/24
DNSServer = 10.0.0.1
Quite Easily Done.
Automating VPN connections
Automatically start VPN on
boot
The VPN can be started automatically on device boot using the
always-on VPN feature available on Android Nougat and
newer.
This option can be enabled through the system settings, under the
“Network & Internet” / “VPN” categories. A tinc network can then
be selected in Tinc Mesh VPN. The chosen one will remain
active across device restart until the user disconnects from it
through the application’s user interface.
Through third-party
apps using Intents
Connections can also be managed from automation and scripting
Android applications (such as LlamaLab Automate,
Tasker or Locale) by using Intents to start or
terminate VPN connections based on time, location, or network
availability for example.
A connection can be initiated by starting an Activity using an
Intent with the following command, replacing $netname
and optionally $passphrase with arbitrary values:
$ am start --user 0 --activity-exclude-from-recents \
-a "org.pacien.tincapp.intent.action.CONNECT" \
-d "tinc:$netname#$passphrase"
Similarly, a currently active connection can be terminated by
starting an Activity with the following command:
$ am start --user 0 --activity-exclude-from-recents \
-a "org.pacien.tincapp.intent.action.DISCONNECT"
Quite Easily Done.