2023-07-30 (v0.38)
The application is shipped with a graphical user interface for convenient network selection, network state monitoring and configuration bootstrapping.
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.
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.
The “network” tab displays a read-only summary of the network interface configuration.
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
.
The “subnets” tab lists the known tinc subnets and their respective owning node.
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.
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.
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.
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.
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.
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
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/
.
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 = …
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:
2
and
10
.
true
, apps may send/receive directly over the underlying
network or any other network they have permissions for.
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
Connections to tinc networks can be initiated and stopped automatically on system startup and from other Android applications.
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.
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.