Soracom Air for Cellular

Remote Command

Overview

Remote Command enables downlink communications from the cloud to IoT devices.

Traditionally, cloud-to-device downlink communication has been challenging due to security concerns and network configuration complexities. Remote Command addresses these challenges by accepting SSH or HTTP commands and associated data through the Soracom API, and securely transmitting the commands or data to devices via Soracom's secure private network. This architecture ensures a simple and secure communication channel.

With Remote Command, even legacy IoT devices can seamlessly integrate with the cloud as long as they accept communication over HTTP or SSH. Furthermore, when combined with low-code development environments like Soracom Flux, it enables the creation of more sophisticated IoT systems, such as automatically sending commands to devices triggered by sensor data or cloud-based events.

Comparison with Other Features

Soracom offers multiple options for downlink communication. The table below compares Remote Command with other features:

Use Cases

Remote Command is intended for the following use cases:

Sending HTTP/S Commands to a Device

You can use the Soracom User Console to send commands via HTTP to devices that use IoT SIMs. You can also verify the results in the console.

From the User Console

1. Login to the User Console. From the Menu, open the SIM Management screen.

2. From the list of subscribers, click the for the SIM you want to send an HTTP/S command to.

3. Click the Actions menu, then select Send Command via HTTP/S.

4. Configure the following settings:

   

   Setting	Description
   Protocol	Select the protocol that the device accepts requests on.
   Port	Specify the port number that the device accepts requests on. Example: 80, 443
   Path	Specify the URL path. Do not include the hostname. Example: /path/to/resource
   Method	Select the HTTP method.
   Headers	Add to add multiple HTTP headers.
   Body	If you select POST, PUT, or DELETE in Method, enter the request body to send.

5. Click Send.

   An HTTP request (command) is sent to the device. When the command execution is complete on the device, the HTTP response (command execution result) is displayed.

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "method": "POST",
|        "path": "/command/settings",
|        "port": 6443,
|        "skipVerify": false,
|        "ssl": true,
|        "headers": {
|          "Content-Type": "application/json"
|        },
|        "body": "{\"param1\":\"value1\", \"param2\":\"value2\"}",
|      }' \
|  https://g.api.soracom.io/v1/sims/<SIM_ID>/downlink/http

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "method": "POST",
|        "path": "/command/settings",
|        "port": 6443,
|        "skipVerify": false,
|        "ssl": true,
|        "headers": {
|          "Content-Type": "application/json"
|        },
|        "body": "{\"param1\":\"value1\", \"param2\":\"value2\"}",
|      }' \
|  https://jp.api.soracom.io/v1/sims/<SIM_ID>/downlink/http

Sending SSH Commands to a Device

You can use the Soracom User Console to send commands via SSH to devices that use IoT SIMs. You can also verify the results in the console.

You can use this feature with either a password-based setup or a key-pair setup.

From the User Console with Password

1. Login to the User Console. From the Menu, open the SIM Management screen.

2. From the list of subscribers, click the for the SIM you want to send a SSH command to.

3. Click the Actions menu, then select Send Command via SSH.

4. Configure the following settings:

   

5. Click Send.

   The command will be sent to the device. Once the device finishes executing the command, the result will be displayed.

From the User Console with SSH Key Authentication

1. Login to the User Console. From the Menu, open the SIM Management screen.

2. From the list of subscribers, click the for the SIM you want to send a SSH command to.

3. Click the Actions menu, then select Send Command via SSH.

4. Configure the following settings:

   

5. Click Send.

   The command will be sent to the device. Once the device finishes executing the command, the result will be displayed.

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "username": "username",
|        "port": 22,
|        "authentication": {
|           "type": "publickey",
|           "key": "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABCugi/Kbh\nICu7Nwdn....",
|        },
|        "command": "reboot",
|      }' \
|  https://g.api.soracom.io/v1/sims/<SIM_ID>/downlink/ssh

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "username": "username",
|        "port": 22,
|        "authentication": {
|           "type": "publickey",
|           "key": "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABCugi/Kbh\nICu7Nwdn....",
|        },
|        "command": "reboot",
|      }' \
|  https://jp.api.soracom.io/v1/sims/<SIM_ID>/downlink/ssh

Preparing an SSH Key Pair (Public Key Authentication Only)

Before sending SSH commands via Remote Command, you'll need to prepare an SSH key pair:

Here, we will create public and private key pair files to use for SSH login and save them as follows:

• Public key, id_ed25519.pub: Save it in a designated location on your target device.
• Private key, id_ed25519: Save it in the authentication information store of the Soracom User Console.

1. Create a public/private key pair on your PC from a Linux environment.

   ssh-keygen
   >Generating public/private ed25519 key pair...
   >Enter file in which to save the key (/home/xxxx/.ssh/id_ed25519):

   Follow the instructions on the screen to create a public key (id_ed25519.pub) and private key (id_ed25519).

   If you set a passphrase, specify it when creating a Soracom authentication.

2. Copy the public key, id_ed25519.pub, to your target device.

   Copy the public key using any method you like. From now on, the target device, user name will be referred to as ${user}. Example: pi

   • If you are copying from an environment where you can use Linux ssh-copy-id, etc., to the target device that can be accessed by an IP address (e.g., 192.168.xxx.xxx), run the following command:

   ssh-copy-id -i /PATH/TO/PUBLIC_KEY ${user}@192.168.xxx.xxx

   • If you are copying from an environment where you can use Linux ssh-copy-id to a target device that uses an IoT SIM, you can create an on-demand remote access in Napter even if you are in a remote location by executing the following command. For more information about on-demand remote access in Napter, see Soracom Napter documentation.

   Replace xxxx and xxx-xxx-xxx-xxx.napter.soracom.io with the port number and domain issued by Napter's on-demand remote access.

   ssh-copy-id -i /PATH/TO/PUBLIC_KEY -p xxxx ${user}@xxx-xxx-xxx-xxx.napter.soracom.io

   • Similarly, use scp if you are copying from an environment where Windows is available, run a command like the following:

   scp -P xxxxx /PATH/TO/PUBLIC_KEY ${user}@xxx-xxx-xxx-xxx.napter.soracom.io:/home/${user}/

   In this case, you will also need to access the target device via ssh and move the contents of id_ed25519.pub to the appropriate location.

   ssh -p xxxxx xxx-xxx-xxx-xxx.napter.soracom.io -l ${user}
   |mkdir -p ~/.ssh
   |cat ~/id_ed25519.pub >> ~/.ssh/authorized_keys
   |chmod 600 ~/.ssh/authorized_keys
   |rm ~/id_ed25519.pub

3. Verify that you can log in to the target device using the SSH key pair.

   ssh -p xxxxx xxx-xxx-xxx-xxx.napter.soracom.io -l ${user}

   If you set a passphrase for your key pair, you can log in by entering the passphrase.

4. Register the private key in the Soracom User Console.

   Specifically, register the credentials on the Register credentials screen of the Credentials Store as follows. For information on how to display this screen, see Creating a Credential Set.

   • Authentication Information ID: Enter a name to identify the credentials. For example: Private-Key.
   • Type: Select Private Key (PEM).
   • Private key (PEM): Copy the contents of the private key (id_ed25519).