Backup/Restore scripts for Linux and MacOS

Hi all,

Many people have asked for a simple way of backing up a configuration in a zip file, and a similarly simple way of restoring the configuration from that zip file.

From version 2.2 onward, openHAB will contain its own backup and restore scripts. These can be found in $OPENHAB_HOME/runtime/bin/.

For users of the Linux packages, and openHABian, simply use the openhab-cli commands.



Running this script will store all of the configurables made in paperUI or through textual configuration. It will attempt to backup the list of installed addons and bindings, and the settings for those bindings too.

./runtime/bin/backup                            ## Creates a backup file in the default location with a timestamp.
./runtime/bin/backup /opt/backups/  ## Creates a backup file in the specified location.
./runtime/bin/backup --help                     ## Brings up the help information

The default path to store the zip files in is in $OPENHAB_HOME/backups/ (/var/lib/openhab2/backups for apt/yum users). You can change this default path by specifying the $OPENHAB_BACKUPS environment variable (again use /etc/default/openhab2 if you’re using apt/yum)


The restore script restores a zip file created using process above and uses it to completely replace your openHAB configuration. Any newer changes that weren’t in the backup get removed.

*Note: This will not backup the runtime folders. If you’re trying to repair openHAB, it’s best to download a new instance, and then try the restore script to load your configuration.

./runtime/bin/restore /opt/backups/  ## Restores the openHAB config from the specified zipfile
./runtime/bin/restore --help                     ## Brings up the help information


You can find the source files at

As always, you should checkout the documentation for the latest instructions on how to use them. Let us know if you have any issues!


This is great stuff!

Does this work across versions? For example, if I were to backup a 2.2 SNAPSHOT now and for whatever reason upgrade to a newer version, let’s say 2.3 Release, can I restore the 2.2 SNAPSHOT to the new 2.3 Release or will I run into problems?

I just want to feel out the capabilities and limitations.

I need to think a bit on how to use this for Docker. It should be possible.

Absolutely, providing that the syntax of what you’re backing up hasn’t changed. From that perspective, it’s no different to keeping a configuration while you upgrade to 2.3 (Just an FYI, the next release after 2.2.0-SNAPSHOT is 2.2.0)

It’ll even take care of special considerations for that userdata folder.

If you set and export $OPENHAB_USERDATA and $OPENHAB_CONF, to your editable/accessible docker volumes, then ideally this should do the trick?

I know, I was trying to use an extreme example.

That should work great. I think a best practice will be to either mount a folder over the default backup folder or mount a folder somewhere else and set the environment variables to point at that.

One would need to do a docker exec -it /path/to/script/in/container to execute the backup. Ultimately I’ll probably want to set up something with the exec binding to run backups automatically. Cron probably isn’t an option inside the container, though maybe the container should be set up to do this automatically for us in the long run. Lots to ponder.

1 Like

I’m lost.
I just installed 2.2 unstable build and tried to follow the instructions.
all I have in $OPENHAB_HOME is a README.txt file telling me that I can place my scripts here.

I needto reinstall my PI3 because of an issue with UA-NETINST or so. I have no clue. I’m a developer and have no idea how to manage linux or openhabian or whatever is running here.

So where do I really find the scripts?

If you can’t find it in your local installation, you did something major wrong …

Take another look at:

That doesn’t sound right, what happens when you put:

printenv | grep "OPENHAB_"

$OPENHAB_HOME should point to /usr/share/openhab2 on Linux installs therefore the full path to the script is /usr/share/openhab2/runtime/bin/backup

Not sure, but according to my knowledge - there is not much you can do wrong with openhabian.
Just burn the image on the SD card, put it in PI3 and power up.
Then wait a few hours for it to install.

And not to get it wrong: Openhab2 was/is running fine on my PI. I just need to backup all settings and restore after a reinstall because I was advised to switch from UA NETINST image to raspbian image.
I assume (as I do not have any different information), that I have to swipe the SD card and burn another image onto the SD card. Then put back into PI and let it do the installation.

As I do not want to go thru all the setup stuff again (including the dashboards and the widgets), I would like to do a backup of the existing settings and restore on the PI after reinstall. Therefore I would like to run the backup.

It does not help to point to documents which do not contain any information on how a backup is done.
The Amada backup is also of no help as I do not even understand the questions it is asking during install like “What is the directory to store backups”. How to define a path in linux? Does the folder have to exist?

printenv shows nothing (no output),
nevertheless the folder /usr/share/openhab2 exists and the backup works when starting the script from there.
Thank you for your help.

Sorry, but when I follow the link I gave you I get:

1 Like

Hello Thomas,
I’ve installed the latest build of openHAB 2.2 on one of my systems yesterday and the printenv command yields the expected result. Could you please post the version string of your build here? (from SSH login screen or in the openHAB web dashboard)

It is not a big issue that this is not the case for you but openHAB itself is working. Still that should not happen and I wonder what went wrong. I’d say you don’t have to go through the trouble of reinstalling your whole system but you should remember that commands involving these environment variables (placeholders) might not work in your setup.

Background: During installation the file /etc/profile.d/ should have been created. Please compare with here…

That script is there and it looks exactly the same. I do not think that this is related to the openhab build installed. could it be that this is just missing because of the way openhab was installed, meaning as part of the openhabian setup?

Anyway - when tried to restore at a different SD card, I got the following errors:

[14:49:14] pi@PI3:/usr/share/openhab2$ sudo systemctl stop openhab2.service
[14:49:20] pi@PI3:/usr/share/openhab2$ sudo ./runtime/bin/restore /etc/openhab2/

       openHAB 2.x.x restore script

Using '/etc/openhab2' as conf folder...
Using '/var/lib/openhab2' as userdata folder...
Making Temporary Directory
Extracting zip file to temporary folder.

 Backup Information:
 Backup Version         | 2.2.0-SNAPSHOT (You are on 2.2.0-SNAPSHOT)
 Backup Timestamp       | 17_09_29-11_29_10
 Config belongs to user | openhab
             from group | openhabian

Your current configuration will become owned by openhab:openhabian.

Any existing files with the same name will be replaced.
Any file without a replacement will be deleted.

Okay to Continue? [y/N]: y
Moving system files in userdata to temporary folder
Deleting old userdata folder...
Restoring system files in userdata...
Deleting old conf folder...
Restoring openHAB with backup configuration...
chown: ungültige Gruppe: „openhab:openhabian“
Failed to change userdata permissions to openhab:openhabian

Any idea?

The restore should have completed regardless of the error, can you confirm this for me?

The script is complaining that your old group “openhabian” doesn’t exist anymore. Although I’m not convinced that this should have been anything other than “openhab”. For now you should make sure openHAB is in-charge of it’s own folders just in case.

sudo chown -R openhab:openhab /var/lib/openhab2
sudo chown -R openhab:openhab /etc/openhab2

I’ll work on updating the script so that it relies on a default if old users/groups do not exist.

Unfortunatley I cannot confirm if or not it worked as openhab2.2 is not running at all with the new raspbian based openhabian image.

The original SD card is back in and at least most of the interfaces work.
HABMIN is not working and keeps throwing errors.

  • OPENHAB is offline!
  • Error loading list of things
  • Error loading …

Nothing works anymore. I think I have to completely start over.

That shouldn’t be necessary, did you try the above commands I mentioned?, You also need to restart openHAB after:

sudo chown -R openhab:openhab /var/lib/openhab2
sudo chown -R openhab:openhab /etc/openhab2
sudo systemctl restart openhab2

Otherwise, sudo journalctl -u openhab2 should have some information as to why it’s not working.

@ThomasBrodkorb I am a bit confused. Is the new system an openHABian RPi image setup or not? The console output posted does suggest otherwise…

@Benjy the restore script is trying to restore all files to the username:password combination from the old system. Shouldn’t it be the respective combination from the new system? Please correct me if I’m wrong :see_no_evil:

I think you’re right, it should say what the previous owner was from the old backup for information purposes only. I’ll change this so that it reads the current username and group and updates after completion of the backup to this.

Regardless, the restore script would have completed the important part and I’m confident that if the run-time is able to start then the configuration will have been restored.

1 Like

Unfortunately I cannot tell if OH2.2 is running or not as I do not get any response to any web interface
I must also admit that I have tried to get nginx up and running - but that is also something that does not seem to work using the wizard.
So I cannot tell at all if OH is running or not. Again - I’m not a linux specialist, and I do not have the time to become one.

So I’m trying to redo all that stuff and will keep you updated.

if you didn’t do any special modifications yourself, the console output from above tells me that your openHABian installation failed horribly. That happens very rarely and there a bunch of reasons. My suggestion would be to restart with a fresh successful openHABian setup. You mentioned your lack of Linux experience but there is really not much you have to pay attention to. Prepare the SD card, boot the Pi, wait for the installation to succeed. Please check the openHABian article on all the details, especially the part that tells you if your installation was successful:

Currently running on step:

Updating repositories and upgrading installed packages… (running 38 Minutes meanwhile).

As far as I remember, the complete process took almost two hours last time.

Now “Installing git package…”