HowTo: Manage OpenHab 2 configurations

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.

How can I enable Simple Mode via configuration files?

  1. Why would you WANT to when most everybody here recommends NOT enabling it? It causes more issues than it solves.

  2. It is a PaperUI setting, The PAperUI access OH through the OH API so you cannot enable simple mode outside the PaperUI.

1 Like

The setting can be stored in the “runtime.cfg” ( last entry in file), to be found in folder openhab2/services/
Note that such change is read only on the next startup of openhab.


Create a filename org.eclipse.smarthome.links.cfg with autoLinks=true inside userdata/etc directory. For openhabian it is /var/lib/openhab2/etc/.

Other way is to use openhab console (one which you log in at port 8101):

config:edit org.eclipse.smarthome.links
config:set autoLinks true

You can also use config:property-list or config:property-get autoLinks to retrieve current setting. It is worth to note that above way be scripted through SSH interface without a need to have physical access to disk. (my way goes one level lower than solution proposed by @opus)


Though that way is not guaranteed to survive an upgrade process. In general, the files in that folder are not guaranteed to not become replaced on an upgrade, which is why runtime.cfg exists in the first place.

In practice those files often do not get replaced after you’ve edited them which raises a wholly different problem. Your edited file will not receive the updated contents as part of the upgrade.

In general, using runtime.cfg is the preferred approach.


Thank you, I found it at runtime.cfg.
However I’m curious where the configuration of autoLinks when I configure it via PaperUI.
I see that in runtime.cfg #org.eclipse.smarthome.links:autoLinks=false although I already enabled simplemode in PaperUI.

PaperUI does not store its settings in the runtime.cfg file, however when openhab is started that files read. The line you see is commented out by the “#” at the beginning.

I think it might be arguable. The runtime.cfg is translated to OSGi Configuration Admin layer which is persisted in userdata folder. See that the syntax of runtime.cfg is <config-id>:<property>=<value> for a reason.
On my local setup I see that this setting is retained over restart when I changed it over paperui. You can try with config:list|grep autoLinks.

1 Like