User interface

The application is shipped with a graphical user interface for convenient network selection, network state monitoring and configuration bootstrapping.

Start screen

The start screen lists all configured tinc networks within the application’s directory, allowing the user to easily connect to any of those.

Eventual critical errors are also displayed on this screen.

Permission and passphrase entry dialogs may appear upon network selection, if such input is necessary.

Status screen

The status screen automatically opens when a VPN connection to a tinc network is active. It allows the user to visualise the state of the connection in three different tabs described below.

Network information

The “network” tab displays a read-only summary of the network interface configuration.

Node status

The “nodes” tab lists the known tinc nodes and their reachability status.

Tapping on a node displays more detailed information about it, equivalently to running tinc status $node.

Subnet status

The “subnets” tab lists the known tinc subnets and their respective owning node.

Log screen

The log screen shows the activity of the currently running tinc daemon in real time at the “DEBUG” logging level.

It is possible to pause the logging and to scroll through the history, as well as to send the recently logged events to other applications.

Configuration screen

The configuration screen allows the user to run some utility commands to create configuration files.

The actual configuration is done through editing text files and copying tinc hosts files on nodes, like on desktop. No graphical configuration editor is provided.

Tools

Network configuration bootstrapping

The “Generate node configuration and keys” link opens the network creation dialog which allows to bootstrap the configuration of a new node to be part of a new or an existing tinc network.

This tool generates the public and private key pairs of the node as well as templates for the tinc daemon, network interface and hosts configuration files.

An optional passphrase can be specified to encrypt the private keys. It will then be required to connect to said network.

The initial configuration of the daemon, network interface and nodes still require some manual file editing and replicating.

Network joining through invitation

The “Join network via invitation URL” link allows a tinc network to be joined using tinc invitation taking the form of an URL string or a QR code to scan.

A new node configuration is then generated accordingly to the parameters contained within the invitation.

Private key encryption and decryption

The “Encrypt or decrypt private keys” link allows one to specify or remove a passphrase used to encrypt the private keys of a tinc network.

This allows protecting a tinc network with a passphrase which will then be required upon connecting to said network.

Internal path information

The “Internal path info” section of the configuration screens displays the internal path to the configuration and log directories, as well as the path to the tinc daemon executable binary.

The given absolute paths are protected and only accessible to the user on rooted Android devices, on which it is possible to control the tinc daemon through the control socket located within the application’s private directory.

On non-rooted devices, the configuration (1) and log (2) directories are accessible by connecting the device in “USB mass storage mode” to a computer. They are located under [USB storage]/Android/data/org.pacien.tincapp/. The directory tree is as follows:

[USB storage]/Android/data/org.pacien.tincapp/
├── files/
│   └── networks/ ------------------ (1)
│       └── [netname...]/
│           ├── network.conf
│           ├── tinc.conf
│           ├── ed25519_key.priv
│           ├── rsa_key.priv
│           └── hosts/
│               └── [host...]
└── cache/
    └── log/ ----------------------- (2)
        ├── tincapp.log
        └── tinc.[netname].log

Configuration

The configuration directory (1) contains the configuration of tinc networks, each in their own subdirectory (2).

In addition to the tinc daemon configuration file (4) and host configuration files (5), each of those contains a network interface configuration file named network.conf (3).

The overall directory structure is as follows:

[USB storage]/Android/data/org.pacien.tincapp/
└── files/
    └── networks/ ------------------ (1)
        └── [netname...]/ ---------- (2)
            ├── network.conf ------- (3)
            ├── tinc.conf ---------- (4)
            ├── ed25519_key.priv
            ├── rsa_key.priv
            └── hosts/
                └── [host...] ------ (5)

This configuration directory can be accessed from a computer by connecting the device in “USB mass storage mode”, in the directory [USB storage]/Android/data/org.pacien.tincapp/.

tinc daemon

The tinc daemon and networks can be configured as they would be on other platforms through the same files, albeit with some specificities to the Android platform, which are the following:

• The tinc daemon will be unable to listen for incoming connections on the standard port (655). Another unprivileged port (>1023) must therefore be chosen with the Port parameter in the current host’s file in the hosts directory. This is indeed automatically done when generating a new configuration with the tinc control command.

• The underlying virtual networking device is automatically set dynamically by the Android API. Hence, no Device or DeviceType must be set in the configuration.

• This underlying network interface operates on the Internet layer and will only accept IP packets. The tinc daemon must therefore be configured with Mode = router.

• The startup nets.boot file is ignored. Tinc VPN connections can be controlled via Android Intents instead.

• No hook script (i.e. {tinc,host,subnet}-{up,down}) can be executed. Network configuration must be done statically through the network.conf file.

Here’s an example of suitable tinc.conf file:

Name = mymobile
Mode = router
AutoConnect = yes
LocalDiscovery = yes
StrictSubnets = yes
ProcessPriority = low
PingInterval = 2400

And matching tinc host file for the device at hosts/mymobile:

Port = 1655
Subnet = 10.0.0.1/32
Ed25519PublicKey = …

Network interface

The network.conf file is used to configure the network interface, allowing one to set parameters such as the IP address, routes and DNS servers for use. Android applications authorised/forced to use/bypass the VPN can also be specified in this file.

The configuration is applied at VPN connect time, and it is not possible to alter the parameters of the network interface while the VPN is active.

The file consists of assignment lines in the form of Key = value pairs, which can be repeated multiple times in order to specify multiple values. Lines beginning with # are treated as comments.

The configuration keys (exposed from the underlying API) are:

Address = [CIDR formatted IP address]

Adds a network address to the VPN interface. Both IPv4 and IPv6 addresses are supported. At least one address must be set. Adding an address implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN.

Route = [CIDR formatted IP range]

Adds a network route to the VPN interface. Both IPv4 and IPv6 routes are supported. Adding a route implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN.

DNSServer = [IP address]

Adds a DNS server to the VPN connection. Both IPv4 and IPv6 addresses are supported. If none is set, the DNS servers of the default network will be used. Adding a server implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN.

SearchDomain = [domain]

Adds a search domain to the DNS resolver.

AllowApplication = [application package name]

Adds an application that are allowed to access the VPN connection. If this parameter is set, only applications added through this method (and no others) are allowed access. Else, all applications are allowed by default. If some applications are added, other, un-added applications will use networking as if the VPN wasn’t running. A VPN may have only a set of allowed applications OR a set of disallowed ones, but not both.

DisallowApplication = [application package name]

Adds an application that are denied access to the VPN connection. By default, all applications are allowed access, except for those denied through this method. Denied applications will use networking as if the VPN wasn’t running. A VPN may have only a set of allowed applications OR a set of disallowed ones, but not both.

AllowFamily = [2|10]

Allows traffic from the specified address family. By default, if no address, route or DNS server of a specific family (IPv4 or IPv6) is added to this VPN, then all outgoing traffic of that family is blocked. If any address, route or DNS server is added, that family is allowed. This method allows an address family to be unblocked even without adding an address, route or DNS server of that family. Traffic of that family will then typically fall-through to the underlying network if it’s supported. Family must be either AF_INET (for IPv4) or AF_INET6 (for IPv6), for which integer values are respectively 2 and 10.

AllowBypass = [true|false]

Allows all apps to bypass this VPN connection. By default, all traffic from apps is forwarded through the VPN interface and it is not possible for apps to side-step the VPN. If this parameter is set to true, apps may send/receive directly over the underlying network or any other network they have permissions for.

Blocking = [true|false]

Sets the VPN interface’s file descriptor to be in blocking/non-blocking mode. By default, the file descriptor is non-blocking.

MTU = [integer value]

Sets the maximum transmission unit (MTU) of the VPN interface. If it is not set, the default value in the operating system will be used.

ReconnectOnNetworkChange = [true|false]

Forces tinc to immediately reconnect to all uplinks on network change. Enabled by default.

Here’s an example of suitable network.conf file:

Address = 10.0.0.1/32
Route = 10.0.0.0/24
DNSServer = 8.8.8.8
DNSServer = 8.8.4.4
AllowBypass = true
ReconnectOnNetworkChange = true

Automatic connection management

Connections to tinc networks can be initiated and stopped automatically on system startup and from other Android applications.

Always-on VPN

The always-on VPN feature available on Android Nougat and newer allows a tinc network connection to be restored after a device restart. This option can be enabled through the system settings, under the “Network & Internet” / “VPN” categories.

Any necessary passphrase for the current network will be saved and will not be asked for again on connection restoration.

If the VPN is disconnected due to an error or is manually disconnected by the user, a warning notification will be shown until it is reconnected.

Intent API

Tinc App allows connections to be managed through Intents, allowing flexible scripting and automation from third-party applications.

A new connection can be instantiated by starting an activity for the action org.pacien.tincapp.intent.action.CONNECT, alongside with an opaque data URI following the pattern tinc:$netname#$passphrase, where $netname is the name of the tinc network to connect to, and $passphrase an optional passphrase to unlock private keys. Connecting to a tinc network will terminate any other existing VPN connection.

If the system VPN permission has not been already granted or has been revoked, a confirmation dialog will be displayed. If the private keys are encrypted but no passphrase has been provided in the Intent data, an input dialog asking for such passphrase will be displayed as well.

A currently active tinc connection can be terminated by starting an activity for the action org.pacien.tincapp.intent.action.DISCONNECT. Disconnecting through an Intent will not drop the system VPN permission.