Troubleshooting guide

2023-07-30 (v0.38)

End-to-end connectivity testing checklist

This section contains 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 or through the Android Debug Bridge.

It’s always a good idea to watch the logs of the tinc daemon at a verbose level, on multiple nodes, while troubleshooting.

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

1.1. On Android

network.conf should contain:

1.2. On “the other side”

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

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

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

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

Common issues and solutions

The VPN gets disconnected after some time

Different device manufacturers enforce arbitrarily restrictive power management policies that may interfere with the normal operation of the tinc daemon.

If VPN connectivity instability issues are noticed, it is recommended to exclude the application from “Background restrictions”, “Battery optimisations”, and other vendor-specific limitations. Instructions for the major manufacturers are available on dontkillmyapp.com.

Unable to use tethering when the VPN is active

It is still possible to share a mobile connection while the VPN is active. For this, the following option must be set in the network.conf file:

AllowBypass = true

It is worth noting that the shared connection will not be tunneled by default. A third party application or custom firewall rules can be used to share the VPN connection with tethered devices.

Google Play can’t download and update applications

Google Play may have trouble reaching Google’s servers through the VPN in some cases.

As a workaround, an exception can be added to let Google Play bypass the VPN:

DisallowApplication = com.android.vending

Unable to click on “OK” on the system “Connection request” dialog

For safety reasons, Android prevents clicking on system dialogs while another application is creating an overlay.

Such application needs to be disabled before interacting with the confirmation dialog.

Can’t bind to port 655/tcp; Unable to create any listening socket!

The underlying tinc daemon needs to bind a port number greater than 1024 due to standard Linux system restrictions.

Another unprivileged listening port can be set in the tinc host file corresponding to the mobile device:

Port = 1655

Route not shown with route or ip route

Routes are added to an Android-managed routing table, entries from which are not listed by default.

To list entries from all routing tables, use:

$ ip route list table all