en.Administration

Important: Create a backup before every update/upgrade and store it safely.

A regular firmware update/upgrade is performed via Settings → Control panel → CCU maintenance. This page shows the currently installed and the latest available software version as well as the storage space available for the update. If there is not enough storage space, the upload is blocked.

Automatic update (recommended):

1. Log in to the WebUI and create a backup of the current configuration under Settings → Control panel → Security → Create backup. Store the downloaded *.sbk file safely.
2. Under Settings → Control panel → CCU maintenance, click Perform automatic update. OpenCCU then directly downloads the update file matching the platform used.
3. Afterwards, initiate the update by clicking Start update. The process may take several minutes and may require multiple restarts. If necessary, refresh the WebUI after a few minutes; a firmware update status page or a prompt to wait for the restart will appear.

Manual update:

1. As above, create a backup of the current configuration and store it safely.
2. Under Settings → Control panel → CCU maintenance → Download, go to the download page and download the appropriate update file for the platform used (e.g. *-rpi3.zip for CCU3/ELV-Charly/Raspberry Pi 3 or *-ova.zip for virtual machines). Caution: Be sure to select the correct file for your target platform.
3. Under Select downloaded software, select the ZIP file and then click Upload. Caution: Really upload the *.zip file – not an extracted archive. Do not close or reload the browser/tab during the upload.
4. After the upload has completed, initiate the update by clicking Start update (procedure as above).

After a successful update, the WebUI login appears again. An additional indicator of a booted system on single-board computers (e.g. Raspberry Pi) is the green board LED, which pulses in heartbeat mode (see Status LED Function). For virtual machines, a look at the console may help. If display or functional problems occur in the WebUI after the update, please clear the browser cache.

Alternatively, an update can also be performed via SSH (see Manual Backup via the Command Line) using the checkFirmwareUpdate.sh script:

/bin/checkFirmwareUpdate.sh -b -a -r

Here, -b creates a backup in the default backup path before the update, -a downloads and installs the latest version and -r restarts the system directly afterwards. Without options, the script only checks whether a new version is available.

For the container variants, the update is not performed via the WebUI but via the respective platform. The configuration is preserved:

• Docker/OCI: Run the install-docker.sh script again or update the image via docker pull/Docker Compose, see Docker Container (OCI).
• LXC: Run the install-lxc.sh script with the update parameter, see Linux Container (LXC).
• Kubernetes: Update the Helm chart via helm upgrade, see Kubernetes/K8s.
• Home Assistant: Update the OpenCCU app like any other Home Assistant app via the Home Assistant user interface. Returning to an older version is only possible via a previously created Home Assistant backup of the app.

If an update/upgrade unexpectedly fails, it can be performed via the recovery system. To do this, trigger the restart under Settings → Control panel → CCU maintenance → Restart in recovery mode. The recovery WebUI is then accessible, allowing administrative actions – including firmware updates.

If the system starts after an update but problems occur that could be caused by installed CCU add-ons, a restart can be performed via Settings → Control panel → CCU maintenance → Restart in safe mode, in which OpenCCU boots without active CCU add-ons (i.e. without their startup scripts).

If this also fails, a reinstallation (e.g. with a new SD card for single-board computers, or with a new VM for virtual machines) according to Installation is always an option. Afterwards, the previously saved backup can be restored via Settings → Control panel → Security.

A backup contains all usage/configuration data of OpenCCU (programs, settings, etc.) including installed CCU add-ons. By importing a backup, a working state can be restored quickly.

Note: Create backups regularly – at least before and after major changes and before every update.

1. Log in to the WebUI.
2. Navigate to Settings → Control panel → Security.
3. Select Create backup. Depending on size and hardware, the creation takes a few seconds up to several minutes. Do not leave the WebUI or the tab during this time.
4. When finished, the browser offers the file for download – then archive it safely.

Prerequisite: a USB storage device (supported file system) is plugged in or an external storage (e.g. NAS via NFS/CIFS) is mounted.

1. Enable SSH in the WebUI under Settings → Control panel → Security (disabled by default) and set a password.
2. Log in as user root via SSH or locally on the console.
3. Create a backup in a target directory using the following command:

   /bin/createBackup.sh <BACKUPDIR>
   

   Replace <BACKUPDIR> with e.g. /media/usb0 (connected USB storage device). The backup file is stored there following the pattern <hostname>-<version>-YYYY-MM-DD-HHMM.sbk.

OpenCCU automatically creates a configuration backup (*.sbk) every night at 00:07 and stores it in a backup directory. By default, this is:

• /media/usb0/backup – on a connected USB storage device (see below),
• /backup/openccu – when running as a Home Assistant app (see below).

By default, a maximum of 30 backups are kept in the backup directory; older backups are deleted automatically. Under Settings → Control panel → Advanced settings, the automatic backup can be disabled via Auto Backups, an alternative backup directory can be defined via Backup Storage Path and the maximum number of backups to keep via Backup Quantity (max.). The backup directory can also be a network drive of a NAS system mounted e.g. via NFS or CIFS (see Custom Actions during Boot).

If a USB storage device with a supported file system (FAT32, exFAT, NTFS, ext2/3/4, F2FS, HFS+) is permanently connected to the system running OpenCCU, OpenCCU automatically creates a backup every night and stores it in the backup directory there.

When running OpenCCU as a Home Assistant app, the automatic configuration backups are stored within Home Assistant in its preconfigured backup path (internally: /backup/openccu).

To access these OpenCCU configuration backups created within Home Assistant, proceed as follows:

1. Install the Advanced SSH & Web Terminal app To be able to download the configuration backups from your Home Assistant system via SCP or SFTP, first install the Advanced SSH & Web Terminal app from the Home Assistant Community Store:

2. Enable SCP/SFTP To be able to download the configuration backup files (*.sbk) from Home Assistant via SCP or SFTP later, change the username to root in the app, set a password and enable the sftp option:

3. Download the sbk backup with an SCP/SFTP client Once SCP/SFTP access has been enabled, you can connect to the Home Assistant host with a suitable SCP/SFTP client and download the *.sbk file to another system, e.g. using the scp command:

1. Log in to the WebUI.
2. Navigate to Settings → Control panel → Security.
3. In the Backup management area, select the desired backup file.
4. Start the process with Import backup; the transfer may take a moment. Note: If a custom security key has been set, it must be entered.
5. Import system backup triggers the restart and applies the backup.

The backup file must first be copied to OpenCCU via SCP or be available on a connected/mounted storage device (e.g. USB stick, NFS share).

1. Log in as user root via SSH.

2. Start the restore:

   /bin/restoreBackup.sh [-c] [-b] [-r] [-f] <PATH_TO_BACKUP>
   

   Options:

   • -c – only check the validity of the backup file without importing it
   • -b – create a backup of the current state in the default backup path before importing
   • -r – restart immediately after importing
   • -f – force the import (skip the security key check)

   Example: /bin/restoreBackup.sh -r /media/usb0/backup/openccu-3.89.11.20260919-2026-10-04-0007.sbk

3. Without the -r option, restart afterwards using reboot.

OpenCCU then restarts and applies the selected backup.

OpenCCU already comes with a number of security features out of the box. For secure operation, the following advice should also be observed:

• Set a password: Under Settings → User management, set a secure password for the Admin user (and any other users). Without a password, the WebUI is accessible to everyone in the local network without logging in.
• No access from the internet: The WebUI and all CCU services are only accessible from local/private networks by default. This restriction can be disabled under Settings → Control panel → Advanced settings → Protect from external internet access, but this is explicitly not recommended.
• No port forwarding: Never make OpenCCU accessible from the internet via a port forwarding in your router. OpenCCU regularly checks whether such a port forwarding exists and reports it with the WebUI alarm message WatchDog: security-portforward. In this case, remove the port forwarding in your router. The check can be disabled under Advanced settings → Security check (Portforwarding).
• Remote access via VPN: For access from on the road, use a VPN instead, e.g. the Tailscale VPN integrated in OpenCCU or a VPN of your own router.
• Firewall: Under Settings → Control panel → Configure firewall, you can define for the programming interfaces (Homematic XML-RPC API, Remote Homematic script API) as well as other services whether full access, access restricted to certain IP addresses or no access is allowed. Interfaces that are not required should be restricted where possible.
• SSH only when needed: SSH access is disabled by default. It should only be enabled under Settings → Control panel → Security when needed and protected with a secure password.
• Encrypted connection: Use HTTPS to access the WebUI wherever possible. How to integrate your own certificate is described in WebUI Usage.
• Stay up to date: Update OpenCCU regularly, since security fixes are only provided for the latest version.

Security vulnerabilities can be reported via the issue tracker in accordance with the security policy.

The following CCU add-on packages are fully or partially compatible with OpenCCU. They are installed via Settings → Control panel → Additional software, which works the same way in all OpenCCU variants (including containers and the Home Assistant app). On ARM64 systems, add-ons compiled for 32-bit ARM (e.g. CCU2/CCU3) usually run as well thanks to the integrated 32-bit support.

The Status column reflects the maintenance status of the respective project: active (changes within the last two years), last change YYYY or archived (project discontinued).

Depending on the hardware (Raspberry Pi, ODROID, ASUS Tinker Board 2, …), OpenCCU uses the board LEDs for status indications if OpenCCU is installed directly on the board.

During startup/shutdown

• Green LED: flashes when the SD card or the storage device used is accessed.
• Red LED: flashes at regular intervals → the system is in administrative mode.

During regular operation (system booted)

• Green LED: heartbeat mode – the pulse frequency increases with CPU load up to a continuous light at 100% load.
• Red LED: flashes when the SD card or the storage device used is accessed.

After a proper shutdown

• Green LED: flashes at regular intervals.
• Red LED: lights up permanently → the system can safely be disconnected from power.

Recovery system started properly

• Green LED: flashes when the storage device is accessed.
• Red LED: heartbeat mode (load indication).

On the ODROID models, the blue status LED takes over the function of the green LED; a red LED is not available there. The use of the board LEDs or the LEDs of the radio module can be disabled under Settings → Control panel → Advanced settings → LED use (Onboard) or LED use (RF module).

In addition, some radio modules (e.g. RPI-RF-MOD, HomeMatic LAN gateway) have LEDs with device-specific status indications.