User documentation

2020-12-17

User interface

The application is shipped with a graphical user interface for convenient network selection, network state monitoring and configuration bootstrapping. It is not meant to replace textual configuration file editing.

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.

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 control the accessibility of the tinc network configuration files, as well as run some utility commands.

It does not provide a graphical user interface for editing the configuration.

Configuration access

The “FTP access” toggle activates and deactivates the embedded FTP server through which the configuration files (1) can be transferred and edited. It also allows the user to retrieve and inspect the generated log files (2). After activation, the randomly initialised credentials and connection port (3) are shown on screen.

The accessible directory is structured as follows:

[FTP root]
├── files/
│   └── networks/ ----------------------------- (1)
│       └── [netname...]/
│           ├── network.conf
│           ├── tinc.conf
│           ├── ed25519_key.priv
│           ├── rsa_key.priv
│           └── hosts/
│               └── [host...]
├── cache/
│   ├── log/ ---------------------------------- (2)
│   │   ├── tincapp.log
│   │   └── tinc.[netname].log
│   └── run/
│       ├── tinc.[netname].pid
│       └── tinc.[netname].socket
└── shared_prefs/
    ├── org.pacien.tincapp.service.xml
    └── org.pacien.tincapp.service.ftp.xml ---- (3)

The FTP server can be reached through both the loopback and external IP addresses of the device. This allows the configuration files to be accessed through any FTP client such as Ghost Commander on Android or FileZilla on a desktop computer.

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.

Those 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.

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:

[FTP root]
└── 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 through an embedded FTP server which can be activated using the FTP access toggle on the configuration screen.

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:

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.

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.