Tinc App

This troubleshooting guide is a generic checklist which should help the reader identifying and solving the most common connectivity issues that may arise at multiple levels during the setup of a tinc VPN using Tinc App and an external node. The following steps and the different testing instructions should be followed in order of appearance. Commands can be executed on Android using a terminal emulator such as Termux.


System network configuration review

This section is focused on the configuration of the network interface and routes on the host systems. The goal is to make sure that network packets are correctly being passed from the OS to the tinc VPN.

On Android

network.conf should contain:

  • at least one single (not a range) IP address with a prefix length of /32 for IPv4 or /64 for IPv6
$ ip address | grep tun                 ->  should display the IP address assigned to the VPN interface
  • one or multiple routes covering the addresses of the nodes within the VPN address space
$ ip route get $otherNodeVpnAddress     ->  should show the VPN interface

On other systems

The network interface and routes should properly be configured statically or using hook scripts in order to:

  • have at least one IP address assigned to the VPN interface
$ ip address | grep tun                 ->  should display the IP address assigned to the VPN interface
  • have packets addressed to the nodes within the VPN address space routed to the VPN interface
$ ip route get $otherNodeVpnAddress     ->  should show the VPN interface
  • have other packets routed to the physical network interface(s) outside of the VPN, if no discrimination method like network namespaces or packet marking is being used to avoid feeding back encrypted VPN traffic to itself
$ ip route get $someIpNotInVpn          ->  should show a different network interface

Tinc configuration review

This section is focused on the configuration of the tinc daemon and the different nodes of the VPN.

It is important to replicate tinc's host configuration files located in the hosts/ directory across all nodes, keeping them in sync manually until the VPN has been successfully set-up.

External node reachability

The tinc daemons running on the different nodes should be able to establish connections between each other ones through the public Internet.

  • A roaming node on a mobile connection with no fixed public IP address should be able to reach another anchor node, whose public IP address or hostname should be present in its corresponding tinc host file.
$ echo "hi" | nc $anchorNodePublicIp $remoteTincPort    ->  should reply with the anchor's node name
  • Connections to anchor nodes should be explicitely requested by setting AutoConnect to yes or one or more ConnectTo directives in the roaming node's tinc.conf file.
  • An Android node running Tinc App should listen for incoming connections on an unpriviledged port instead of the standard one (655). This is done by setting the Port parameter to either 0 or a random port number above 1024 in the node's host file.
  • It is also recommended to enable LocalDiscovery in tinc.conf in order to allow nodes to detect peers located on the same local network.

Remote nodes should have the "reachable" status in the "Nodes" tab on the Android application's connection status screen. This can also be verified from other nodes through the following command: tinc -n $netname info $otherNodeName.

Internal node reachability

The different nodes should be able to communicate within the tinc VPN using their IP addresses belonging to the address space of the private network. The packets must be correctly routed from nodes to nodes within the mesh network using correct subnets delegations.

  • Each node host file should contain at least one Subnet parameter identical to or covering its VPN IP address. There should be no ambiguous or conflicting Subnet rules within the network.

The ownership of the subnets, shown in the "Subnets" tab on the Android application's connection status screen or the $ tinc -n $netname dump subnets command on other systems, should be coherent with the IP addresses assigned to the network interfaces of the nodes within the VPN.

  • Each node should be able to send ping requests and receive responses to and from any other node in the VPN address space.
$ ping $otherNodeVpnIpAddress   -> should receive responses