How to Deploy ControlUp for Desktops on Reimaged IGEL or 10ZiG devices

  • Updated on Oct 27, 2025
  • Published on Apr 9, 2025
  • 3 minute(s) read
Prev Next

In some cases, deploying the ControlUp for Desktops Agent on a device that gets reimaged can cause duplicated entries in ControlUp for the same device. You can solve this problem by using the device's name as the device's ID. If the device name remains the same after reimaging, then data in ControlUp is consistent before and after the reimaging.

This article describes how to use this feature for IGEL and 10ZiG.

Step 1 - Add custom settings in ControlUp

  1. In ControlUp, go to Devices > Configuration > Settings > Agent > Custom Settings. Your ControlUp account must have the permission Configure Custom Settings.

  2. Add the following custom setting to the JSON configuration: "RegisterWithDeviceName": true.

  3. Click Check and beautify custom settings at the bottom right to confirm correct JSON synax.

  4. Click Save Custom Settings.

Step 2 - Apply device settings

Preparation before reimaging

  1. Locate and capture the settings.json file:

    1. Using terminal access or a file manager with appropriate permissions on the Linux endpoint, navigate to the correct path for the specific OS:
      • IGEL 11: /custom/.controlup/sip_agent/settings.json
      • IGEL 12: /usr/local/avacee/sip_agent/settings.json
      • 10-ZIG: /boot/controlup/sip_agent/settings.json
    2. Create a secure copy of this settings.json file to a temporary location (e.g., a network share or a USB drive). Use commands like cp /path/to/settings.json /<your external storage location>/settings.json.backup in the terminal. Ensure you have read permissions on the source file and write permissions on the destination.

  2. Manually add RegisterWithDeviceName to settings.json:

    1. Open the copied settings.json file using a text editor (e.g., nano, vim, gedit).
    2. Within the JSON structure (typically at the top level), add the following key-value pair:
{
  "RegisterWithDeviceName": "true",
  // ... other existing settings ...
}
  1. Locate and capture the DeviceAccessToken.txt file:

    1. Navigate to the correct path for your OS:

      • IGEL 11: /custom/.controlup/sip_agent/cachefiles/DeviceAccessToken.txt
      • IGEL 12: /usr/local/avacee/sip_agent/DeviceAccessToken.txt
      • 10-ZIG: /boot/controlup/sip_agent/cachefiles/DeviceAccessToken.txt

    2. Create a secure copy of this DeviceAccessToken.txt file to the same temporary location as the settings.json backup. Use commands like cp /path/to/DeviceAccessToken.txt /<your external storage location>/DeviceAccessToken.txt.backup in the terminal. Ensure you have read permissions on the source file and write permissions on the destination.

Note that settings.json and DeviceAccessToken.txt files are unique identifiers for this specific installation. Do not use copies from one machine on another, as this will lead to identify conflicts within your ControlUp tenant.

Post reimaging and identity restoration

  1. Execute the standard reimaging procedure for the Linux hardware. This is outside the scope of this document but is the necessary precursor to restoring the Agent identity.

  2. Restore the settings.json file. After the reimaging is complete and the base OS is running, copy the backed-up settings.json file back to its original location. Ensure you have the necessary write permissions to the destination directory. You might need to use sudo with the cp command.

    • IGEL 11: cp /<your external storage location>/settings.json.backup /custom/.controlup/sip_agent/settings.json
    • IGEL 12: cp /<your external storage location>/settings.json.backup /usr/local/avacee/sip_agent/settings.json
    • 10-ZIG: cp /<your external storage location>/settings.json.backup /boot/controlup/sip_agent/settings.json

  3. Restore the DeviceAccessToken.txt file. Copy the backed-up DeviceAccessToken.txt file back to its original location. Ensure you have the necessary write permissions to the destination directory. You might need to use sudo with the cp command.

    • IGEL 11: cp /<your external storage location>/DeviceAccessToken.txt.backup /custom/.controlup/sip_agent/cachefiles/DeviceAccessToken.txt
    • IGEL 12: cp /<your external storage location>/DeviceAccessToken.txt.backup /usr/local/avacee/sip_agent/DeviceAccessToken.txt
    • 10-ZIG: cp /<your external storage location>/DeviceAccessToken.txt.backup /boot/controlup/sip_agent/cachefiles/DeviceAccessToken.txt

  4. Start the Agent service on the reimaged machine. The method for starting the service depends on the specific Linux distribution and its init system (e.g., systemctl start <agent_service_name>, service <agent_service_name> start).

When the Agent starts, the Agent reads the settings.json file. The presence of RegisterWithName: "true" triggers a process where the Agent communicates with the Tenant. Using the restored DeviceAccessToken.txt as its unique identifier, it will request to associate itself with the hostname that was previously linked to this access token. The Tenant should recognize the endpoint as the same device, retaining its historical data and configurations.

In ControlUp, ensure that the reimaged endpoint has reappeared with its original hostname and that historical data is still associated with it.

If hostname takeover fails, double-check the file paths, the content of settings.json (especially the RegisterWithName value and JSON syntax), and the successful restoration of DeviceAccessToken.txt. Review agent logs for any error messages related to registration or hostname assignment. Ensure correct file permissions are maintained when copying files back. The agent might require specific ownership and permissions to access these files.