# Command Reference Soratun tool command reference. To show available commands, run `soratun help`: ```bash 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](https://docs.soracom.io/en/services/arc/soratun) documentation. > [!WARNING] > > 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](https://docs.soracom.io/en/pricing) for more information. To bootstrap using [AuthKey authentication](https://docs.soracom.io/en/services/arc/soratun/authkey-bootstrapping), run: ```bash 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](https://docs.soracom.io/en/services/arc/soratun/cellular-boostrapping), run: ```bash 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](https://docs.soracom.io/en/services/arc/soratun/sim-bootstrapping), run: ```bash 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`: ```bash 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: ```bash 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. ```bash 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. ```bash 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. ```bash 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/.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. ```bash 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: ```bash 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] > > 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="",interface="",endpoint=""} soratun_received_bytes_total{simId="",interface="",endpoint=""} soratun_latest_handshake_epoch{simId="",interface="",endpoint=""} ``` --- ### 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: `:`). | | `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](https://docs.soracom.io/en/services/arc/soratun/authkey-bootstrapping) 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`). |