Docs on how to backup openhab

Tags: #<Tag:0x00007f61702d8bc8>

I think there is a huge lack regarding how to backup openhab in the docs. Infact for such an important task, its unbeliveable (for me) howcome it has been almost ignored.

My purpose with this thread is to have a discussion on, how to add a backup procedure to the doc, without having to search through tons of threads in the forum about the same.

First a quick pick at the doc as it looks right now:


The menu on the left, does not contain a backup menu at all. This is a fatal miss, (my opinion), as it would be the first option to go reading, in case someone needs to know how to backup, (which everybody should need to know).

Using the search option from openhab doc, there will be a list of 10 entry for the backup work. The closest I have come to a decent menu is this:

“Availability and backup”. Thats not good. Users searching for backup need to know how to backup. They dont need to read anything else. But this is a good start for a actual backup menu and procedure. Unfortuantly clicking on the link for the backup tool, leads to a post in a thread on the community. This is NOT good. It should lead the user to the actual backup menu in the doc, which is lacking, and the reason of this post…

Thats why I think, that there is a desperate need to change something here. Backup is not suppose to be difficult or even difficult to find how to. Its should be one of the most important steps and very easy to find. At least the docs could be optimized very easy I believe.
I know some will say. “Go file an request…”. But this is NOT my intention with this thread, at least not untill we have had a discussion on, what exactly to request for.

Which leads me to the next step of this post:
How to do backup of openhab:

The way I see it, there are two obvious possiblities:

  1. Amanda.
  2. openhab-cli backup.

I know Amanda has been documented somewhere (I didnt search specific for this, but I have seen tons of forum post regarding Amanda). Amanda has also been partly documented regarding openhabian-config… Perhaps it just need to be placed in a “Backup menu” in Openhab documentation. I think Markus has already done a great job of documentation for this, right?

For the second possibility, openhab-cli backup, the situation is worse, cause as far as I know, any documentation is only available from a tons of post on the forum. And the user will have to seek though a hell of posts to get more clear on this option, specially regarding whats beeing backup´d and whats not beeing backup´d.

My intention is to focus on the option #2 openhab-cli backup, and end up with a fully useable doc, which will (from the actual file request) be added to a backup menu of openhab documentation, together with doc of Amanda.

So lets do this the right way, from a non advanced user point of view:

  1. Explaination - (short story, what does it do, and specially, what it do not do).
  2. Requirement - (containing whats required to be able to do openhab-cli backup… Terminal connect, backup storage etc)
  3. How to backup - (command(s) which well lead to the actual succes of the backup. Any special requirements needs to get posted as well
  4. How to restore - (command(s) which will lead to the actual succes of the restore. Any special requirements needs to get posted as well.
  5. Q&A - (optional components backup, like Grafana, InfluxDB (orther persistense modules), how to automatize backup procedure and stuff like that.

I have a feeling lots of the stuff can be added directly from several threads and posts on the forum. But maybe its easier to start all over than to search for it?

Again, this is just a suggestion, no ask or demand for someone else to do this. I know too little about the openhab-cli backup option, so I cant do it alone.
Lets do it together. And do it right first time.

What do you think?

6 Likes

I do not use Amanda and personally fine the documentation overwhelming and not something I recommend for anyone new to Linux.

I agree that making a back up shouldn’t be difficult or confusing so here’s what I have in my personal notes (if you’re new to OH or Linux then I recommend keeping notes for what works, :wink:). I’m using an RPI 3 b+ and installed OH via the openhabian image but this will work for any Linux distro.

#1 Explanation - (short story, what does it do, and especially, what it do not do).

This will backup /etc/openhab2/ and /var/lib/openhab2/
This way, the information about installed addons is backuped, but not the addons itself, so when installing openhab2 new, the actual version of the bindings will be installed.
The only things to backup in addition, are the manually installed addons.

#2 Requirement - (containing what’s required to be able to do openhab-cli backup… Terminal connect, backup storage etc)

Be able to type access the command line and use sudo openhab-cli backup. Most use Putty and SSH connection for command line access as this works on most any OS. Install Putty, enter your servers IP address (this would be your running version of OH), check the default port is 22 then click open. This should take you to a screen where the user name and password is entered. If all goes well you should be at the command line like the image below.
image

#3 How to backup - (command(s) which will lead to the actual success of the backup. Any special requirements need to get posted as well

Use sudo openhab-cli backup or sudo openhab-cli backup-full I have not tried using just backup but know that backup-full works fine. After the backup is complete it will tell you the location of the zipped file. For Linux users, this would be var/lib/openhab2/backups. From here you will need to move the zipped file to your PC, USB, or another safe place. I use FileZilla for moving the zipped file to my PC and it works well.

Note: If installing to a new image you must first run openhab-cli backup on new install so a backup directory gets created, then delete the new system backup. If you have file permission issues
before transferring then use sudo chmod a+rw backups. To change back permissions sudo chmod a-rw backups. You can also use openhabian-config to fix the permissions if this is installed on your setup.

#4 How to restore - (command(s) which will lead to the actual success of the restore. Any special requirements needs to get posted as well.

Place the backup zip file into the backups folder then:
sudo systemctl stop openhab2
openhab-cli restore /path/to/zipped/backup (var/lib/openhab2/backups)
sudo systemctl start openhab2

#5 Q&A - (optional components backup, like Grafana, InfluxDB (other persistence modules), how to automatize backup procedure and stuff like that.

I do it manually but adding this to openhab-cli backup would be ideal.

As mentioned above these steps are for Linux users but it would be nice to have a complete guide that included steps and file locations (including steps for permissions or other snags one may encounter) for Windows, Docker, Mac, etc…

I hope this bit of info helps and thanks @Kim_Andersen for taking the time to put this together. Hopefully others in the community will add to this and include info for other OS’s.

2 Likes

No, that’s just a fatal misunderstanding of yours what openHAB is and what it is not. Backup is not part of openHAB - it is a user’s task to contribute.
Which is exactly the explanation why there is no such menu item below “openHAB” but documentation only below “openHABian”.

Oh dear. That is a fatally wrong and dangerous statement. Backup is a complex task but the term already is not a well-defined one. Any user must understand the eco-system of what he needs and wants to backup and why, when and how often, which filesystems, which files, which devices, which data that affects (config? persistence ? Logs ? raw filesystems ? etc) that affects, what’s the available tools on HIS system what’s the pros and cons of the various approaches, what’s the retention strategy to apply and so on and so on.
Taking your post, you put Amanda and openhab-cli into the same drawer although they are completely different tools to address different stuff and user needs.
Amanda is a backup tool yes, but not part of openHAB. openhab-cli is part of openHAB yes but not a backup tool. It’s a multi-tool to include a config export function at best. Better don’t call that “backup”, please.
Note that openhab-cli is available on non-openHABian systems, too.
A true backup is about more than just the OH config and it is highly dependent on the system you run openHAB on. As OH essentially runs on anything capable of running java, it is close to impossible to just list(!) let alone describe all of the HW/OS combinations, let alone to describe all the backup variations there.
Again, it’s any user’s task to get that understanding right prior to doing their backup, and it is highly specific to the HW and OS you run OH on. So your claim above that users “need not” to read anything else is outright wrong.
And sorry for blaming you, but you didn’t do well in searching. You found the openHABian main document (which is actually just mirrored into the openHAB documentation and I think you didn’t pay attention to that) and you apparently misunderstood it is about openHAB (without ian). It isn’t.
Generalized backup docs on the other hand need not, even must not be part of openHAB documentation because backup is not part of openHAB as I explained above.

Häh? You’re confusing something.
It should link to a backup “menu” ??? No it should not. Docs have no “menu”. I assume you mean a chapter or paragraph ?
It links to a post which explains usage of the openhab-cli tool’s backup option which is exactly describing the part of it’s functions that is relevant to backup.
Which is an intelligent form of documentation particularly for information that could change while docs are static most of the time.
You also need to understand this is different people to contribute - person A to write the tool but he has no access to the docs, and person B to do all docs but to know nothing about the tool other than what person A tells him (or not in this case).
And yes if you don’t like that, change it yourself rather than start a potentially lengthy discussion. Be prepared though that the docs maintainer might see it different like I do.

What the heck are you talking about? Again, there is no “menu”. openhab-cli usage is linked to in item 3 of the list.
Yes, a forum post, but sufficient documentation nonetheless because it is that dead simple. See also below.
The links to Amanda documentation are right below in item 4, so what?

By the way, the paragraph also tells you about openhabian-config menu options that effectively are a frontend UI to openhab-cli so you don’t
even need to use CLI or read the tool-specific docs.

[10:06:57] openhabian@devpi:~$ sudo openhab-cli

Usage:  openhab-cli command [options]

Possible commands:
  backup [--full] [filename]   -- Stores the current configuration of openHAB.
  clean-cache                  -- Cleans the openHAB temporary folders.
  console                      -- Opens the openHAB console.
  info                         -- Displays distribution information.
  reset-ownership              -- Gives openHAB control of its own directories.
  restore filename             -- Restores the openHAB configuration from a backup.
  showlogs                     -- Displays the log messages of openHAB.
  start [--debug]              -- Starts openHAB in the terminal.
  status                       -- Checks to see if openHAB is running.
  stop                         -- Stops any running instance of openHAB.

Which is why I started this thread. Thank you for at least understanding that part!
A small note though - Wether or not backup not being part of openhab, doest NOT mean it shouldn´t be documented in some way.
If backup is not part of openhab, where did the openhab-cli script´s, backup and restore came from ?

No it´s not. Its how you read it and fail to at least understand where this is getting at.
Noone wants to read about birds, when searcing for info about fishes. Its as simple as that.

Which is why documentation is highly important!

Not really. The user who understand the term of backup is only interested in one thing - Be able to get back to some stage of history, before it went wrong, when restoring a backup. How the backup procedure works, which files etc, really isnt a concern, UNLESS the backup isnt backing up everything. This is why there is a need of my #1.

Come on… You´re really doing your best to destroy this thread, right?
If you have at least read my post, clicked the second link, you would have seen openhab-cli is mentioned as a backup-tool. This is NOT MY WORDS god damit! This is the documentation of openHAB:
" Use the openHAB integrated backup tool to interactively backup/restore your openHAB config [menu option 51/52]."

Click the god damn link for crist sake! And then tell me where you end up, and what exactly you´re beeing told from there. Perhaps you should start counting, how many times the word “backup” is mentioned in regard to openhab-cli backup. Then get off my neck with your stupidity about ME not understanding. Its simply impossible to understand, how openhab-cli backup and restore, should not be called “backup” according to you!

So according to you, because you believe it´s impossible to list, openhab is better off with nothing…
Sweat!

Perhaps you should make up your mind.
Is openhab-cli backup and restore script part of openhab? This is a simple yes/no question.
Next, is openhab-cli backup mentioned as a backup-tool? This is a simple yes/no question.

Press the link to the docs, and tell me what you see on the left side. Thats menu´s in my world… You world seem a whole lot different… I really dont care. I´ll bet you, that most people will call it menu´s, except you ofcouse!

This is not something I need to understand. This is the reason I started this thread. And for now, you dont seem to have contributed with anything, except trying to ruin it.

You´ll never be able to understand. So I wont try explain this to you, again!

1 Like

Thank you very much!.. I´m very pleased to see your contribution on this one @H102
When we have a few more, I´ll try to summon it into a finished document!

I may be commenting some part of it later.

1 Like

It would be great to have steps for Windows, Docker, etc… users as well. :grinning:

Totally agree. And we can always extend the doc to whatever we like :smiley:

1 Like

I have a few comments for your contribution…
Whenever I ask a question or comment on anything, I do not expect you to answer, if you dont know. Maybe others will step in and answer, (this is how I wish this documentation beeing developed :slight_smile: ). And everyone is free to comment.
So look at my questions and comments is for everyone interesting is participating in development this doc.

#1 Nice contribution…
Maybe we could add some more specification regarding whats not beeing backup´d… Something like, “*manually installed addons in /usr/shared/openhab2/addons/… *”, just to be more specific and like “forcing” the user to pay attention to this.

#2 I really like that part, specially with the screendump. (Pictures says a 1000 words).

#3 Do you (or anyone else) know the difference between openhab-cli backup and openhab-cli backup–full ?
I think it´s important to know and explain the difference, otherweise people may get unsure and maybe pick the wrong one. (I do not know the difference).

Also we could write, that the backup procedure will zip the files into one, and that its possible to specifiy the filename of the backup? (a example for that).

Moving the file can be done in several ways. Its nice to have more options to choose from.
Personlly I move the file using WinScp (Windows SSH utility).
So now we have FileZilla and WinScp. I´m thinking a note about Samba directories might be usefull as well. (either move the file from the backup folder to a shared folder, or share the backup folder).

#4 like this… Right now I´m not sure if it needs more explanation.

I´m doing alot of thinking about #5. An option of using openhab-cli backup to move from one system to another has been mentioned a few times on the forum. This could be a very usefull information for #5. But before we suggest such a option, I need to make 100% sure, that it will work, or if there are any special requiements, such as the openhab system has to be the same version etc. which has to be specified.

Thats it for now… Lets have some more inputs to this!

Stop nit-picking words and stop focusing on openhab-cli, please … all it does is it just exports the OH config. Of course anyone can call it a backup tool but that is misleading. As I tried to explain before, it does just a minor fraction of what a “backup” tool should provide and what Amanda does provide.
To avoid more misunderstandings, I just changed that part of the docs for you. It’s now called by it’s name.

Your notion of “menu” is a little strange because technically, it isn’t a link to something on the left hand side frame (the menu, that is) but to so paragraph (or to precise, a HTML anchor) INSIDE the document in the right hand side frame. That’s why your description is confusing.
But ok, nothing worth battling about.
So I understand you want either another document to appear in the right frame when you click on the “backup tool” link or at least you want it to jump to a section to explain how to use openhab-cli.
Ok. Technically, it does just that. Just that the target document is a community post because the author of the tool did not provide any separate documentation.
So what? Provide the docs Pull Request with that page and changed link destination and you’re set. But as I said, be prepared that the docs maintainer does not see it the way you do.
Note that technically the page you change is part of openHABian docs but openhab-cli is not hence any request to document it there would probably be denied. So you must provide a new page, then the incriminated link in the openHABian document can be changed to point there.

And remember it’s just the tool to export/import the OH config. Not what people will expect to get from that when you call it a “backup” tool.

Yes, backup is a word with different meanings.

Improving the documentation is definitely helpful, but since OH shold also become easier for newbies, a “Create & Restore configuration” section in the UI would be definitely needed. I’ve created an issue for that.

5 Likes

Definitely would big step forward! I guess thats the main reason why openhab is not as popular as others: not newbie-friendly! OpenHABian supports some kind of backup&restore (openhabian-config) but never read full docs nor tried it.

No… That IS the purpose! I wrote that in my first post. Go read it again. If you dont like it, too bad! Noone is forcing you to!

Anyone do seem to call it like that. So everyone are wrong, and you´re right?
Does it really matter? Its an utility to backup (or if your prefere, copy) the config of openHAB in an easy way, and to restore it back again, leaving the config at the exact same time of history where the copying was done.
To me, that sound pretty much like a simple and usefull backup procedure!!

But you dont seem to like it beeing part of the openhab documentation…

So openhab is misleading its users?
Look at this thread as a try to fix it then! And not a stupid discussion of what a backup is. openhab-cli has already been adviced as backup option a zillion times in the forum! Now, when I want it documented to become userfriendly, you´re telling us, its not a “true” backup solution…
You simply have a way of picking your timing real bad! And a highly strange way of defining “backup”.
But you´re so wrong!! Backup is not a specific defined procedure.
Backup is an action. A user copying files from one storage to another, is also making a backup.

But it does something. And this “something” is what I believe is worth documenting, rather than having nothing.
You have another opinion, I respect that. But unless you can argue better for not doing anything, I and others (hopefully) will continue!

My suggesting is a backup option on the left side, exactly like all the other options (links if you like) which contains documentations of openHAB.
As I wrote in my first post. When users want to know, they turn to the documentation. Right now the information regarding backup is highly limited, and points to the community only. This is not the way documentation is suppose to be, unless you truely believe documentations belongs to a forum post.
If you really do believe that, then you can start remove all the other options (links if you like) as well, and simply points everything to the forum. I dont think (hope not) thats what you really want.

Which to me is a big mistake.
But again, as I mentioned. Just because someone did not do its job, I see no reason why others cant. Ofcouse I cant fully document openhab-cli. If thats whats required of the maintainers, I see nowhere any people beeing able to help with documentation, except for the authors! Thats hopefully not the way you want openhab to become!

First - Dont you tell me/us what people will expect to get, untill you have seen the documentation. Its my job, as well as those who participate in this thread to make the documentation come through, and to make sure the user expectations will be whatever is gona be in the documentation, and nothing more.

Second - as mentioned several times now. Openhab-cli backup/restore has been mentioned/adviced/suggested as a backup option a zillion times on the forum. So in case you believe this is damaging anything, the damage has already been done long long time ago. Why the hell do you react now sabotaging those who are trying to make it easier to comprehend?

Very nice suggestion… And yes, even better having it in a UI.

openhab-cli backup and openhab-cli restore are simply shortcuts on Linux packaged installations. All they do is run the backup and restore scripts available from the openhab distribution.

These scripts are available on any openhab system, including Windows and Mac and they all work in the same way. A backup on Windows can be restored in Linux for example.

I’d suggest not mentioning openhab-cli at all when specifically talking about openHAB’s backup mechanisms. Instead this can be mentioned on the installation page.

Thank you alot for clarify this part.
Just to make 100% clear - Does it mean that running the backup script on openhab 2.0 and restore in 2.5.5 (or any other combination) will work fine?

Why?

It might do at the installation page allright. I´m mainly interested in having the backup (word as well as an easy procedure) pushed forward somehow, because I think its a highly important task when dealing with a system such as a smart home system which is meant to be running 24/7.

Good initiative to improve this part. I did started with openhab 2 years ago without any Linux experience and a very important thing is to have a backup of your configuration. And when you are new, it’s sometimes hard to follow explanations since somebody expects another to have some base knowledge. But with an important topic like a backup/copy of your config (making sure you do have to start all over again when you screw it) is a newby explanation very helpful.
Unfortunately I cannot help you at the moment with the open questions, but will follow the topic and jump in if I can.

1 Like

Thank you very much for your support… Whenever you feel like, you just jump in and add whatever is on your mind! (regarding the subject :smiley: ).

Not quite, files you copy in from a backup on an older version would overwrite files in the newer version. If there are necessary changes, such as a keyword change then the restore script won’t do them automatically.

Because it’s linuxpkg specific. Ideally you would talk about the backup procedure once. A single sentence describing the openhab-cli shortcut will be okay, but for documentation sake “The included backup script” is a cover all for every OS.

Okay thats what I thought. Just needed someone to clarify.
I have seen some using it to move the configuration from one system to another (like from a Rpi3 to Rpi4). I guess this would only be safe to do, if the destination system is running the same openhab version. Which make it highly important to notice.
It can however become a problem, if someone is running an older version, and this version isnt available for downloading, (ie 2.0) Then the user will have to update the system to latest before doing the backup. Which can become a problem, if the system is crashed.
Are all older openhab versions available for downloading?

Another question.
Do you know whats the difference between openhab-cli backup and openhab-cli backup --full is? Is it only cache included in --full? Personally I wouldnt recommend backup a cache. I prefere the system itself rebuild the cache insted, even though it will take a while. But it needs to be explained for others who may have another opinion about the cache.

I have no idea how Mac works. But in windows I would assume the user would just copy the folders, (or make their own scripts which basicly do the same). In worse case, they could use Windows backup and a scheldule task. I dont quite see why a windows user would start a ssh session to enter linux (openhab-cli) commands. But it has been too long since I tried openhab for windows, so I wouldnt know if this is required.

Again, for the sake of documentation of all OS: $OPENHAB_RUNTIME/bin/backup --full

The --full option includes cache and tmp directories. Useful now if you want exactly the same binding versions. Without the option the backup is configuration only, and much more likely to work across different versions.

Mac and Linux run the $OPENHAB_RUNTIME/bin/backup script, Windows runs the $OPENHAB_RUNTIME/bin/backup.bat script. These do the same thing which is not as simple as copying the files across. There are a few system files in the $OPENHAB_USERDATA directory that should not be changed or replaced.