# Installation

Instructions for installing soratun tool.

Soratun can be installed by simply downloading the latest release to your device and extracting the archive. Soratun also includes a built-in WireGuard client implementation based on the official [wireguard-go](https://git.zx2c4.com/wireguard-go/) library, so there is no need to separately install the WireGuard implementation for your platform.

## Installing Soratun

1. Download the latest [release](https://github.com/soracom/soratun/releases) for your platform from the [Soratun Github repository](https://github.com/soracom/soratun/):

   ```bash
   wget https://github.com/soracom/soratun/releases/download/v1.1.0/soratun_1.1.0_linux_armv7.tar.gz
   ```

2. Extract the archive:

   ```bash
   tar xvf soratun_1.1.0_linux_armv7.tar.gz
   ```

3. Copy the executable file `soratun` to `/usr/local/bin`:

   ```bash
   cd soratun_1.1.0_linux_armv7
   sudo cp soratun /usr/local/bin
   ```

You should now be able to run the `soratun` command. To check, you can run `soratun version` to verify that the command runs properly:

```bash
soratun version

{"revision":"2f52b9770f7684d9dbd0ebe6ff17c01a0804b5e6","version":"1.1.0"}
```

## Bootstrapping

Once you have installed Soratun, you can proceed to bootstrapping your device based on the bootstrap method you want to use:

- [Bootstrap with AuthKey](https://docs.soracom.io/en/services/arc/soratun/authkey-bootstrapping) authentication
- [Bootstrap with Cellular](https://docs.soracom.io/en/services/arc/soratun/cellular-boostrapping) authentication
- [Bootstrap with SIM](https://docs.soracom.io/en/services/arc/soratun/sim-bootstrapping) authentication

> [!NOTE]
>
> If you are bootstrapping with SIM authentication, you will also need to install Krypton CLI on your device. Refer to the [Bootstrap with SIM](https://docs.soracom.io/en/services/arc/soratun/sim-bootstrapping) documentation for more information.

For more information on the differences between each bootstrap method, refer to the [Soratun Overview](https://docs.soracom.io/en/services/arc/soratun) documentation.

Once you have finished bootstrapping your device, a **Soratun configuration file** will be created at the location specified with the `--config` flag, or in a file `arc.json` in the current directory if the `--config` flag is not specified.

### Manual Configuration

If you prefer to create a Virtual SIM from the Soracom User Console or using the Soracom API or CLI, you can create the **Soratun configuration file** manually by running `soratun config`. This will output a Soratun configuration file template, which you can then save to a file `arc.json` in the current directory, and then edit the file with the WireGuard configuration details provided by Arc when creating a Virtual SIM.

For more information, refer to the [Connection](https://docs.soracom.io/en/services/arc/connection) section.

## Configuring systemd

While Soratun can be run as a standalone process by simply running the `soratun` command from your device or application, you can also run it as a daemon process by configuring [systemd](https://www.freedesktop.org/wiki/Software/systemd/). This will allow your system to start Soratun automatically, and restart it in the event of connection loss or error.

To configure `systemd`, you will need to provide a configuration file. A sample configuration file is provided in the Soratun archive at `/conf/soratun.service.sample`.

1. Open the `/conf/soratun.service.sample` file.

   ```bash
   nano conf/soratun.service.sample
   ```

2. Adjust any settings as needed. At a minimum, you will likely need to change the `ExecStart=` parameter to match the path where you installed `soratun`, as well as the path of your Soratun configuration file:

   ```ini
   [Unit]
   Description=soratun
   Documentation=https://users.soracom.io/
   Requires=network-online.target
   After=network-online.target

   [Service]
   Type=simple
   ExecStart=/usr/local/bin/soratun up --config /path/to/arc.json
   Restart=always
   StandardOutput=journal
   StandardError=journal
   SyslogIdentifier=soratun
   SyslogFacility=local7
   WatchdogSec=120

   [Install]
   WantedBy=multi-user.target
   ```

> [!NOTE]
>
> When specifying the Soratun configuration file path, make sure to use the absolute file path in order to avoid path variable problems.

3. Copy the configuration file to the `systemd` configuration directory:

   ```bash
   sudo cp conf/soratun.service.sample /etc/systemd/system/soratun.service
   ```

4. Enable and start the daemon:

   ```bash
   sudo systemctl enable soratun
   sudo systemctl start soratun
   ```

The usual `systemd` commands are available:

- `sudo systemctl stop soratun` - Stop the `soratun` daemon
- `sudo systemctl status soratun` - Check the status of the `soratun` daemon
- `journalctl -u soratun` - Check the `soratun` daemon logs

### Watchdog

Soratun also supports the `systemd` watchdog. It reports the connection uptime to `systemd` approximately every 110 seconds, based on the following timer:

[Protocol & Cryptography - WireGuard](https://www.wireguard.com/protocol/)

After receiving a packet, if the receiver was the original initiator of the handshake and if the current session key is `REKEY_AFTER_TIME - KEEPALIVE_TIMEOUT - REKEY_TIMEOUT` ms old, we initiate a new handshake.

In the example `systemd` configuration file, watchdog is configured with a default timeout of 120 seconds. If the Arc session is disconnected, or if Soratun stops for some reason, `systemd` will restart Soratun after a maximum of 120 + 110 seconds.

> [!NOTE]
>
> Although you can configure the `WatchdocSec=` parameter for a timeout duration shorter than 120 seconds, this may result in `systemd` restarting the Soratun daemon, even if there is no problem.

To disable watchdog from automatically restarting the Soratun daemon, simply delete the `WatchdogSec=` parameter.

## Running as a Non-Root User

Since Soratun will perform network-related operations on your device, you typically need to provide root privileges with `sudo` in order to run most commands.

On Linux, you can run the `soratun` command as a non-root user by providing `CAP_NET_ADMIN` privileges to a group, and adding the non-root user to that group. For more information, refer to [capabilities(7)](https://man7.org/linux/man-pages/man7/capabilities.7.html): `CAP_NET_ADMIN`.

1. Create a group such as `wg`:

   ```bash
   sudo groupadd wg
   ```

2. Add the user that will run Soratun to the group. For example, if your user is `pi`, the following command will add the user to the `wg` group:

   ```bash
   sudo usermod -a -G wg pi
   ```

3. Finally, add `CAP_NET_ADMIN` to the `soratun` executable, making sure to use the path where you installed `soratun`:

   ```bash
   sudo setcap cap_net_admin+epi /usr/local/bin/soratun
   ```

4. When Soratun runs, it will store socket connection files in the following directory. First, create the directory to ensure that it exists:

   ```bash
   sudo mkdir -p /var/run/wireguard
   ```

5. Finally, change the group associated with the directory:

   ```bash
   sudo chgrp wg /var/run/wireguard
   ```

Once you log out and log in again, your user will be able to run `soratun` without `sudo`:

```bash
soratun up
```

> [!NOTE]
>
> On some systems, the `/var/run/wireguard` directory may be deleted when the device is rebooted. If this occurs, you may need to implement a mechanism to automatically create the directory and set its group (steps 4 and 5) on boot.

## Uninstalling Soratun

To uninstall Soratun:

1. If `soratun` is already running, stop it:

   - If you are running `soratun` as a foreground process, press `Ctrl-C`.
   - If you are running `soratun` as a background process, send `SIGTERM` to the `soratun` process with the `kill` command.
   - If you are running `soratun` as a daemon of systemd, use the command `sudo systemctl stop soratun`.

2. If you configured `systemd`, remove the systemd configuration file (default: `/etc/systemd/system/soratun.service`)

3. Remove the following files:

   - The `soratun` executable
   - Your Soratun configuration file (for example: `/path/to/arc.json`)
   - If you used the SIM authentication bootstrapping method, remove the additional Krypton CLI files

4. Reboot your device.