Skip to content

Mass Installation

The manual installation and device registration method described in the getting stated guide is good for one-off installation or if you have got just a few devices to install the SocketXP agent on and register the devices with the SocketXP Cloud IoT Gateway.

For production or mass installation (installing SocketXP agent on a very large number of devices), it is highly recommended to create an OS disk image with SocketXP agent pre-installed in it.

You should clone the OS disk image created to other SD cards or disks, and use the cloned disks to bootup other devices.

Creating a disk image with SocketXP agent installed

In this section, we will explain how to create a disk image with the SocketXP agent installed and configured in it.

Here is the strategy we will follow:

  • Take a fresh device
  • Install the SocketXP agent in the device manually
  • Delete the device.key file from the device file system
  • Add a device registration script to the network interface ifupdown hook
  • Create a disk image of the SD card/disk.
  • Clone the disk image to other SD cards/disks
  • Insert the cloned SD cards/disks into other devices.
  • Boot up the devices with the cloned SD cards/disks.
  • The device registration script will be invoked when the interet connection comes up.
  • The script will try to register the device with the SocketXP Cloud Gateway on the first bootup using an auth-token.
  • A unique device.key file will be download and stored on the each device, automatically, during its first bootup.
  • The script will be self-deleted after a successful device registration.

Install SocketXP Agent

Take a fresh device.

Install the SocketXP agent manually using the single-touch installation script.

At a very high level, the script will install and create the following 5 items in the device:

  • the agent binary
  • a config file
  • a credential file.
  • a systemd service file
  • a log file

Let's go in detail.

The installation script will first download and install the SocketXP agent in the /usr/local/bin/ folder.

It will also create a config.json file in the /etc/socketxp/ folder with the basic SSH remote access configuration in it, as shown below:

{
    "region": "",
    "tunnels" : [
        {
            "destination": "tcp://127.0.0.1:22"
        }
    ]
}

Note:

By default, SocketXP agent will connect to the "US" region gateway. If you want your device to register with the "EU" region gateway, set the "region" flag to "eu" in the above config file.

Update the configuration file to include HTTP web service remote access configuration or any other features you want to enable. Refer to our configuration guide to know more about various configuration options. Make sure the configuration is working fine before you clone the disk image.

The installation script will register the device with the gateway and create a device.key file and a socketxp.log file at /var/lib/socketxp folder. The device.key file will contain a unique device ID and a device key pair allocated by the cloud gateway to uniquely identify the device.

Each device, after a successful registration with the cloud gateway, will be assigned a unique device ID and device key pair which will be downloaded and stored in the device.key file. The device agent will use these credentials to authenticate with the cloud gateway for all future communications.

Warning:

You should NEVER copy over a device.key file from one device to another. If you do so, the first device may be de-registered and disconnected from the SocketXP Cloud Gateway.

So, before you begin to clone a disk and create a disk image, delete the /var/lib/socketxp folder from the device's file system.

sudo rm -rf /var/lib/socketxp

The installation script will next create a systemd service definition file at: /etc/systemd/system/, as shown below:

$ cat /etc/systemd/system/socketxp.service


[Unit]
Description=SocketXP secure IoT remote access service
Requires=network.target
After=network.target

[Service]
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/socketxp --config /etc/socketxp/config.json
ExecStop=/bin/kill -15 $MAINPID
KillMode=process

[Install]
WantedBy=multi-user.target
The installation script will eventually start the socketxp service to run in the background. It will also enable the service to start automatically on boot up.

Create a Device Registration Script

Next, manually create a device registration script in the device file system. 

sudo nano /etc/network/if-up.d/register_device.sh

Copy the following content into it.

#!/bin/bash

AUTH_TOKEN="copy your device registration token here"

# Check if the device.key file exists
if [ -f /var/lib/socketxp/device.key ]; then
  echo "device.key found. Script already run. Exiting." >> /var/log/register_device.log
  exit 0
fi

# Wait for internet connectivity
while ! ping -c 1 google.com > /dev/null 2>&1; do
  echo "Waiting for internet connectivity..." >> /var/log/register_device.log
  sleep 10 # Wait for 10 seconds before retrying
done

echo "Internet connectivity detected." >> /var/log/register_device.log

# Your socketxp login command here (replace with your actual auth token)
echo "Running sudo socketxp login..." >> /var/log/register_device.log
sudo socketxp login $AUTH_TOKEN >> /var/log/register_device.log 2>&1

# Check if the device.key file was successfully created (or login was successful)
if [ ! -f /var/lib/socketxp/device.key ]; then
    echo "Error with socketxp login. device.key not found. Exiting." >> /var/log/register_device.log
    exit 1
fi

# Start the SocketXP service
systemctl start socketxp

echo "First-time setup complete." >> /var/log/register_device.log

# Self-delete the script
rm /usr/local/bin/register_device.sh

echo "Script deleted." >> /var/log/register_device.log

Make sure you update the script with your AUTH_TOKEN. You'll have to login to the SocketXP web portal, visit the Authtoken page and create a new DEVICE_REGISTRATION type token that has a lifetime set according to your needs and security policy.

Warning:

Each authentication token(Advanced Security Auth Token) has an expiry time built into it. The auth token will become invalid automatically after the expiry period.

You also have the option of revoking an auth token from the web portal. It will invalidate the token immediately.

Never use the all-purpose basic-security auth token in your disk image.

Tip:

It is a good security practice to create and use a device-registration token that has a limited lifetime. Release a new disk image at regular intervals with a new token added to it. So that, your operations team or your customers use the new disk image with the new token embedded in it.

Never use/distribute the all-purpose basic-security auth token in your disk image.

The device registration script will be run only the first time the device boots up. After the first successful execution, it will auto delete itself.

The script will be invoked during the device boot up when the network interfaces come up one by one. The script will check if the internet connection is working fine. If not, it will exit. It will be invoked again, when the next "internet reachable" interface comes up.

The script will try to register the device with the SocketXP Cloud Gateway using the "socketxp login" command and the auth token provided. If the registration is successful, a device.key will be downloaded to the /var/lib/socketxp folder in the device.

The script will check if the /var/lib/socketxp/device.key file is created. If the file is not found, the script will exit and retry during the next bootup.

If the file is found, the script will start the socketxp service to run in the background.

Finally, the script will self-delete itself from the device's file system and exit. This will avoid the script from re-registering the device, unnecessarily, during subsequent boot ups.

Alternate Method:

An alternate approach to device registration on boot up would be to create a systemd service file for the device registration script and configure the service to start running the script on bootup. This way, the device registration process will not only be retried once during each boot-up, but continuously (according to the RestartSec setting in the service file) after the bootup.

Again, the device registration script should stop the script service and delete the systemd service file for the script, after a successful device registration.

Create a Bootable Disk Image

Creating a bootable disk image of your device's SD card for cloning onto other SD cards involves a few steps, as shown below:

Note:

We will use Raspberry Pi as an example device in this section to illustrate the disk image creation process. You can follow the same procedure for any type of device/hardware/platform(Raspberry Pi, Arduino, Nvidia Jetson or any device) and any variant of Linux OS.

Also, the procedure to create and clone a disk image is the same for an SD card or SSD or HDD.

1. Prepare Your Raspberry Pi:

Safely shut down your Raspberry Pi:

sudo shutdown now

Once the Raspberry Pi is powered off, remove the SD card.

2. Create the Disk Image (On a Linux Machine):

  • Identify the SD Card Device: Insert the SD card into a card reader connected to your Linux machine. Use the lsblk or sudo fdisk -l command to identify the device name (e.g., /dev/sdb, /dev/mmcblk0).

    Warning:

    Be extremely careful to identify the correct device, as writing to the wrong device can result in data loss.

    $ lsblk

  • Create the Image: Use the dd command to create the disk image:

    sudo dd if=/dev/sdX of=raspberrypi.img bs=4M status=progress
    • Replace /dev/sdX with the actual device name of your SD card.
    • raspberrypi.img is the name of the image file you're creating.
    • bs=4M sets the block size to 4MB for faster reading.
    • status=progress shows the progress of the dd command.

    Warning:

    dd is a powerful command. If you specify the wrong if or of arguments, you can easily overwrite data on your hard drive. Double-check your device names.

The image file created by dd will be the same size as the SD card. You can (optionally) compress it to save space:

gzip raspberrypi.img

This will create raspberrypi.img.gz.

3. Write the Image to Other SD Cards (On a Linux Machine):

  • Identify the Target SD Card Device: Insert the target SD card into a card reader and identify its device name using lsblk or sudo fdisk -l.

  • Write the Image: Use dd to write the image to the target SD card:

    • For the uncompressed image:

      sudo dd if=raspberrypi.img of=/dev/sdY bs=4M status=progress

    • For the compressed image:

      gzip -dc raspberrypi.img.gz | sudo dd of=/dev/sdY bs=4M status=progress

    • Replace /dev/sdY with the actual device name of the target SD card.

    • gzip -dc decompresses the image before writing it.

  • Sync: After writing the image, it's important to sync the file system to ensure all data is written:

    sync

4. Using the Image on Other Raspberry Pis:

  • Insert the newly created SD card into another Raspberry Pi and power it on.
  • The Raspberry Pi should boot using the cloned image.

Alternative Tools:

  • raspi-config: The Raspberry Pi OS itself includes a tool for creating SD card copies.
  • PiShrink: This tool can shrink the image file to its minimum size, which is very useful.
  • Raspberry Pi Imager: The official tool for writing images, and can also be used to create backups.

Important Considerations:

  • SD Card Size: The target SD card must be equal to or larger than the original SD card.
  • Operating System Compatibility: The image should be compatible with the target Raspberry Pi model.
  • Security: If your original Raspberry Pi had sensitive data, consider encrypting the image file.
  • Backup: Always back up your important data before creating or writing disk images.
  • Testing: Test the cloned SD card on a test Raspberry Pi before deploying it to a production environment.
  • Resizing Partitions: If you used PiShrink or a tool to shrink your image, the first time you boot the cloned Pi, the OS will automatically resize the root partition to use all the space on the SD card. If this doesn't happen, you can use raspi-config to manually expand the filesystem.