Troubleshooting

Start from what you see, then follow the checks in order. Most problems come down to one of four things: the device isn’t signed in, the access policy doesn’t allow the connection, a route hasn’t been approved or accepted, or DNS settings on the device. The commands below run in a terminal (PowerShell on Windows).

Three commands that answer most questions#

# Is this device connected, and which devices can it see?
$ txhub status
# Can I reach that device, and is the path direct or relayed?
$ txhub ping <device name>
# How is this device resolving names?
$ txhub dns status

I can’t sign in#

• “No network access yet”: your sign-in worked, but you aren’t a member of any TxNet. Ask an admin to add or invite you.
• Your password is refused: if your company uses single sign-on, sign in with your work account instead. A password never works on an SSO address. If you forgot your password, an admin can set a new one.
• Your authenticator code is refused: check that your phone sets its clock automatically, or use a recovery code. An admin can reset two-factor authentication for you.

Details are on the Sign-in and SSO page.

My device doesn’t appear in the dashboard#

1. Make sure you finished signing in in the browser and saw You’re connected. If the page asked you to choose a TxNet, check you picked the right one.
2. Run txhub status on the device. If it isn’t signed in, sign in again: Log In… in the app, or sudo txhub up on Linux.
3. If you saw “You have reached your machine limit”, remove a device you no longer use or ask an admin to raise your limit.
4. If you used an enrollment key, check it hasn’t expired and, for a single-use key, that it wasn’t already used. Create a new one if in doubt.

A device shows as offline#

• Check the device is switched on, online and that the TxHub app is running. On macOS and Windows, the app shows when the background service isn’t running and offers to start it.
• Look at Last Seen in Machines to see when it last checked in.
• If the machine shows Expired, its sign-in has expired or an admin used Expire key. Sign in again on that device. The machine’s page shows its Key expiry.
• On Linux, check the service: systemctl status txhubd.

I can’t reach another device#

1. Run txhub status. The other device must be in the list. If it isn’t, the access policy doesn’t let you reach it, or it belongs to another TxNet.
2. Run txhub ping <device name>. A reply means the network path works. If ping works but your app doesn’t, the port is probably not allowed, or the service on the other device isn’t listening.
3. Ask an admin to check the access policy. In Settings → Access policy, Test this policy shows which rule allows or blocks the connection, including the port.
4. Remember that a tagged device is only matched by tag: rules, not by rules that name its owner.
5. Check the other device isn’t offline or expired (see above).
6. Check the firewall on the other device allows the service you are trying to use.

Names don’t resolve#

Each device gets a name such as laptop.acme.tx.net. If a name doesn’t work but the TxNet IP address does, the problem is DNS.

1. Run txhub dns status to see whether this device uses TxHub’s DNS settings, and which names and servers it knows about.
2. Make sure the device accepts DNS settings from TxHub. This is on by default. To turn it back on:

   $ sudo txhub set --accept-dns=true

3. Try the full name (laptop.acme.tx.net) instead of the short one. You can check a name directly with txhub dns query laptop.acme.tx.net.
4. Flush your computer’s DNS cache, then try again.

# macOS
$ sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
# Windows
$ ipconfig /flushdns
# Linux with systemd-resolved
$ resolvectl flush-caches

A subnet route, exit node or application isn’t used#

Subnet routes

• An admin must approve the route first: open the device in Machines and, under Subnet Routes, click Approve. Until then the device shows Subnets (pending).
• Your device must accept routes. On Windows this is on by default. On macOS turn on Use Subnet Routes in the TxHub menu. On Linux run:

  $ sudo txhub set --accept-routes

• The access policy must allow you to reach the route’s addresses.

See Subnet routes.

Exit nodes

• An admin must enable the exit node on the device’s page (Enable Exit Node). Until then it shows Exit Node (pending).
• You must pick it on your device: in the app menu, or with sudo txhub set --exit-node=<name>.
• If your TxNet has an access policy, a rule must allow autogroup:internet.

See Exit nodes.

Applications

Check the application and its gateway machine under Settings → Applications. The gateway must be online and have Application gateway turned on in its app (or sudo txhub set --advertise-connector on Linux). See Applications.

The connection is slow#

TxHub tries to connect devices directly. When a network blocks that, traffic goes through one of TxHub’s relay servers. It still works and is still encrypted, but it can be slower.

1. Run txhub status. Each device shows direct with an address when the path is direct, or relay with a relay name when it is relayed.
2. Run txhub ping <device name>. The first replies often go through a relay while a direct path is found. Each reply says which path it took.
3. Run txhub netcheck to see what your network allows (UDP, NAT type) and how far the nearest relay server is.

Strict corporate or guest networks often block the UDP traffic needed for direct connections. Try another network to compare. If you use an exit node, all your internet traffic also goes through that machine, so its speed and distance matter.

Windows SmartScreen warns when I install#

The Windows installer isn’t code-signed yet, so Windows SmartScreen may show “Windows protected your PC”. Click More info, then Run anyway. Only do this for an installer you downloaded from TxHub. See Install the app.

Where to find logs#

• Windows: open the TxHub tray menu, open Advanced and click View logs.
• macOS: in the TxHub menu, open Advanced and choose View Daemon Logs… (the background service, /var/log/txhubd.log) or View App Log… (the menu-bar app, in ~/Library/Logs/TXHub).
• Linux: the service logs to the system journal.

$ journalctl -u txhubd -f

Still stuck?#

Email info@txhub.is. To help us help you quickly, include:

• What you were trying to do, and what happened instead.
• The device’s operating system and TxHub version (txhub version).
• The output of txhub status and, for connection problems, txhub netcheck.
• Recent log lines from the time of the problem.