Quickstart guides

2021-03-28

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 generated configuration files can be accessed by enabling the embedded FTP server on the same screen. An FTP client such as Ghost Commander on Android or the default file manager on a desktop computer can then be used to edit the configuration files located in the /files/networks/$netname folder. The first option conveniently includes a text file editor.

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:

/files/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.

/files/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 (/files/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 /files/networks/$netname/hosts/ directory. This can be done through the FTP access enabled at the previous step. Once the configuration is done, the FTP server can be deactivated.

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 App 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 App, 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 App. 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 in Tinc App by enabling the embedded FTP server through the application’s configuration screen and copying the tinc network configuration directory to [FTP root]/files/networks/$netname. This can be conveniently be done on the device itself through an Android FTP client such as Ghost Commander.

Step 3: Adapting the configuration

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.

/files/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 /files/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 App. 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.