Linux device enrollment in Hexnode UEM

Enrollment establishes the necessary communication between Linux endpoints and the Hexnode UEM console, enabling administrators to configure, secure, and oversee devices remotely. Hexnode uses a CLI-based (Command Line Interface) enrollment method for Linux, ensuring fast and efficient provisioning via terminal commands.

What is CLI-based Enrollment?

CLI (Command Line Interface) is a text-based user interface used to interact with a computer’s operating system. Unlike a Graphical User Interface (GUI) which uses windows and icons, the CLI relies on text commands entered into a terminal to execute tasks with high precision.

Hexnode uses this method for Linux to provide a lightweight and versatile onboarding process. It offers several key advantages:

• Efficiency: Enroll devices in seconds by executing a single command block.
• Headless Support: Perfect for servers, IoT gateways (like Raspberry Pi), and digital signage players that do not have a monitor or mouse attached.

Prerequisites and Compatibility

Before enrolling, ensure the device meets the following operating system requirements:

• Ubuntu: 18.04 LTS and later
• Fedora: Version 36 and later
• Debian: Version 10 and later
• Linux Mint: Version 21 and later

Enrollment Methods

There are two primary methods for enrolling Linux devices:

• Open Enrollment: No credentials required on the device side.
• Authenticated Enrollment: Requires user credentials (Email/SMS or Self-Enrollment).

Method 1: Open Enrollment (No Authentication)

This method allows devices to be enrolled immediately by running a script, without requiring the user to enter a username or password on the device.

Step 1: Configure Portal Settings

1. Navigate to Enroll > Platform Specific > Linux > CLI-based Enrollment.
2. Select Switch to Open Enrollment.
3. Default User: Select the user to be associated with the device.
4. Ownership: Choose Personal or Corporate.
5. Click Next.

Step 2: Run Commands on Linux Device

Open the terminal on the Linux device and execute the commands matching your hardware architecture. Replace <portalname&gt with your actual Hexnode portal name.

For Standard Devices (Non-ARM):

Verification Hash (SHA-256) for the installer:

For ARM-based Devices:

Verification Hash (SHA-256) for the installer:

Method 2: Authenticated Enrollment (Email/SMS or Self Enrollment)

This method requires the user to authenticate using credentials sent via Email/SMS or pre-assigned by the admin.

Option A: Email or SMS Enrollment

Step 1: Configure Portal

1. Navigate to Enroll > Platform Specific > Linux > CLI-based Enrollment.
2. Click Switch to Authenticated Enrollment.
3. Enrollment Request: Select the users to enroll.
4. Ownership: Select Personal, Corporate, or allow the user to choose.
5. Click Next.
6. Select Email or SMS (requires SMS configuration) and click Send.

Step 2: Device Enrollment

1. The user receives an Email or SMS containing the specific enrollment command and credentials.
2. Open the terminal.
3. Run the command provided in the email/SMS (Ensure you use the correct command for ARM vs Non-ARM as listed).
4. When prompted, enter the Username and Password provided in the message.

Option B: Self Enrollment

Use this method if you want to provide a static password to users manually, rather than sending a dynamic request.

Step 1: Configure Portal

1. Navigate to Enroll > Platform Specific > Linux > CLI-based Enrollment.
2. Click Switch to Authenticated Enrollment.
3. User Type: Select Self Enrollment.
4. Configure Ownership settings and click Next.

Step 2: Device Enrollment

1. Run the applicable command for your hardware:

   For Standard Devices (Non-ARM):

   Script to enroll non-ARM devices.

   curl -L https://<portalname>.hexnodemdm.com/enroll/ --output config chmod +x config sudo ./config

   1 2 3

   curl -L https://<portalname>.hexnodemdm.com/enroll/ --output config   chmod +x config sudo ./config

   For ARM Devices:

   Script to enroll ARM devices.

   curl -L https://<portalname>.hexnodemdm.com/enroll/ARM --output config chmod +x config sudo ./config

   1 2 3

   curl -L https://<portalname>.hexnodemdm.com/enroll/ARM --output config chmod +x config sudo ./config

2. Enter the username and password assigned by the admin when prompted.

Frequently Asked Questions (FAQs)

Q1: What are “Linux Distros” (Distributions)?

A Linux Distribution (or “Distro”) is a specific version of the operating system that includes the Linux kernel along with a package manager, desktop environment, and pre-installed software. Hexnode supports major enterprise distributions including Ubuntu, Fedora, Debian, and Linux Mint.

Q2: What are “ARM Devices”?

ARM devices run on processors that use a different architecture (RISC) than standard desktop PCs (x86/Intel/AMD). Because the hardware language is different, they require a specific installer file.

Examples: Raspberry Pi, NVIDIA Jetson Nano, and other IoT gateways.

Q3: How do the installer file be verified?

You can verify the integrity of the downloaded config file using the SHA-256 hashes provided in the “Open Enrollment” section. Run sha256sum config in the terminal and compare the output string to the hash provided in this documentation.

Troubleshooting Enrollment Errors

1. “The Hexnode agent is already running”

Symptom: When attempting to enroll a Linux device, the terminal displays the error:

“The Hexnode agent is already running. Stopping the enrollment process.”

Cause: This error typically occurs if the device was previously enrolled and not properly disenrolled. Residual files or active services from the previous installation are blocking the new enrollment attempt.

Resolution: You must manually stop the background service before re-attempting enrollment.

1. Open the terminal on the Linux device.
2. Run the following command to stop the service:
   Script to stop backgroud service

   sudo systemctl stop hexnode_agent.service

   1	sudo systemctl stop hexnode_agent.service

3. Once the service is stopped, re-run the enrollment command.