Install Localtonet from a DEB or RPM package

On this page 9 sections

Before you start
What the package installs
Steps
Download and install the package
Set your AuthToken
Check the configuration
Enable a service
Start a tunnel
Tunnel service or VPN service
How the services run
Read the log
Upgrade
Remove
Troubleshooting
Related pages

The DEB and RPM packages install the Localtonet client together with two systemd services, one for tunnels and one for tunnels plus VPN. The services read your AuthToken from a file and run without a terminal, so the client starts on every boot.

Before you start #

A 64-bit Linux system: the packages exist for x64 and ARM64.
systemd 247 or newer and OpenSSL 3, such as Debian 12, Ubuntu 22.04+ or RHEL 9.
Root access (sudo).
Your AuthToken. Select Copy on the AuthToken card of the Dashboard, or copy a token from My Tokens.

On other distributions, on 32-bit ARM, or when you do not want a system package, use the install script or the archives described in Linux.

What the package installs #

Path	What it is
`/usr/bin/localtonet`	The `localtonet` command.
`/usr/lib/localtonet/`	The client itself.
`/usr/lib/systemd/system/localtonet.service`	The tunnel service.
`/usr/lib/systemd/system/localtonet-vpn.service`	The VPN and tunnel service.
`/etc/localtonet/auth-token`	The token file. Only root can read it. It is installed with the placeholder `DUMMY_AUTH_TOKEN`.

The package is named localtonet. Its dependencies, among them OpenSSL 3, iproute2 (iproute in the RPM), iptables and kmod, are installed by your package manager. Installing the package does not enable or start a service: you set the token first and then enable the service you need.

Steps #

Download and install the package #

Choose the package for your distribution and CPU from the list at the end of this page, then install the downloaded file with apt (DEB) or dnf (RPM). Setup instructions under each package shows the exact commands for that file.
Set your AuthToken #

Edit /etc/localtonet/auth-token as root with a text editor and replace DUMMY_AUTH_TOKEN with your token on a single line. Then make sure that only root can read the file:
Terminal
```
sudo chmod 600 /etc/localtonet/auth-token
```
Check the configuration #
Terminal
```
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
The check reads the token file without connecting. It answers Localtonet headless configuration OK. when the file contains a 33-character token without spaces. It does not ask the Localtonet servers whether the token is valid for your account.
Enable a service #

For tunnels, enable the tunnel service and read its log:
Terminal
```
sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service
```
If this device also joins a VPN network, enable the VPN service instead. See Tunnel service or VPN service.
Start a tunnel #

The token now shows Online under My Tokens. Create and start a tunnel for it in the dashboard, see Quick start.

Tunnel service or VPN service #

Both services run the same client and both serve your tunnels. They differ in the rights they run with. Enable one of them: the two services conflict, and starting one stops the other.

	`localtonet.service`	`localtonet-vpn.service`
Use it for	Tunnels	VPN and tunnels
Runs as	An unprivileged user that systemd creates for the service	root, limited to the network capabilities `CAP_NET_ADMIN` and `CAP_NET_RAW`
TUN module	Not used	Loaded with `modprobe tun` before the client starts
Working directory	`/var/lib/localtonet`	`/var/lib/localtonet-vpn`

To switch a device from the tunnel service to the VPN service:

Terminal

sudo modprobe tun
sudo systemctl disable --now localtonet.service
sudo systemctl enable --now localtonet-vpn.service
sudo journalctl -u localtonet-vpn.service

To switch back, disable localtonet-vpn.service and enable localtonet.service the same way. VPN networks themselves are set up in the dashboard, see VPN Manager.

How the services run #

Behaviour	Details
Headless mode	Both services start `localtonet --headless`. In this mode the client never prompts, and it does not store the token in its own settings.
Token	systemd passes `/etc/localtonet/auth-token` to the service. A service does not start while the file is missing.
Start on boot	An enabled service starts after the network is up.
Restart	systemd restarts the client ten seconds after a failure. It does not restart it when the client stops because of an invalid token file. Fix the file and restart the service yourself.

Read the log #

In headless mode the client writes plain lines to the journal, one per change:

Terminal

sudo journalctl -u localtonet.service -f

Line	Meaning
`Connection: Connected`	The state of the session. Other values are `Connecting` and `Disconnected`.
`AuthTokenName: …`	The name of the token the client signed in with.
`OPEN …`, `ADDED …`	A tunnel that runs on this device, with its public address, protocol and local target.
`STATUS …`	A tunnel changed its status.
`CLOSED …`	A tunnel was stopped or removed.
`Authentication failed: AuthToken was rejected.`	The token in the file is not accepted. Copy it again from My Tokens.

If one of these lines would contain the token, the client writes [redacted] in its place.

Upgrade #

Download the new package and install it the same way as the first time, then restart the service you use. Your token file is preserved.

Tunnel service

sudo systemctl restart localtonet

VPN service

sudo systemctl restart localtonet-vpn.service

Under My Tokens, the Client column shows the version the device last reported and a Need Update badge when a newer one is available.

Remove #

Debian, Ubuntu

sudo apt remove localtonet

Fedora, RHEL

sudo dnf remove localtonet

Removing the package stops and disables both services. The token file is a configuration file, and package managers treat those with care: after the removal, check whether /etc/localtonet/auth-token or a saved copy of it is still there, and delete it if you do not want the token to stay on the machine.

Troubleshooting #

Invalid Localtonet headless configuration. Check the token file or environment settings.

The token file is not usable. Check that /etc/localtonet/auth-token exists, that the placeholder DUMMY_AUTH_TOKEN is gone, and that the file contains only the 33-character token, without spaces and on a single line. Run the check with sudo, because only root can read the file.

The service is enabled but does not run

Run systemctl status localtonet.service. A service does not start while /etc/localtonet/auth-token is missing, and it is not restarted after it stopped because of an invalid token file. Fix the file, run the configuration check, then run sudo systemctl restart localtonet.service.

The log says: Authentication failed: AuthToken was rejected.

The file has the right format but the token is not accepted. Copy the token again from My Tokens, save it to the token file and restart the service.

The tunnel service stopped when I started the VPN service

That is intended. The two services conflict, so systemd stops one when the other starts. The VPN service serves your tunnels as well.

The package does not install on my distribution

The packages need systemd 247 or newer and OpenSSL 3. On older releases the package manager cannot satisfy these dependencies. Use the install script or an archive from the Linux page instead.

LinuxInstall script, archives and the built-in service command. VPN ManagerCreate VPN networks and add devices. Run as a serviceService mode on every platform. CLI referenceHeadless mode and every other option.

The packages are listed below. Select Setup instructions under a package for the commands with its file name.

Linux packages

Installable DEB and RPM packages for x64 and ARM64. Requires systemd 247 or newer and OpenSSL 3, such as Debian 12, Ubuntu 22.04+ or RHEL 9.

Debian / Ubuntu · x64
Setup instructions

1. Install the downloaded package. Open a terminal in the directory containing localtonet-linux-x64.deb.
```
sudo apt install ./localtonet-linux-x64.deb
```
2. Set your AuthToken. Edit /etc/localtonet/auth-token as root and replace DUMMY_AUTH_TOKEN with your token on a single line. Then protect the file and check the configuration:
```
sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
3. Start the service. Once the configuration check succeeds:
```
sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service
```
For VPN, switch to the VPN service:
```
sudo modprobe tun
sudo systemctl disable --now localtonet.service
sudo systemctl enable --now localtonet-vpn.service
sudo journalctl -u localtonet-vpn.service
```
For upgrades, install the new package and run sudo systemctl restart localtonet. Your configuration is preserved.

If you use VPN, restart localtonet-vpn.service instead.
Debian / Ubuntu · ARM64
Setup instructions

1. Install the downloaded package. Open a terminal in the directory containing localtonet-linux-arm64.deb.
```
sudo apt install ./localtonet-linux-arm64.deb
```
2. Set your AuthToken. Edit /etc/localtonet/auth-token as root and replace DUMMY_AUTH_TOKEN with your token on a single line. Then protect the file and check the configuration:
```
sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
3. Start the service. Once the configuration check succeeds:
```
sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service
```
For VPN, switch to the VPN service:
```
sudo modprobe tun
sudo systemctl disable --now localtonet.service
sudo systemctl enable --now localtonet-vpn.service
sudo journalctl -u localtonet-vpn.service
```
For upgrades, install the new package and run sudo systemctl restart localtonet. Your configuration is preserved.

If you use VPN, restart localtonet-vpn.service instead.
Fedora / RHEL · x64
Setup instructions

1. Install the downloaded package. Open a terminal in the directory containing localtonet-linux-x64.rpm.
```
sudo dnf install ./localtonet-linux-x64.rpm
```
2. Set your AuthToken. Edit /etc/localtonet/auth-token as root and replace DUMMY_AUTH_TOKEN with your token on a single line. Then protect the file and check the configuration:
```
sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
3. Start the service. Once the configuration check succeeds:
```
sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service
```
For VPN, switch to the VPN service:
```
sudo modprobe tun
sudo systemctl disable --now localtonet.service
sudo systemctl enable --now localtonet-vpn.service
sudo journalctl -u localtonet-vpn.service
```
For upgrades, install the new package and run sudo systemctl restart localtonet. Your configuration is preserved.

If you use VPN, restart localtonet-vpn.service instead.
Fedora / RHEL · ARM64
Setup instructions

1. Install the downloaded package. Open a terminal in the directory containing localtonet-linux-arm64.rpm.
```
sudo dnf install ./localtonet-linux-arm64.rpm
```
2. Set your AuthToken. Edit /etc/localtonet/auth-token as root and replace DUMMY_AUTH_TOKEN with your token on a single line. Then protect the file and check the configuration:
```
sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
3. Start the service. Once the configuration check succeeds:
```
sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service
```
For VPN, switch to the VPN service:
```
sudo modprobe tun
sudo systemctl disable --now localtonet.service
sudo systemctl enable --now localtonet-vpn.service
sudo journalctl -u localtonet-vpn.service
```
For upgrades, install the new package and run sudo systemctl restart localtonet. Your configuration is preserved.

If you use VPN, restart localtonet-vpn.service instead.

Before you start #

What the package installs #

Steps #

Download and install the package #

Set your AuthToken #

Check the configuration #

Enable a service #

Start a tunnel #