Command Reference

To show available commands, run soratun help:

soratun help
>soratun -- SORACOM Arc Client
>
>Usage:
>  soratun [command]
>
>Available Commands:
>  bootstrap   Create virtual SIM and configure soratun
>  config      Create initial soratun configuration file without bootstrapping
>  help        Help about any command
>  status      Display SORACOM Arc interface status
>  up          Setup SORACOM Arc interface
>  version     Show version
>  wg-config   Dump soratun configuration file as WireGuard format
>
>Flags:
>      --config string   Specify path to SORACOM Arc client configuration file (default "arc.json")
>  -h, --help            help for soratun

Soratun Commands

For all commands, use the --config flag to specify the location of the Soratun configuration file. If the file does not exist, Soratun will perform the initial bootstrapping process to create a Virtual SIM, and store the resulting Arc connection details in the specified file. If the file already exists, Arc will update the Arc connection details.

If the flag is not specified, Soratun will use a file arc.json in the current working directory.


Bootstrap

Command for performing bootstrapping in order to create a Virtual SIM, or update a Soratun configuration file for an existing Virtual SIM.

For more information on the differences between each bootstrap method, refer to the Soratun Overview documentation.

When bootstrapping, a Virtual SIM will be created which will incur an initial fee. In addition, the Virtual SIM will incur a monthly service fee until the Virtual SIM is terminated. Refer to the Pricing & Fee Schedule for more information.

To bootstrap using AuthKey authentication, run:

soratun bootstrap authkey --config /path/to/arc.json

To bootstrap using Cellular authentication, run:

soratun bootstrap cellular --config /path/to/arc.json

To bootstrap using SIM authentication, run:

soratun bootstrap sim --config /path/to/arc.json

With the exception of the --krypton-cli-path flag, all flags will be passed as parameters to the krypton-cli command.


Config

Command for outputting a sample Soratun configuration file template. When creating a Virtual SIM from the User Console or using the Soracom API/CLI instead of using Soratun bootstrapping, you can use this command to generate a Soratun configuration file, which you can then modify to enter the WireGuard configuration details provided by Arc in the User Console or API/CLI. You can then pass the Soratun configuration file into Soratun using the --config flag to activate the WireGuard connection and connect to Soracom.

The sample configuration will be sent to stdout:

soratun config
>{
>  "privateKey": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
>  "publicKey": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
>  "simId": "890000xxxxxxxxxxxxx",
>  "logLevel": 2,
>  "enableMetrics": true,
>  "interface": "soratun0",
>  "arcSessionStatus": {
>    "arcServerPeerPublicKey": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
>    "arcServerEndpoint": "127.0.0.1:11010",
>    "arcAllowedIPs": [
>      "100.127.0.0/16"
>    ],
>    "arcClientPeerIpAddress": "127.0.0.1"
>  }
>}

You can redirect the output to a file in order to create a file from the sample configuration:

soratun config > /path/to/arc.json

For more details on each of the configuration parameters, refer to the Configuration File section below.


Status

This command displays the status of the WireGuard network interface created by soratun. Requires root user privileges.

sudo soratun status
>Password:
>interface: utun7 (userspace)
>  public key: PXlKD3r5vuPZk4kNatfL6ZPceCjfntWWIqjU9UksoHg=
>  private key: (hidden)
>  listening port: 63066
>
>peer: cx/QH4up20+tgvjr5Ht9kFZUA5BVY1N2m7hY6vP7vVA=
>  endpoint: 123.45.67.89:11010
>  allowed ips: 100.127.0.0/16
>  latest handshake: 2021-06-17 13:30:20.186527 +0900 JST
>  transfer: 92 B received, 180 B sent

If soratun is not running, the following message will be displayed.

sudo soratun status
>no SORACOM Arc device found

Up

This command activates a WireGuard network interface using the Soratun configuration file and configures the system's network routing table. Requires root user privileges.

sudo soratun up --config /path/to/arc.json
>
>DEBUG: (soratun0) 2021/06/17 14:37:03 device started
>...
>DEBUG: (soratun0) 2021/06/17 14:37:03 assign IP address: 123.45.67.89
>DEBUG: (soratun0) 2021/06/17 14:37:03 set link up: soratun0
>DEBUG: (soratun0) 2021/06/17 14:37:03 add route: 100.127.0.0/16
>DEBUG: (soratun0) 2021/06/17 14:37:03 Interface up requested
>DEBUG: (soratun0) 2021/06/17 14:37:03 peer(cx/Q…7vVA) - Received handshake response

When Soratun creates a WireGuard network interface, it will create a socket file at the path /var/run/wireguard/<INTERFACE-NAME>.sock. Normally this file is deleted when Soratun exists. However, if this file is not deleted correctly, this may prevent Soratun from being able to create the network interface again. If soratun up fails, check the corresponding directory and delete any socket files that correspond to interface names that are not running.

To stop Soratun:


Wg-config

This commands converts a soratun configuration file, specified by the --config flag, to a WireGuard configuration format, and outputs it to standard output. This is useful when you are using soratun for bootstrapping a device only, and want to connect to Soracom Arc with a different WireGuard implementation.

soratun wg-config --config /path/to/arc.json
>[Interface]
>Address = x.x.x.x/32
>PrivateKey = ...
>
>[Peer]
>PublicKey = ...
>AllowedIPs = 100.127.0.0/16
>Endpoint = x.x.x.x:11010
>PersistentKeepalive = 60

You can redirect the output directly to a WireGuard configuration file, such as:

soratun wg-config --config /path/to/arc.json > /path/to/wg0.conf

Configuration File

When using Soratun to bootstrap a device for the first time, Soratun will save the WireGuard configuration details in a Soratun configuration file. If the --config flag is used, the configuration file will be saved at the file path specified. Otherwise, the the configuration file will be saved in a file arc.json in the current working directory.

The Soratun configuration file stores connection information in JSON format that Soratun will use to activate a WireGuard connection and connect to Soracom.

If needed, you can modify the Soratun configuration file based on your requirements.

Note that modifying certain properties such as privateKey or arcSessionStatus can result in Soratun being unable to establish a WireGuard connection. If you need to update the connection details, use the soratun bootstrap command that corresponds to your bootstrapping method to update the connection details whenever possible.

Property Type Required Description
enableMetrics Boolean Yes If enabled, metrics will be output to stdout approximately every 60 seconds when the log level is 1 errors only or 2 verbose.
interface String Yes The name of the interface to be created by soratun. On macOS, you must specify a string starting with utun due to OS limitations.
logLevel Integer Yes Log level. Valid options: 0 no output, 1 output errors only, 2 verbose output (errors and debug information).
privateKey String Yes The WireGuard client private key. In most cases, you should not edit this property.
publicKey String Yes The WireGuard client public key. In most cases, you should not edit this property.
additionalAllowedIPs String[] No An array of CIDR blocks to add to WireGuard's AllowedIPs configuration. Traffic to these destinations will also be routed through Soracom.
arcSessionStatus Object (see Arc Session Status below) No Soracom Arc connection information. In most cases, you should not edit this property.
mtu number No MTU for the interface.
persistentKeepalive number No WireGuard PersistentKeepalive for the SORACOM Arc server.
postDown array[] No Array of shell scripts to run after the interface is removed successfully. A script should be in the form ["executable", "param1", "param2"]. To specify the WireGuard interface name as a parameter, use the placeholder %i. The commands are executed in sequential order. For example: "postDown": [ [ "/bin/echo", "postDown", "%i" ], [ "echo", "%i" ] ]
postUp array[] No Array of shell scripts to run after the interface is activated successfully. A script should be in the form ["executable", "param1", "param2"]. To specify the WireGuard interface name as a parameter, use the placeholder %i. The commands are executed in sequential order. For example: "postUp": [ [ "/bin/echo", "postUp", "%i" ], [ "echo", "%i" ] ]
profile Object (see Profile below) No Soracom API connection information. Included only when using AuthKey bootstrapping.
simId String No The SIM ID of the Virtual SIM.

When logLevel is set to 1 (errors only) or 2 (verbose output) and enableMetrics is set to true, Soratun will output the following metrics details approximately every 60 seconds:

soratun_sent_bytes_total{simId="<SIM_ID>",interface="<INTERFACE_NAME>",endpoint="<ARC_ENDPOINT_ADDRESS>"} <NUM_BYTES_SENT>
soratun_received_bytes_total{simId="<SIM_ID>",interface="<INTERFACE_NAME>",endpoint="<ARC_ENDPOINT_ADDRESS>"} <NUM_BYTES_RECEIVED>
soratun_latest_handshake_epoch{simId="<SIM_ID>",interface="<INTERFACE_NAME>",endpoint="<ARC_ENDPOINT_ADDRESS>"} <LAST_HANDSHAKE_TIMESTAMP>

Arc Session Status

The arcSessionStatus object contains Arc connection information that will be used by Soratun to establish a WireGuard connection with Soracom.

In most cases, the parameters will be updated automatically when bootstrapping and creating a Virtual SIM for the first time, or when bootstrapping subsequent times to update the connection details.

Property Type Required Description
arcAllowedIPs String[] Yes An array of CIDR blocks provided by Soracom Arc to add to WireGuard's AllowedIPs configuration.
arcClientPeerIpAddress String Yes IP address of the WireGuard client.
arcServerEndpoint String Yes The endpoint of the Soracom Arc server (format: <IP_ADDRESS_OR_HOSTNAME>:<PORT>).
arcServerPeerPublicKey String Yes The WireGuard server public key.

Profile

The profile object contains the AuthKey information that will be used by Soratun to access the Soracom API when bootstrapping using the AuthKey authentication method.

Property Type Required Description
authKeyId string Yes The Soracom API AuthKey ID to use.
authKey string Yes The Soracom API AuthKey secret to use.
endpoint string Yes The Soracom API endpoint to use (https://g.api.soracom.io or https://api.soracom.io).