HowTo: Manage OpenHab 2 configurations

There was also another issue related to the Ecobee binding, where stale configuration was the cause.

Dimitris, you are clearly the knowledgable person to properly articulate these points in a new issue report! I would be very happy if you did. :smile:


I wouldn’t say this. PaperUI is great but it isn’t really complete. For example, you can’t set configuration parameters on zwave devices nor can you create sitemaps and such. A number of users, to include Kai, do not use PaperUI at all.

I’d say “an alternative way of working …”

This is correct.

Great write up!

not sure if this is the right track.

I installed openhab2 some days ago. I started writing my config files for sitemaps, things, items,etc. but somehow I still got data in my system that probablly belongs to a _default site that was created on startup somehow while playing around.

I cannot see the things or items in the UIs, but I still see the site in HABmin and the inconsisten data of those things/items causes a lot of exceptions during startup.

How can I reset my openhab2 installation to a clean state?
All tips here in the first post do not work and I get errors…

Thanks for your help.

If all of your configuration is in files (no configuration with paper UI beside addon installation), you could simply backup these files and make a new installation (don’t choose demo!).

However, you could use the REST API or karaf console to get rid of these outworn elements (you will have to find them manually…)

Hi @mbuchberger1967,

There has been a major change since I wrote the original post with regards to how OH2 stores the configs. See here:

Many of the commands in the original post still work but they are more related to bindings and their configurations (not so much for items, sitemaps, things, etc)

I would go the way that @Udo_Hartmann recommends (keep your customized configuration files and reinstall)

Another way would be: Karaf console, then:

smarthome:links clear
smarthome:items clear
smarthome:things clear

This will clear out whatever OH2 has stored internally. Make sure that you have removed the _default files, keep your files in the configuration directories and OH2 will re-read them and populate the internal (json) database.

Hey @Dim, @Udo_Hartmann, @rlkoshak and @watou,
that’s quite an interesting discussion you’ve got going on here. Would you mind to rephrase whatever is fitting for a) the FAQs or b) a docs article? We need to start organizing information, especially with the upcoming attention for the openHAB 2.0 GA release…

1 Like

is it really necessary to ssh into the karaf console to change configuations? openhab is installed on the system im working on so should i not be able to access these files directly with a text editor?

Err … you edit files from within Karaf ? Didn’t even know that’s possible …
Don’t confuse that with the most common way which is to SSH into the machine. Or share the config directory via network to a desktop computer and edit it there, preferrably using VS code extensions nowadays.

1 Like

Is there a way to dump the config done from paperUI, so I can use it in the items/service/thing configuration files ?

This is because I prefer to have a stored in file copy of everything. paperUI is great when starting, but having a config file version is easier to recover (for me)

For instance I did setup my rfxCOM this morning and did setup all the rollershutters.

Things were created in paperUI (easier for syntax), but items and sitemap done in config files. I’d like to port all my “things” from paperUI to config files (as I understand, those will be read at restart or at any new start, so also after an upgrade)

There is no automated tool to export Things from the JSONDB into .things files. Furthermore, not all bindings support Things defined in .things files yet. So depending on what bindings you have, it may not be possible to go all text config. Those bindings that do support .things files will have the syntax defined in their README.

For the Zwave binding, support for .things files only exists in the development branch.

Finally, if you were not aware, everything you do in PaperUI is saved in a text file of sorts. In /var/lib/openhab2/jsondb there are several JSON formatted text files which is where all your Things and Items that you create in PaperUI get saved. It is text-based and human readable. And it might be possible for an enterprising individual to create a script to convert the JSONDB to .things files, but as each binding has its own parameters and syntax to some degree it might require special code for each binding to make it work.

1 Like

Regarding the questions of configuring things in json db vs. things in files, may I ask for a general clarification:

Which way is the way openHAB is finally aiming at?

From what I understood, configuration files are read and then copied to the database. Also, the REST API provides read and write access to the database. So I assume that the database is where it all should eventually end, am I right?

Both will remain supported for the foreseeable future. However, JSONDB will become the default and recommended approach at some point. There are still a number of features missing from PaperUI to make this possible though.

This is not correct. OH reads the Items from the .items file and reads the Items from JSONDB and stores them internally in memory. It does not copy the Items from the .items files to the DB. The two are kept separately.

1 Like

I believe the same.

Don’t laugh (i did this in 3 seconds)… here is my understanding (this is oversimplified):

All config inputs (PaperUI, $OPENHAB_CONF, REST, etc) interact with the ConfigAdmin which stores data in HashMaps
Some of that data end up in the jsonDB (not all) and some other in Userdata

for example:
/var/lib/openhab2/config/org/openhab/addons.config contains the parameters that we set in /etc/openhab2/services/addons.cfg (this file is parsed, and entered in ConfigAdmin with config pid: org.openhab.addons)

I would also like to have everything being dumped from the OSGi ConfigAdmin into jsonDB :stuck_out_tongue:

Of course, it is much more complicated than I described above (with Managed Items, etc) and I am reading more on the topic. There are many nice resources out there: example:


This is not correct. OH reads the Items from the .items file and reads the Items from JSONDB and stores them internally in memory. It does not copy the Items from the .items files to the DB. The two are kept separately.

Thanks for clarifying. I had read somewhere that config files are copied and that, therefore, items which were removed from the config file, are not deleted from the internal database and need to be deleted from it manually.

this is true for configuration (*.cfg files) related parameters (not for items)

If you remove an item from a flat *.items file, it should be removed also from OH2.
Items coming from flat files are not stored in an another destination (in $OPENHAB_USERDATA or jsonDB or somewhere else) after they have been loaded by OH2 in memory. Same applies for Things in flat files as well.

There is a workaround the stale configs issue: place the config pid as the first line in your *.cfg
This will overwrite any existing stuff in the ConfigAdmin and as a result, clean the output *.config file from old stuff and place only the new parameters coming from the *.cfg file

example for addons.cfg:

package = expert
ui = ...
voice =....
so forth

This workaround for the stale configs applies to all configurations (*.cfg files) that have a config PID… e.g. mqtt, influxdb, mail, etc, etc… mostly stuff in /etc/openhab2/services/

This is because the ConfigAdmin will read both *.cfg and *.config files and load all parameters.
Stuff in *.cfg take precedence but if you remove (not change) a parameter from *.cfg, it does not get removed from the *.config

1 Like

This is the first I’m really seeing this explained. A quick tutorial post would be great so it is easier to find and link to when the stale config parameters issue pops up on the forum.

but… from what I understand, this story with the pid: is a temporary measure
I believe that they are working towards a more robust solution where there will be checks in the code to “clean up” stale configs without any user intervention.

Anyway, we are in the “managing OH2 configurations” HowTo thread, so people can find this stuff here in theory.

(and I didn’t do a very good job of explaining them… I can do better :wink:)

1 Like

in case this is about a binidng that has an OH1 and OH2 version, for the pid process should I take pid:org.openhab.mqtt1 of pid:org.openhab.mqtt for the version 1 binding config? Same for MODBUS for example

The github issue was closed a long time ago, this should not be needed anymore.