Docs on how to backup openHAB

Ben… Did you see my post regarding those few files which contains IP number?

Could you perhaps spread some note about what happens, if a user restore the backup to another system which has another IP number?
My most worries is the \userdata\config\org\eclipse\smarthome\network.config file.

The rule I mentioned earlier about $OPENHAB_USERDATA containing UI settings is relevant for most of variables stored in $OPENHAB_USERDATA\config\. An important part of the restore process is to check that the system has the correct values for the new machine. The IP value for example will copy over from the old machine but openHAB should change it and you can and should check this in paper UI:


I don’t think this is true for InfluxDB but there should still be a setting in PaperUI to view it if it’s in $OPENHAB_USERDATA/config/

While rereading your post, i still don’t understand, what this means:

I think i wonder what/which the “standalone zip file” is. The answer might be:
Running backup under any linux, i’ll have a different directory structure in the resulting zip file than i will have running backup unter openHABian.
Please help again on that one please.

I had a (n other) glance at the documentation. Searching for “backup” gives me a list of entries for Mac, Win, Linux, openHABian.

Looking at what i am trying to emphasize on in this thread is: the users requirements [are|should be|are expected to be] the same for no matter which plattform they run openHAB on. Would you agree on this?

There are hints of what a user should copy to a save place in every doc. And if there are procedures to support this, there is an info.

Looking at these first step requirements and the systems mentioned, i wonder, if just one article would provide a better solution? Also i wonder about a missing script for beloved Windows. No need or no takers?

I’ve also had a look at the zip-file “openhab-cli backup” creates. Like Ben stated above, this is just a copy of a directories with all files an subdiriectories. Did i get this right?

The point of old IP-address being restored in case of has been mentioned above. Anything other to look at after restore explicitely?

From what i saw, there are also files restored, which will not be needed for a restored openHAB to run like userdata/jsondb/backup/*. Are there more files/directories which are not necessary but good to have (like the one i named) or even just do no harm?

I’m still unsure, how to put the infos together, we get here. How to structure it, so that there will be benefit. But Kim may have.

I still think it would be worth a result, even if it doesn’t cover each and every aspect of backup/recovery. A result that make guys und girls like Markus and Ben think that it was worth it to provide all the information, hints and links.

BTW: Looking at openHAB 3 documentation discussion, I see kind of similar problems. We are not alone. :wink:

Not quite, when I was talking about a “standalone zip” I was refering to the single zip file that you can manually install openHAB from (located in the Downloads Page. The file is the same file regardless of if you wanted to install on Mac, Linux or Windows. The package installations (apt, yum, dnf, docker etc) simply use this file and install it in a different way.

The backup zip file is a different file, likewise it can be used for any operating system and its contents are the same.

Yes, I would agree.

One page that describes a generic backup process like you’re suggesting would be better IMO. The backup strategy is separated into different installation methods because originally, the backup script only worked on Linux/Mac.

Basically yes, but it avoids copying any system files that shouldn’t be changed after installation, IMO this makes it a little more robust than copying and pasting the CONF and USERDATA folders and putting them back. The zip file also contains information about the openHAB version that it was backed up from. Just in case we need to add new features to the scripts etc.

Well it entirely depends on the system. The general rule is that if you set anything up that is system specific, then you should expect to have to change it after a restore.

Probably not, the majority of files that you won’t need are in userdata/cache or tmp and these aren’t included in the default mode of the script. If the default backup directory is in $OPENHAB_USERDATA then the backup script won’t include other backups either.

Ahh okay. I was afraid it would mess things up, so the user couldnt access the system anymore.

The restore from “the zip file” provided by “the backup script” was all i wanted to address. So everything else is out of scope ATM. Sorry to having been unspecifc. I understand from you answer, that there is nothing well known like the IP address the user should look add (even though he could expect openhab to take care of it). Is this correct from your point of view (not discussing, that user should have a close look on everything after restoring whatever)?

I’ve made an attempt to give the backup topic a structure from my point of view:

Secure your own work

  1. Data created with openHAB
    1.1) Reference to directorystructure in general / what ti finde where in the file system
    1.2) specific reference to openhab-cli backup / restore
  2. Changes and adjustments to the system
    2.1) writing down somewhere (of what you learned reding the docs) is most important
    2.2) possibly start again after the first test runs
    2.3) if possible, copy configuration files
  3. Know your own needs
    3.1) how important is openHAB to you?
    3.2) file deleted unintentionally
    3.3) something has is wrong since my last adjustment
    3.4) openHAB update(upgrade?) doesn’t do what it should do
    3.5) needs you never would have thought about …
  4. Be prepared for desaster
    4.1) backup complete operational system
    4.1.1) relatively simple with a dedicated system
    4.1.2) in principle this is also possible for every Windows laptop (dunno about Macs!)
    4.2) it’s not about software only
  5. Be aware of exotic conponents like z-wave :wink:
    5.1) read and understand the binding specific needs (need a controler? need to backup!)
  6. Practice restoring the system
    6.1) recover, recover, recover

I won’t think there’s more to write than 2-3 sentences a topic. This is more about making users think about the needs and what they should be willing to familiarize themselves with.

Please comment on this. I’ll try to put the next version togther including yourf feedback.

Comments regarding:
1.1 This is in my opinion not important. It could be nice to know, and maybe it could be specified in a later section . But it would be explained the other way around as in - What isnt beeing backup´d.
A user who just want to be able to backup and restore his system, whatever files/directories he probably wouldnt care about at all.

2.1 - 2.3
Is this worth anything regarding backup/restoring?

If the user came as far as to a document regarding backup/restoring, it would have been important enough :slight_smile:
Regarding how important an backup strategy is, thats suppose to be at the very top of the document. The users will always decide for himself. But the importantness is, hmm… important to stress to all, from the perspective of, what will happen if the system breakes.
We shouldnt care wether someone choose not to use any kind of backup. But we should explain what can or will happen. From there its a purely user decision to go any futher.

3.2 Goes for a more advance section.
3.3 This is relevant regarding when to do the actual backup… Ie… Do not do the backup when your system isnt running flowless (without issues).
3.4 This is where restoring makes sense :slight_smile:
3.5 Highly important aspect. But not too complex to scare the user.

Point 4 I´m not sure should be included at all.

Point 5 - This is part of, whats not beeing backup´d. There should be a later section where z-waves, databases, Grafana etc should be mentioned. But at first we should concentrate on how to use openhab-cli backup/restore procedure, and just add, that these external services do not get backup´d. This is to make it as simple and as clear as possible for most users, to get the messages spread and to get the users familiar with the methode of using openhab-cli. We dont want to scare them with the docs.

Later we can extend the backup docs with sections on, how to backup the external services.

Thx your input. “Their may be a misunderstanding” is what i think while reading your comments. I wondered what the cause might be.

This last sentence ogf yours gave me the hint: What im am “talking about” in 1)-5) is a short introduction in backup/restore (i dislike this description but don’t know better ATM).
What you want to get as a result is something like a “HowTo”, may be dedicated to openHABian. I forgot about that for a moment. But then i thought: both should be done. Give the user a general idea of backup needs and what to think about. And let’s do a HowTo.
If i’m wrong, let me know. If you think, some “introduction” (same for all plattforms openHAN runs on) is not what anyone needs, please let me also know. I doesn’t make sense to make some work nobody needs or cares about.
Anyway a structure for a HowTo is need, yes. Do you already have an idea of it?
PS: i’ll read your post again later. Maybe it’s me, who misunterstands.

at the risk of stirring up a heated discussion:

To me, backup is currently really an underexposed item in the documentation. I understand most of the opinions above. I understand why one would keep backup outside of the docs. I agree that backing-up is a different beast with several personal choices on which risks are acceptable.
However ( :slight_smile: )
OH3 is migrating towards GUI configuration (please do not start a new discussion on textual configuration). For me as an openhabian user I have some options, all looking at different issues of backing up a system. (openhab-cli, using openhabian copy of SD card for fast recovery, menu options 50-51, Amanda).
If I look at the current the zip file created by openhab-cli (or openhabian), it could just as well be a “.openhabconfig” binary file. (Although it feels reassuring to be able to actually look into the zip in order to see what is backed up and what isn’t). You could compare it to the fact that the jsondb file is human-readable but not at all aimed to be altered manually, or even .thing .item being txt files.

My point is that, especially if openhab wants to appeal to users that only feel comfortable using a GUI,
a save the current configuration (with the option to include or exclude persistence) will have to be part of the project. If I’m the type of user not comfortable with textual configuration, chances are that I will not see the difference between the different things to backup, and the zip file is “my homeautomation project”
When first getting to grips with openhab I would want to experiment and revert back, just by saving and opening my “.openhabconfig” file. Obviously, in doing so you get a lesser quality backup.

Being able to create the “.openhabconfig” zip file from within the gui, in combination with samba, would also allow people to integrate their backup into their family home backup system, whether this would be a NAS, cloud-based, etc

I therefore suggest investigating the option to integrate the openhab-cli backup into
the GUI. (at some point in time after which the developers have taken a rest from coding and answering all our questions)
In addition, the thorough explanation on the different risks to be covered could be made part of the documentation. (perhaps a tabular form with the different risks and options would be easier to read)


I realy want to start migrating to OH3, and switch to configuring everything via the GUI, but I’m not sure yet how to deal with backup and versioning. At the moment, after every change, I do a commit to my git repo. This way I have a nice view on all my changes, but I also use this as a backup (already needed it a few times). I understand that I can use openhab-cli backup, but this will not solve my versioning requirement. Any suggestions? Maybe I can add other (auto-generated) files to my repo when making modifications?

Do you use config files or are you going to set it all up with the main UI?

What hardware are you using?

Do you know about the openHABian SD card mirroring? This makes recovering from a failure something you can guide someone over the phone to do.

You can continue to do so. All UI configuration is stored as files in the /userdata/config folder or in userdata/jsondb.

Just add this to your repo. That’s what I’m doing. Only drawback is that there are some files that are changed even if you don’t do any real changes. I have excluded some files from versioning via .gitignore I feel are not relevant

But that’s versioning. For backup I would consider whole userdata folder.

Which then would be (one of) the problem root cause(s).
OH being a project that every volunteer for himself chooses what to work on is another one.

Backup alone is a complex issue, OH with all of its capabilities even more so, and a full home automation ecosystem like openHABian is the ultimate challenge to a backup process engineer.
And all you want is everything to simply work with a couple of clicks.
It never will (to an extent that’ll satisfy GUI lovers and beginners) because a) it is way too complicated to get it right and b) requires lots of efforts and competencies. Building the new OH UI took two years alone.

We do what we can but that ideal we cannot get even close to.
It would be relatively simple to provide some GUI hook, but it wouldn’t neither be comprehensive nor work reliably.

That’s the real challenge.
That’s what everybody expects without even saying so.
That’s what is way more important than the (G)UI.
That’s why GUI (in all likelihood) won’t happen.

That’s why we few spend our little spare time on what improves User eXperience most.
Reliability that is.

Hi Marcus,
I think I agree with you. Backup is hard and complex, as you point out in your excellent document In that document you also point out that what risks to take is a personal choice to which there is no one answer.
I just want to point out that, to me, it feels that there is a discrepancy between building a GUI enabling people to make use of the excellent stability of OpenHab, without knowledge on eg programming, and the current options to backup your work. With the emphasis on work not e.g. data persistence. If one uses your openhabian, you have several options to backup and restore. If not your on your own in the wild, often without sufficient knowledge. The basics are available: using backup-cli you can backup and restore your system.
So I created items and rules and if I hit the switch from within the GUI, it creates a restore point. To keep track of the changes I make in the system, I have a word file in the openhab configuration folder. If I want to read what “version” I want to restore to, I read the word file inside of the backup .zips.
I know this is not a full backup and restore by far, but it is sufficient for me. (for now)

If I’m suggesting to incorporate such restore point (restore being not equal to backup) into the GUI it is just that: a suggestion. I fully understand the work that’s being done, is done so by people spending their free time and I really appreciate the hard work and the stability of OH. It is because I appreciate the work I wouldn’t find it fair to withhold my experiences, as a suggestion

I totally disagree with this.

Backup is a simple task itself. The issue is, the restoring of the backup. And specially if you restore to a different system/different version as the backup was made for.

Thats why its important to distinquiss between the backup procedures as well as the restoring procedures.

A simple way way to backup a computer system, is to shut down the system, and do an image copy of its data on the storing device (normally an harddrive). And the exact opposit for the restoring procedure… Thats easy, simple and will work anytime.
The disadvantage is, this procedure takes time, and its far from flexible, no automatic. And it will only get you back to the time of when the backup was created. But it will work!

In my opinion, this is a minimum backup procedure which should be build-in to any system. Even though it may require you´ll have to add a second storage device for the backup.

Backing up a system and restoring to another system (even a different version of the same system) often requires somekind of hassle, all depending on, how much and what have changed since the backup. This is where a backup procedure really become complex.
Its not impossible, but there can be many things to consider to make it realiable.

And a backup of one type of system on a specific hardware, can become an issue trying to restore to the very same system (same version) but different hardware.

It all depend on, which kind of backup you would like (or maybe pay for).

Not necessarily, backup can be very difficult to understand, particularly for new users.

That is a manual backup solution, anyone can do it yes, but it is not what is being discussed here. In this we are discussing how to create a much more user friendly and intuitive backup solution, perhaps even accessible through the web UI.

I know. But when I read someone mentioning backup beeing complex, I simply have to disagree.
Automatic running backup procedure can be highly complexed, specielly if it should be schedule while the system is running (ie, without loosing data).

still dint had a chance to test OH3, so its enough /userdata/config folder and userdata/jsondb for versioning control ? And how to share config with other users when part is for example in userdata/jsondb ? All GUI is nice in OH3, but with OH2 file configs for me looked much easier when you need to share some part of items and rules…