Suggested Upgrade Path From B4

Hello -

I am currently working in OH2, B4 and I would really like to upgrade to a more current version to take advantage of some of the fixes as well as being able to install HABPanel through PaperUI.

I’ve read quite a few posts that running the upgrade can cause deletions and corruption of the system.

What is the safest way to upgrade to one of the newer builds without destroying what I currently have in place?



I recommend the following:

Go through PaperUI and copy the names of all your installed add-ons to services/addons.cfg.

There is a section in addons.cfg for each tab in PaperUI. Just list the add-ons separating them with a comma.

For example, this is my addons.cfg

# The base installation package of this openHAB instance (default is "standard")
# Valid options:
#   - minimal  : Installation only with dashboard, but no UIs or other addons
#   - standard : Typical installation with all standards UIs
#   - demo     : A demo setup which includes UIs, a few bindings, config files etc.
#package = minimal

# Access Remote Add-on Repositories
# Defines whether the remote openHAB add-on repository should be used for browsing and installing add-ons.
# This not only makes latest snapshots of add-ons available, it is also required for the installation of
# any legacy 1.x add-on and all experimental features. (default is false for offline distro, true for online distro)
remote = true

# Include legacy 1.x bindings. If set to true, it also allows the installation of 1.x bindings for which there is
# already a 2.x version available (requires remote repo access, see above). (default is false)
legacy = true

# Include experimental add-ons. If set to true, it also allows the installation of extensions that are not (yet) part
# of the official distribution and need further testing (requires remote repo access, see above). (default is false)
experimental = true

# A comma-separated list of bindings to install (e.g. "sonos,knx,zwave")
binding = zwave,astro1,http,mqtt,nest,networkhealth

# A comma-separated list of UIs to install (e.g. "basic,paper")
ui = paper,basic,habmin,habpanel

# A comma-separated list of persistence services to install (e.g. "rrd4j,jpa")
persistence = influxdb,rrd4j,mapdb

# A comma-separated list of actions to install (e.g. "mail,pushover")
action = nma,mail

# A comma-separated list of transformation services to install (e.g. "map,jsonpath")
transformation = xslt,map,regex,javascript

# A comma-separated list of voice services to install (e.g. "marytts,freetts")
voice =

# A comma-separated list of miscellaneous services to install (e.g. "myopenhab")
misc = myopenhab

If you are in doubt, you can find the name of an add-on in PaperUI by looking at the smaller grey text under the add-on’s main title. Just ignore the “binding-”, “transform-”, etc parts. For example, given:

I would put astro1 in addons.cfg in the binding filed. If I were using the 2.0 version I’d just put astro.

You will also notice that some of the parameters from Configuration -> System are also defined here. Mainly enabling Legacy 1.x bindings, and Experimental bindings.

Next you want to move your other settings to runtime.cfg.

This one may be a little more challenging because new parameters keep being added and I don’t know if they are all adequately identified and documented.

Here is my runtime.cfg:

# setting this to true will automatically approve all inbox entries and create Things for them,
# so that they are immediately available in the system (default is false)

# This setting allows to switch between a "simple" and an "advanced" mode for item management.
# In simple mode (autoLinks=true), links and their according items are automatically created for new Things.
# In advanced mode (autoLinks=false), the user has the full control about which items channels are linked to.
# Existing links will remain untouched. (default is true)


# Basic UI
# Icons can be disabled
# Icons can be shown as PNG or SVG images
# Default: PNG

# Classic UI
# Defining the default sitemap to use

# The icon type to use, either png or svg

# Disable in-memory caching of html fragments
# If this is true, on every request the html files are loaded from disk (default is false)

Hopefully you will recognize some of these parameters from PaperUI. Important ones are the iconType and default sitemap for Basic and Classic UIs, auto links, and your default persistence.

There are more parameters than this though. If you have set something within PaperUI let me know and I’ll see if I can figure out what to set.

If you configured any binding through PaperUI on the Configurations -> Binding page you may want/need to move those settings to that binding’s cfg file.

If you changed any other files in userdata, such as the logging config, make a copy of that file in your /etc/openhab2 folder or somewhere safe.

If you create any Items using PaperUI or Habmin, you will want to move those into .items files. The next step is going to potentially blow away your PaperUI/Habmin created Items unfortunately. I’m not really sure (I run in a Docker container so upgrades work slightly differently for me) but this is a good step to be safe rather than sorry.

There have been a ton of changes since beta4 with one very important one being a rearrangement and migration of some files in userdata. In particular some config files have been moved out of the karaf runtime folder into the etc folder such as the logging config file.

At this point you are in a good position to upgrade. All your add-ons will automatically be reinstalled. Your Items will be protected from any database corruptions and in a worst case scenario you may have all your automatically discovered Things disappear. In this case they will simply be rediscovered and as a result their IDs may change so you will have to copy them over the old IDs in your .items files.

You also might have to go through some of the initial set again for bindings that require it, like myopenhab and nest. Again, I’m not certain since upgrades work differently for me so I don’t know what gets preserved and what gets wiped out.

You are also in a good position to continue to upgrade nightly if desired because even in a worst case scenario of a corrupted configuration database, you are fine because all your configuration is outside the DBs.

Once the devs finish fixing the upgrades so they don’t wipe out your bindings I think it will be safe to move back to using PaperUI/Habmin for most of your binding installation and configuration.