Soracom Arc

Installation

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 library, so there is no need to separately install the WireGuard implementation for your platform.

Installing Soratun

  1. Download the latest release for your platform from the Soratun Github repository:

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

  2. Extract the archive:

    tar xvf soratun_1.1.0_linux_armv7.tar.gz

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

    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:

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:

For more information on the differences between each bootstrap method, refer to the Soratun Overview 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 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. 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.

    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:

    [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

    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:

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

  4. Enable and start the daemon:

    sudo systemctl enable soratun
sudo systemctl start soratun

The usual systemd commands are available:

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

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.

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): CAP_NET_ADMIN.

  1. Create a group such as wg:

    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:

    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:

    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:

    sudo mkdir -p /var/run/wireguard

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

    sudo chgrp wg /var/run/wireguard

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

soratun up

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.