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

Optional flags:
- --auth-key-id - Your Soracom API AuthKey ID, beginning with keyId-.
- --auth-key: Your Soracom API AuthKey secret, beginning with secret-.
- --coverage-type - The coverage location where you want to create the Virtual SIM (g or jp).

To bootstrap using Cellular authentication, run:

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

Optional flags:
- --endpoint - The Soracom Krypton API endpoint to use for provisioning.

To bootstrap using SIM authentication, run:

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

Optional flags:
- --krypton-cli-path - Path to the krypton-cli command (default: /usr/local/bin/krypton-cli).
- --clear-key-cache - Remove all items from the key cache.
- --disable-key-cache - Do not store authentication results in the key cache.
- --keys-api-endpoint-url - Keys API endpoint URL.
- --provisioning-api-endpoint-url - The Soracom Krypton API endpoint to use for provisioning.
- --params - Additional JSON parameters to pass when making a provisioning request.
- --signature-algorithm - Signature generation algorithm.
- --interface - The UICC interface to use. Valid options:
  - autoDetect (default)
  - iso7816
  - comm
  - mmcli
- --port-name - The port name to use for communicating with the device (such as COM1 or /dev/ttyUSB1).
- --baud-rate - Baud rate to use for communicating with the device.
- --data-bits - Data bits to use for communicating with the device.
- --parity-mode - Parity mode to use for communicating with the device. Valid options:
  - 0 - None (default)
  - 1 - Odd
  - 2 - Even
- --stop-bits - Stop bits to use for communicating with the device.

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:

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.

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 `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`).