Skip to main content

Linux Seamless Provisioning

Seamless Provisioning allows users to register devices to the console before they’re provisioned. Linux Seamless Provisioning differs from Android and iOS Seamless because users can also provision their Linux devices using supported distribution packages. 

Supported packages: 

  • .deb for Ubuntu
  • .rpm for Red Hat 

With Linux Seamless Provisioning, you can either pre-register devices using known serial numbers or generate a configuration file to include in your image. Once the customized image is installed and the device boots, provisioning occurs automatically—reducing manual setup steps and ensuring devices are provisioned on boot.

In this article: 

Linux Seamless

Step 1: To use Linux Seamless Provisioning, go to the console’s Provisioning Methods section. Select Linux as the Device Platform and Seamless Provisioning as the Provisioning Method. 

Then select a blueprint. 

Option 1: Pre-Register Devices (for readily-available serial numbers)

Step 2: Enter the device's serial number  into the input file. You can register multiple devices at once by separating the serial numbers by a comma. 

device serial numbers in an input field separated by a comma.png

You can also use Bulk Upload to upload a CSV file of device identifiers. Follow the CSV formatting to upload multiple devices. Bulk uploading also allows you to add aliases and tags to the device. 

We are discontinuing UUIDs for Linux Seamless Provisioning. You can continue to use serial numbers.
unique_id unique_id_type group_id assigned_blueprint_id alias tags
12XXXXXXXXX SERIAL GROUP ID BLUEPRINT ID ALIAS TAG1,TAG2,TAG3

Option 2: Generate Configuration (when serial numbers aren’t readily available)

In the Generate Configuration tab, click on Generate Configuration.

Place the configuration in /var/lib/esper.config.json in your Linux image.

Step 3: Click on Seamless Provisioning Package to download the package. Choose from: 

  • .deb for Ubuntu
  • .rpm for Red Hat 

After downloading the package, integrate the package into your image generation process. 

Then, install the operating system on the device. After installation, boot the device to trigger provisioning. 

For RedHat, a reboot may be required after configuring Wi-Fi. 

Integrating the Debian Package for Ubuntu Devices

There are many ways to integrate the Esper package in your image. In this example, we use Cubic to integrate the Esper Debian package into the Ubuntu ISO image. 

Before you begin: 

  • Ensure you have administrator (sudo) privileges on your build system
  • Back up any important data on the USB drive as it will be completely overwritten
  • The entire process takes approximately 30-45 minutes

Requirements: 

  • A bootable drive, such as a USB drive
  • A Linux device to do the integration on, we’ll call this a work computer
  • A Linux device to install the image on, we’ll call this the seamless device
  • Cubic or something similar
  • An Ubuntu ISO image 

Proceed with the seamless provisioning steps listed as Steps 1, 2, and 3 of this guide. 

Step 4: Prepare the Ubuntu image

While on your work computer, launch Cubic. Create a directory to save the project. 

custom ubuntu iso creator cubic screen with project field.png

 

On the next screen, click on the filename and select the Ubuntu ISO image. The rest of the information should auto-populate. 

Screenshot of Cubic application where Ubuntu ISO file is selected.png

 

Press Next. Wait while the program exacts the image. 

Screenshot of Cubic extracting Ubuntu ISO image for customization.png

 

Step 5: Integrate the Esper Debian package

On the next screen, click on the copy button and choose the Esper Debian package. 

If you downloaded the configuration file from option 2 of this guide, also paste the configuration in the terminal.

Screenshot of Cubic showing file copy dialog to select Esper Debian package.png

 

Then press the copy button to copy the file into the virtual environment.

Screenshot of Cubic environment showing Esper Debian package copied successfully.png

 

While in the virtual environment, install the package. Then verify that the package was copied successfully. 

Installation 

Install the Debian package and check for dependencies. 

dpkg -i /root/app.deb || apt-get -f install -y

If you added the configuration file, you will also move it to the appropriate folder.

mv config.json /var/lib/esper

Verification 

Verify the installation. 

-l /var/lib/esper/bin/provisioner
ls -l /lib/systemd/system/esper-provsioner.service 
ls -l /ect/systemd/system/multi-user.target.wants/esper-provsioner.service
Screenshot of terminal showing verification of Esper provisioner installation paths.png

The error “System has not been booted with systemd as init system…” is expected. You can proceed with the verification steps after the package is installed. 

Then press Next. 

Screenshot of Cubic preparing customized Ubuntu image after installation of package..png

 

The system will prepare the new image. 

Click Next.

Screenshot of Cubic displaying options to finalize and prepare the new Ubuntu image..png

Select gzip and click Generate. 

Screenshot of Cubic interface with gzip selected for image compression before generation.png

Then press Finish. 

The system will create the image. This may take a while. 

Step 6: Load the image to the USB drive 

Then insert the USB drive. Select the USB drive from the Disks menu. 

Screenshot of USB drive selection screen for loading Ubuntu image.png

Then, select the image. 

Screenshot of USB drive menu showing selected Ubuntu image.png

Press Start Restoring to begin. 

Screenshot of restoration process with Start Restoring button highlighted.png

You may need to input your access credentials to proceed. 

The image will start saving to the USB drive. This may take a while. Once the operation is finished, disconnect the USB drive. 

You can use Rufus or Balena to burn the software to a disk as well. 

Step 7: Install the image on the seamless device 

Connect the USB drive to the seamless drive and enter the device’s boot menu (usually by pressing F2, F10, or F12. Check your manufacturer’s documentation). Choose the USB drive, and boot the Ubuntu image. 

Troubleshooting 

I cannot load the image because it says there is a Bitlocker issue. 

Ensure Bitlocker and other security functions are disabled while booting the image. 

How do I enter the boot menu? 

Each device differs. Look up your device manufacturer information to see how to enter the boot menu. Typically, entering the boot menu involves hitting F2, F10, or F12 repeatedly during the start up screen.

I need to install the X11 display package separately from the Wayland package. 
Starting in January 2026, the X11 and Wayland packages can now be installed separately or together depending on your requirements.

Related articles

Featured content