Bulk Provisioning

Bulk provisioning setup is used when provisioning hundreds or thousands of devices from the same OS image

To provision multiple freshly-imaged devices with Synpse agent, a recommended method is to add a script to systemd which will run once on boot after networking.

You shouldn't just clone an image that has Synpse agent already initialised as each device needs to have its own device ID, which is set on initial install. It's important that we install Synpse on the first boot, and not pre-install it before cloning the disk. Read on for an example of how to do so.

Workflow

If you haven't dealt with bulk provisioning before, here's a workflow you can use to get yourself set up. It involves:

1. Downloading and booting into your chosen Linux installation

2. Filesystem changes to set up your devices on their first boot (systemd script)

3. Cloning the modified disk to multiple drives

After we're done, you'll be able to simply boot the devices and they will register as unique entries in your Synpse dashboard.

Preparing a Linux image

To boot a Linux install, pick your distribution of choice, download the image, and write it to your SD card or other medium of choice. Here is how you might do this to install Raspberry Pi OS, a standard distribution built for Raspberry Pis.

Next, plug your disk into your device. For a Raspberry Pi, this would just mean slotting the SD card into the SD card reader. You may also want to attach some peripherals for the following step, such as a keyboard and monitor, so you can interact with the system.

Installation script

Each device needs to run the installation script that you would normally use yourself when installing Synpse. Copy the project ID and device registration token (instructions can be found here):

Provision device page gives you project and registration IDs

Use the variables to edit the initial installation script below. Then place this script in /opt/install-synpse.sh. Once saved in the device, run chmod +x /opt/install-synpse.sh to ensure that the script can be executed.

#!/bin/bash
set -e
# Installs Synpse agent
curl --retry 10 --retry-delay 60 \
  https://downloads.synpse.net/install.sh | \
  AGENT_PROJECT=YOUR_PROJECT_ID \
  AGENT_REGISTRATION_TOKEN=YOUR_DEVICE_REGISTRATION_TOKEN \
  AGENT_CONTROLLER_URI=https://cloud.synpse.net/api \
  bash

# Stops the service only if the previous command was successful!
systemctl disable install-synpse.service

Running the script on boot

Here's a systemd unit file that we can use to run our one-off script. Let's place this script in /etc/systemd/system/install-synpse.service

[Install]
WantedBy=multi-user.target
[Unit]
Description=Installs Synpse agent
Wants=network-online.target
After=network-online.target
[Service]
Type=oneshot
ExecStart=/opt/install-synpse.sh
RemainAfterExit=true
StandardOutput=journal

Then ryn systemctl daemon-reload to reload daemon and then run sudo systemctl enable install-synpse.service to enable our new installation service to run on boot!

Ensuring it works (optional 😀)

Before cloning the image to thousands or millions (or just one) of devices it's always good to try it out. High level steps:

1. Restart the device

2. Check whether installation is successful and device registers to Synpse

3. Uninstall the agent

4. Re-enable install service

Let's test it. First, restart the device:

sudo reboot

Wait for the device to come up as a new device in Synpse. If it didn't work, check the logs with:

journalctl -u install-synpse -f

This should give you an indication on what happened.

If it does come up as expected, we need to disable and uninstall synpse agent (instructions here) and then enabling the install script again:

sudo systemctl enable install-synpse.service

Now, turn off the device and don't start it again without first cloning the image.

Disk Imaging

Now, the entire point of bulk provisioning is to provision multiple devices, so you'll want to clone this image across the storage drives that your devices will boot off of. You can use many disk cloning utilities to do so. Some good options are tools like Clonezilla or Deepin which can then be used to clone one drive to multiple drives for a very fast provisioning workflow.

Place the cloned SD cards into your devices, boot them, and you should see the new devices added to your project in Synpse dashboard.