Why every time I reboot the system using the shellhubio/agent:v0.21.3 client change number (mac)

[DxrMorgan]

Hello. Can you tell me why, every time I reboot the system using the shellhubio/agent:v0.21.3 client on the shellhub server, I see a request for a new device? It seems like the MAC address or something is changing. I installed DietPi Linux (Debian 13). Others always had Armbian (Debian 12). This is the first time I've seen this. Where and what can I check? How does the agent generate the MAC address or number?

[otavio]

This is a known issue that can occur on DietPi, especially with Debian 13. Let me explain what's happening and how to fix it.

How ShellHub Identifies Devices

By default, ShellHub generates the device identity using the MAC address from the primary network interface (typically eth0). This works well on most systems, but DietPi on certain SBCs can have issues where:

1. The MAC address changes randomly on each reboot (common on Orange Pi and similar boards)
2. The network interface name changes (from eth0 to enxXXXXXXXX)
3. The interface used for identity detection isn't consistent

Quick Diagnostic

You can verify if your MAC address is changing by running this before and after a reboot:

ip link show | grep ether

If the MAC address is different after reboot, that's your issue.

The Solution: Use SHELLHUB_PREFERRED_IDENTITY

The recommended fix is to set a fixed device identity using the SHELLHUB_PREFERRED_IDENTITY environment variable. This overrides the MAC-based identity with a custom, stable value.

Option 1: Reinstall with Preferred Identity

If you haven't customized your setup significantly, the easiest approach is to reinstall the agent with a fixed identity:

# Stop and remove current agent
docker stop shellhub && docker rm shellhub

# Reinstall with a custom identity
curl -sSf "http://<YOUR-SERVER>/install.sh?tenant_id=<YOUR-TENANT-ID>&preferred_identity=my-dietpi-device" | sh

Option 2: Modify Existing Docker Container

If you want to keep your current setup, you can modify the Docker run command to include:

-e SHELLHUB_PREFERRED_IDENTITY=my-dietpi-device

You'll need to recreate the container with this environment variable.

Option 3: Fix the MAC Address (Alternative)

If you prefer to fix the underlying MAC address issue, you can set a static MAC in DietPi:

Create /etc/network/interfaces.d/eth0:

iface eth0 inet dhcp
hwaddress ether XX:XX:XX:XX:XX:XX

Replace XX:XX:XX:XX:XX:XX with your desired MAC address.

Note: Avoid using dietpi-config for network settings afterward, as it may overwrite this configuration.

Summary

The quickest fix is to use SHELLHUB_PREFERRED_IDENTITY to set a custom, stable device identity. This bypasses any MAC address inconsistencies on your DietPi system.

Let me know if you need any clarification!

[DxrMorgan]

Thank you very help me! By the way, using your service (I actually hosted it on my own) I wrote a program for convenient port forwarding, an SSH client, file transfer, and so on. Now I can directly access any Linux system from my computer through your service. It's like a shell. Thanks for the project. I used Zerotier before, but it's blocked as a VPN. [image: Ashampoo_Snap_18 января 2026 г._23h36m15s_030_.png] [image: Ashampoo_Snap_18 января 2026 г._23h25m37s_029_.png] [image: Ashampoo_Snap_18 января 2026 г._23h25m23s_028_.png] [image: Ashampoo_Snap_17 января 2026 г._20h31m35s_003_.png] [image: Ashampoo_Snap_17 января 2026 г._20h30m50s_001_.png] пн, 12 янв. 2026 г. в 03:02, Otavio Salvador ***@***.***>:

…

This is a known issue that can occur on DietPi, especially with Debian 13. Let me explain what's happening and how to fix it. How ShellHub Identifies Devices By default, ShellHub generates the device identity using the MAC address from the primary network interface (typically eth0). This works well on most systems, but DietPi on certain SBCs can have issues where: 1. The MAC address changes randomly on each reboot (common on Orange Pi and similar boards) 2. The network interface name changes (from eth0 to enxXXXXXXXX) 3. The interface used for identity detection isn't consistent Quick Diagnostic You can verify if your MAC address is changing by running this before and after a reboot: ip link show | grep ether If the MAC address is different after reboot, that's your issue. The Solution: Use SHELLHUB_PREFERRED_IDENTITY The recommended fix is to set a *fixed device identity* using the SHELLHUB_PREFERRED_IDENTITY environment variable. This overrides the MAC-based identity with a custom, stable value. Option 1: Reinstall with Preferred Identity If you haven't customized your setup significantly, the easiest approach is to reinstall the agent with a fixed identity: # Stop and remove current agent docker stop shellhub && docker rm shellhub # Reinstall with a custom identity curl -sSf "http://<YOUR-SERVER>/install.sh?tenant_id=<YOUR-TENANT-ID>&preferred_identity=my-dietpi-device" | sh Option 2: Modify Existing Docker Container If you want to keep your current setup, you can modify the Docker run command to include: -e SHELLHUB_PREFERRED_IDENTITY=my-dietpi-device You'll need to recreate the container with this environment variable. Option 3: Fix the MAC Address (Alternative) If you prefer to fix the underlying MAC address issue, you can set a static MAC in DietPi: Create /etc/network/interfaces.d/eth0: iface eth0 inet dhcp hwaddress ether XX:XX:XX:XX:XX:XX Replace XX:XX:XX:XX:XX:XX with your desired MAC address. *Note:* Avoid using dietpi-config for network settings afterward, as it may overwrite this configuration. Summary The quickest fix is to use SHELLHUB_PREFERRED_IDENTITY to set a custom, stable device identity. This bypasses any MAC address inconsistencies on your DietPi system. Let me know if you need any clarification! — Reply to this email directly, view it on GitHub <#5701 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAN6XZ6K5BJ4NVEQVU7DZJ34GLP7ZAVCNFSM6AAAAACRKWDHIWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKNBXGEYDIMQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>