BalenaOS - Changing Hostname

If you are using Balena Cloud to manage your IoT devices, you will most likely run into the requirement to change the hostname of the device. This can be done in multiple ways, in the alternatives below, I am assuming you are running Balena OS on a SBC such as Raspberry Pi where the boot media is a SD card.

• Editing config.json on SD card
• Changing hostname using Cloud API
• Editing config.json on the device

Editing config.json on SD card

This option is easiest way to change the hostname, but this requires physical access to the device and its’ boot media. This can be done both before first boot and after first boot.

1. Take out the SD card and insert it into a computer. If you are using a Windows device, only the /boot partition will show, which is fine.
2. Open the config.json file.
3. If the hostname key exists, update the value, otherwise the following at the end of the file, before the last }:
   , "hostname": «newhostname»
4. Re-insert the SD card and boot device,
5. The new hostname should now be active.

Changing hostname using Cloud API

This option does not require any special tools except curl, but I have only been able to get this working on a non-windows client (due to issues with quotes).

1. Find the full uuid of your device.
   1. One option is using balena-cli: balena device list
   2. Another option is to navigate to the device page on dashboard. The uuid is in the web address: https://dashboard.balena-cloud.com/devices/«uuid»
2. Find and copy your session token in the dashboard

3. On a non-windows host, run the following command, replacing the values in the first three lines:

   UUID=uuid_of_device
   TOKEN=session_token
   HOSTNAME=new_hostname
   
   curl -X POST --header "Content-Type:application/json" \
   --header "Authorization: Bearer $TOKEN" \
   --data "{\"uuid\": \"$UUID\", \"method\": \"PATCH\", \"data\": {\"network\": {\"hostname\": \"$HOSTNAME\"}}}" \
   "https://api.balena-cloud.com/supervisor/v1/device/host-config"
   

4. Reboot device, and the new hostname should now be active.

Editing config.json on the device

This option requires the following:

• balena-cli installed and signed in
• ssh access to device

1. Setup to ssh into the device:
   1. Download, install and sign into balena-cli.
   2. Add your clients public ssh to your Balena account. See this post for creating a ssh key.
   3. Run balena device list.
   4. Find the uuid of your device, both the short and long uuid works.
2. Run balena device ssh «uuid». You should now be connected to the host.
3. Re-mount the boot partition as rw: mount -o remount,rw /mnt/boot.
4. Take a backup using cat /mnt/boot/config.json
5. Check if the key hostname already exists in config.json
6. Open the config.json file in vi: vi /mnt/boot/config.json
7. If the hostname key exists, update the value, otherwise the following at the end of the file, before the last }:
   , "hostname": «newhostname»
8. To save and exit vi:
   1. Press Esc to enter command mode.
   2. Type :wq to write and quit the file.
9. Doublecheck that the edit was successful by running cat /mnt/boot/config.json.
10. If everything looks good, finish by rebooting the device.
11. The new hostname should now be active.