I must admit that this part of the thread doesn’t quite help to make the latent confusion on my side smaller.
What I figured: there’s an upgradeTool, which is only relevant for managed configs and not for file-based configs. And there is an upgrade script, which is not the same thing and also relevant for purely file-based configs. The upgrade script must be run (after?) an upgrade or after transferring configuration. There’s also an update script in some installations, which automatically downloads a new version. But the update script is something else than the upgrade script (or isn’t it?).
I understand that there are many different variants in many different scenarios. Let’s take a rather straightforward and for me particularly relevant one: I am just talking about Linux packet-based installations.
I was recommended to upgrade only occasionally when needed, and I tend to run LTS operating system versions for many years. But the time has come: I need to pull my setup forward to new versions, on the OS level and also on the OH level. An extreme case where this would become necessary - and one that I was already facing years ago - is: hardware fault of the old machine, harddisk burnt. But yay, I have my OH configuration backup made with openhab-cli.
I buy a shiny new machine, set up a new OS installation with much newer software, and install the current OH version as a package. The new OS version doesn’t easily run the old OH versions (dependencies, Java versions, you name it). The old OS version doesn’t support my new hardware. So that’s where I am standing: new OH version and no reasonable way back, plus my backup from the older version.
The new OH release from the package gets automatically started after I installed it. It probably spams the logs with all the initial-startup errors. I learned that I just need to stand this without getting worried. So I wait for a while, stop the service, start it again, and notice that now it’s running smoothly with an empty configuration.
I stop the OH service (again).
I restore the configuration backup from my old OH version (which, if I figured it correctly, essentially boils down to copy&paste of all configuration data from the backup archive).
I run the upgradeTool. (Or do I run the upgrade script? - probably not, because it’s a packet-based installation?) (Or the update script? - probably not, because it likely won’t exist in my packet-based installation, and because I definitely wouldn’t want it to download another OH version over my packet-based one?)
I re-start the OH service, keep my fingers crossed, and enjoy a smoothly running new OH version with my old configuration on my shiny new machine?
Did I figure that out correctly? It seems to me this is what some people here were saying, while others seemed to be disagreeing. And the details especially regarding what I need to do after restoring the configuration are still somewhat diffuse to me.
Edit: There’s a step missing - re-installing the bindings that my configuration need. Would that be step 2b? or step 7?
I can see why you’re so confused, but I think you’re overthinking and overcomplicating things.
Unfortunately I can’t give any advice on apt-based installation. I use Docker but perhaps the only difference here is the actual paths for the key directories which you probably already knew, but I’ll list them below anyway.
My machine is a Xeon cpu, 128GB RAM, 8 HDDs (which are mostly multiple duplicate copies of my data backups + snapshots). I’m running Ubuntu 20 - yes too lazy to upgrade it, but I think I’ll upgrade the machine and install the latest Ubuntu LTS, if and when there’s a new hardware that I like.
With docker, I just have three mountpoints:
conf
userdata
addons
Those are the only three directories that I back up. But I rarely if ever had the need to do any restore. Definitely never because of any upgrades or downgrades.
I use file-based config.
To upgrade my openhab, I just edit the docker-compose so it pulls the new version, then tell docker to recreate the image (or whatever it’s called). So it’s just two commands chained like this: docker-compose pull && docker-compose up -d
voila, I have a new version.
In fact I use 5.2-snapshots so I do this quite often - between every week to every month.
What I’m trying to say is, don’t worry about running upgradeTool, updatetool, or upgradescript etc. All of this stuff is executed for you automatically whenever openhab detects that your current installation is older than the currently running version. It knows this based on what’s in your userdata.
I have never had to run any of this manually.
Most of the time I can also very easily downgrade, e.g. from 5.2-snapshot to 5.1.1, or 5.1.0, or 5.0.1 or whatever. Upgrade / downgrade is extremely simple with docker.
I also run a separate instance of openhab docker for development, testing and fooling around. They listen on different ports.
That’s perfectly possible as long as you still have your old installation, and it’s still running. It’s not possible if the machine burnt and you need to start from scratch on a new basis. As I said, this is what once happened to me. It caused a lot of headache. The headaches were of course not only because of OH, but OH proved the by far most difficult part to handle.
I think restoring a backup from an earlier version is a perfectly valid use case, especially if something went really wrong and especially if you tend to stay with older versions for longer times because you’re in a mission-criticial production deployment. It could also become relevant if I want to set up a test installation on a second machine (or in a VM). And I just can’t figure out how it’s meant to be done.
That’s when you restore those 3 directories from your backup, then install openhab on top of it - or you can install a fresh openhab then restore your backup. I don’t think the order matters.
If you want the least hassle, install the same OH version that you used to have. Or if you’re feeling brave, install a newer version. As I said it wiill detect your version and do whatever it needs to do. The only catch is that it will restart once (by itself), and if necessary restart it again after a while. Not sure if it’s necessary though.
I think it is important to distinct between Docker @jimtng and all other installations.
The Docker container checks the config and data on startup and applies the required steps if it notices that the config and data is from and older openHAB version. The other installation methods (Linux & Homebrew package, manual) don’t do that.
They only run the upgrade steps if their upgrade script is called. To reduce the confusion:
Linux and Homebrew package handle the upgrade steps including upgradetool execution through their package manager.
On manual installs, upgrading should be performed through the update script included in the distribution, which will handle the upgrade steps.
If I read all the above correctly, it would help users really much if the manual install would behave similarly to the Docker container. IMO the packages don’t neccassarily need to do that, as you are expected to upgrade them through the package manager as you’ve installed them through it. It would probably make more sense to run the upgrade steps as part of the restore command of the openhab-cli tool that is shipped with the packages.
But that’s not going to happen if the package is already installed before the backup is restored, like in the scenario that I described. Right? So then I manually run the upgradeTool after restoring and before starting OH again, and that’s it?
Ideally you would install the old openHAB version on the new machine, restore the backup, and then upgrade.
Running the upgradetool is only part of the upgrade process, breaking change warnings, and if needed file modifications are also applied by the package scripts.
I am thinking how be approach that situation best. We shouldn’t replicate the same functionality across several places, ideally I think the steps that are done by the package upgrade script should be moved into the update script in distro so they are available cross platform, and can be reused across packages, docker and manual installs. And I think it would be wrong behaviour for a package to attempt upgrade steps on every start.
Yes, I figured that much. But very old OH versions usually won’t easily run on new OS versions. You’ll be running into all sorts of dependency and version availability issues. I went throught it.
I think in a really good world, OH would just check whether it’s seeing an old config file upon every startup, and trigger the necessary things when it does so. In a better yet world, it would only do so after getting confirmation from the user. And in a perfect world, it would just be able to work with the old configuration without needing any sort of conversion.
I think you don’t need to run that old openHAB version you restore from, you just need to install it, restore backup, then upgrade the package.
This is what the Docker container does, it has to because otherwise it can’t notice it is upgraded – contrary to the packages where the package manager knows that. The manual installation should behave similarly to the Docker image IMO.
I am a bit hesitant whether the packages should also check on every start, because there upgrades are handled by the package manager and can’t happen “quietly”. For the packages, I think it would be enough to run the upgrade procedure on package upgrade AND backup restore.
Indeed. But as I said: the packet manager will usually not give me any option to even install it. Packet not available in the repository. Unfulfilled (i.e., unfulfillable) dependencies. I might be able to scratch an old packet of the old version somewhere out of an ancient repository and try to force install it against all warnings and missing dependencies, hoping that it won’t kill itself when it automatically tries to start after that installation. But is that the user experience we’re talking about here?
Any language that runs on linux, windows and macos.
The permission and ownership part will be os-specific, but can be a branch inside the application launcher.
But at least the overall logic is unified an os agnostic.
I’ve done similar things in python, but I know it’s hated by some maintainers so I am not going to suggest that.
I agree. But checking some preconditions (e.g. if the cache is stale then purge) should definitely happen at every start.
Imho there are two use cases which should be separated which are now mixed:
Upgrade of an existing installation (e.g. from 5.0 → 5.1)
start of an existing installation with a possible configuration upgrade.
Option 1 should always be triggered through the user while option 2 should be checked every time.
The question is if doing this check is “cheap” or not. If it’s done in a few milliseconds, it doesn’t really matter if it’s run every time, and that would certainly “plug some holes” that might cause problems for users, like restoring configuration from backup “manually”.
in my view, on every startup, there should just be a check in the jsondb for the version (if it doesn’t exist yet, there should be a file there that contains the version of the configuration). If the version of OH being started is after the version found in the jsondb, ideally there should be a new UI, proposing to clear the cache, run the upgrade tool, show breaking changes… If we don’t have that yet, it could just automatically clear cache and tmp, run the upgrade tool and update the version in the db. Is there anything else the upgrade scripts do? Do we need to take care of changes in cfg files. I beliece sometimes upgrade scripts do things there as well. Basically bring the functionality of the upgrade scrips inside the start script, to run after a check.
In my view, that would bring us to a point where just copying in the configuration would not lead to problems beyond having to adjust file based configurations when there are breaking changes.
I know the issue with file locations, and what to copy and what not. But even that becomes less of an issue if cache and tmp are cleared.
There is a good deal of that added already and more being added every release. That’s basically what the health check does for you. Right now it only really checks the semantic model, orphaned links, and persistence configs but I would hope it will be expanded to include more in the future.
But for now, there really is no substitute to looking at the logs periodically for errors.
Correct.
Correct. Think of it like this, the upgradeTool is a part of the upgrade script. The upgrade script will invoke the upgradeTool as one of the steps it takes to prepare a config to run with a new version of OH which includes clearing the cache and in some cases updating some files in userdata/etc.
Yes but only if the configuration comes from a different version of OH than it’s being transferred to.
I think it depends on the distro. As far as I know, only Windows has such a script.
Is this theoretical or something you’ve faced? On occasion, I’ve had to install old OH’s on newer OS (e.g. OH 2.5 on Debian Bookworm, and Java 8 and OH 2.5 installed and ran without problem). I’ve never had to do Java 11 or Java 17 but if 8 worked I would assume those would work too. Does it not?
If it’s an empty config there will be no errors because there is nothing configured that depends on specific add-ons being installed. It’s only when there is already a configuration in place that depends on certain add-ons being installed that errors may occur. The root cause is the clearing of the cache causes a reinstallation of all the add-ons and that takes time. OH doesn’t (yet?) have a way to make OH wait until the add-ons are ready before proceeding with the boot. So stuff may start happening (e.g. rules triggering) before the add-ons it needs to run are installed.
tl;dr: this step is unnecessary. Skip to step 3.
Or use openhab-cli restore.
The package installer in this case never had the change to run an upgrade on anything becuase there was no config there. So if the config you restored was for a different version of OH, you’d run the upgrade script. The upgrade script will run the upgradeTool for you.
If you already had a config in place and just upgraded through the package manager (e.g. sudo apt upgrade) the package installer would have invoked the upgrade script as part of that process.
Now is where you may need to do the whole wait and restart steps. The ujpgrade script, whether invoked by you or invoked by the package installer will have cleared the cache. Stuff may start happening before the add-ons they need are reinstalled. So wait for the add-ons to get installed and restart is the current best practice. Hopefully this will get fixed but until it is …
You don’t have to do this at all unless they were installed from the marketplace (i.,e. unofficial add-ons). And there, make sure there is a version compatible with this version of OH first.
“container”.
Almost no one does. But Windows and users who use a manual installation of OH do.
The specific mechanism in Docker is a little different but over all apt/yum will work do the same steps.
The key thing though is that the config for OH is already in place before the upgrade. If you take a backup of a config and restore it to an already installed and running OH, the upgrade script is not invoked automatically in that one circumstance no matter how OH is installed.
Actually the order does matter. If you restore it before installing OH, the package installers should see that and run the upgrade script for you. If you restore it after installing OH, you have to run the upgrade script manually.
In Docker we are spoiled because in both cases the container will run the upgrade script for you.
Indeed, this would be a big improvement.
One or the other would need to be done to handle the case of moving a config to a new machine where the OH already installed there is a different version from the backups.
For now, you manually run the upgrade script. The upgrade script will clear the cache so there might the that first start troubles so a second restart may be required.
But yes, that’s it.
If the restore is made smarter to run upgrade for you, you wouldn’t need to run the ujpgrade script manually at all.
But it could check to see if an upgrade is needed on every startup. That’s really what Docker does. I don’t know how easy it would be for other types installs to do that though. There needs to be some sort of “this is the version of OH” somewhere that is separate from “this is the version of OH these configs were running in”.
In Docker it’s easy because it ships with a separate copy of userdata/etc populated with the original distro files. It just needs to check the versions file in the active and the copy. Docker already needs these files (so it can copy them into an empty userdata folder when necessary) there so it’s no extra burden.
I haven’t looked at in many years, but I actually submitted the first version of the upgrade logic for the Docker container. I don’t think it has changed much over the years.
You should have userdata/logs/update.log. That shows all the steps taken during an upgrade and shows important notes and breaking changes and such. Here’s the contents of my latest update.log.
Image and userdata versions differ! Starting an upgrade.
You can find backup of userdata in /openhab/userdata/backup/userdata-2025-12-23T09-27-43.tar
################################################
openHAB Docker update script
################################################
The script will attempt to update openHAB to version 5.1.0
Please read the following ESC[32mnotesESC[m and ESC[31mwarningsESC[m:
Important notes for version 5.1.0:
ESC[31mWarning:ESC[m CORE: Persistence default strategies are removed and not applied automatically anymore. Managed persistence configurations are updated automatically. If you have a file based configuration with an existing .persist file, you may have to update your configuration: remove "default" from Strategies and make sure all Items definitions have a strategy defined.
ESC[31mWarning:ESC[m AhaWasteCollection Binding: A typo was corrected in the lightweight channel id, you may need to correct your configuration.
ESC[31mWarning:ESC[m Allplay Binding: Due to limited usage and increasing maintenance issues, this binding has been removed.
ESC[31mWarning:ESC[m Automower Binding: Restructured to modular things with auto-discovery of datapoints. New things and channels will need to be linked, existing items need to be adjusted.
ESC[31mWarning:ESC[m evcc Binding: Restructured to modular things with auto-discovery of datapoints. You must reconfigure settings, recreate Things, and adjust Items as previous configurations are incompatible.
ESC[31mWarning:ESC[m Folderwatcher Binding: A typo was corrected in the AzureBlob thing parameter containerPath. You may need to reconfigure this parameter.
ESC[31mWarning:ESC[m Freebox Binding: The binding has been removed from the distribution. You should consider migrating to the FreeboxOS binding.
ESC[31mWarning:ESC[m Home Assistant Binding: The binding has been split from the main MQTT binding, and will not be auto-installed. If you use this binding, it will need to be manually re-installed. You may also need to re-configure the binding if discovery settings have been customized.
ESC[31mWarning:ESC[m Homie Binding: The binding has been split from the main MQTT binding, and will not be auto-installed. If you use this binding, it will need to be manually re-installed.
ESC[31mWarning:ESC[m JavaScript Automation: The event object in UI-based environments has been aligned with the file-based event object. Properties are now pure JavaScript types and property names have changed. Blockly users need to resave their scripts.
ESC[31mWarning:ESC[m JavaScript Automation: Automatic injection of the openHAB JavaScript library now allows for more fine-grained control. It is recommended to manually import required namespaces from the openhab library in file-based scripts and transformations and disable automatic injection for file-based scripts and transformations.
ESC[31mWarning:ESC[m KNX Binding: Using secure tunnel or secure router with autodiscovered Gateway Things may cause configuration loss on restart. To recover: delete the IP Gateway Thing from the Inbox and restart. The Gateway will be rediscovered automatically. Note: Routers may appear as both tunneling and routing devices
ESC[31mWarning:ESC[m PythonScripting Automation: Python "openhab.Timer" removed. Can be replaced with default Threading or Timer implementation.
ESC[31mWarning:ESC[m PythonScripting Automation: Changed parameter of "openhab.Registry.addItem"
ESC[31mWarning:ESC[m PythonScripting Automation: Replace "NotInitialisedException" with "NotFoundException" in "openhab.Registry.getItem, "openhab.Registry.removeItem", "openhab.Registry.getThing", "openhab.Registry.getChannel"
ESC[31mWarning:ESC[m PythonScripting Automation: "openhab.Registry.getItemMetadata", "openhab.Registry.setItemMetadata" and "openhab.Registry.removeItemMetadata" replaced by "<Item>.getMetadata().get", "<Item>.getMetadata().set" and "<Item>.getMetadata().remove"
ESC[31mWarning:ESC[m PythonScripting Automation: "openhab.Registry.safeItemName" move to "openhab.Item.buildSafeName"
ESC[31mWarning:ESC[m Shelly Binding: Thing type shellyplushtg3 was renamed to shellyplusht. Delete the existing things and re-discover the devices.
ESC[31mWarning:ESC[m SMHI Binding: Due to updates to SMHI's API, the channel ids have changed. Measures have been taken to ensure backwards compatibility, but to avoid future issues all items need to be relinked to the new channels.
Replacing userdata system files with newer versions...
Clearing cache...
Starting JSON database update...
[main] INFO org.openhab.core.tools.UpgradeTool - Already executed 'itemCopyUnitToMetadata' on 2025-06-19T07:09:42.639345337-06:00[America/Denver]. Use '--force' to execute it again.
[main] INFO org.openhab.core.tools.UpgradeTool - Already executed 'linkUpgradeJSProfile' on 2025-06-19T07:09:42.664950608-06:00[America/Denver]. Use '--force' to execute it again.
[main] INFO org.openhab.core.tools.UpgradeTool - Already executed 'linkUpgradeScriptProfile' on 2025-06-19T07:09:42.680081975-06:00[America/Denver]. Use '--force' to execute it again.
[main] INFO org.openhab.core.tools.UpgradeTool - Already executed 'yamlTagsListToMap' on 2025-06-19T07:09:42.799142699-06:00[America/Denver]. Use '--force' to execute it again.
[main] INFO org.openhab.core.tools.UpgradeTool - Already executed 'homeAssistantAddonUpgrader' on 2025-12-15T14:30:01.121179769-07:00[America/Denver]. Use '--force' to execute it again.
[main] INFO org.openhab.core.tools.UpgradeTool - Already executed 'homieAddonUpgrader' on 2025-12-15T14:30:01.514579513-07:00[America/Denver]. Use '--force' to execute it again.
[main] INFO org.openhab.core.tools.UpgradeTool - Already executed 'persistenceCopyDefaultStrategy' on 2025-12-15T14:30:01.606850453-07:00[America/Denver]. Use '--force' to execute it again.
JSON database updated successfully.
SUCCESS: openHAB updated from 5.1.0.M4 to 5.1.0
That’s already been discussed elsewhere. I don’t know if it’s more than idea yet but there is the idea of having some sort of webpage that comes up before OH does to tell you stuff like that.
But in the mean time, you should have it in a log file generated by the image. You don’t have to get it through docker log.
The only two packages though are Java and openHAB. openHAB gets everything else from Maven, not the OS package installer. And OH only depends on Java. So did you have problems installing Java? You came from OH 3 IIRC correctly so that would be Java 11 I think.
That might be something we can deal with, namely identify an OpenJDK implementation for these older Javas that work on newer OS. That can be added to the docs at least. Once Java is installed and working OH is good to go.
It can’t be JSONDB because that will get overwritten on the restore. It has to have something outside of userdata and conf to know the version of OH that’s running and compare that to something inside of userdata or conf that tells it what version the configs came from.
Another problem here is that clearing the cache and updating the JSONDB and all that has to be done while OH is not running. OH can’t do this to itself. Something has to do it before OH comes up. In Docker it’s entrypoint.sh.
I think only usedata/etc. Nothing in $OH_CONF should get touched. Sometimes there might be additions to some of the files under userdata/config, though I don’t know if that’s really ever happened in actuality before.
update.bat just starts update.ps1 (which means that it won’t work from a “regular” Windows command-line aka cmd.exe). update.lst has what seems like both alert messages and some kind of list of files to be moved/deleted etc.(snippet):
[5.1.0]
ALERT;CORE: Persistence default strategies are removed and not applied automatically anymore. Managed persistence configurations are updated automatically. If you have a file based configuration with an existing .persist file, you may have to update your configuration: remove "default" from Strategies and make sure all Items definitions have a strategy defined.
ALERT;AhaWasteCollection Binding: A typo was corrected in the lightweight channel id, you may need to correct your configuration.
ALERT;Allplay Binding: Due to limited usage and increasing maintenance issues, this binding has been removed.
ALERT;Automower Binding: Restructured to modular things with auto-discovery of datapoints. New things and channels will need to be linked, existing items need to be adjusted.
ALERT;evcc Binding: Restructured to modular things with auto-discovery of datapoints. You must reconfigure settings, recreate Things, and adjust Items as previous configurations are incompatible.
ALERT;Folderwatcher Binding: A typo was corrected in the AzureBlob thing parameter containerPath. You may need to reconfigure this parameter.
ALERT;Freebox Binding: The binding has been removed from the distribution. You should consider migrating to the FreeboxOS binding.
ALERT:Guntamatic Binding: Channel ID spelling errors (such as `079-interuption-0` and `080-interuption-1`) have been corrected. You may need to update items linked to these channels.
ALERT;Home Assistant Binding: The binding has been split from the main MQTT binding, and will not be auto-installed. If you use this binding, it will need to be manually re-installed. You may also need to re-configure the binding if discovery settings have been customized.
ALERT;Homie Binding: The binding has been split from the main MQTT binding, and will not be auto-installed. If you use this binding, it will need to be manually re-installed.
ALERT;JavaScript Automation: The event object in UI-based environments has been aligned with the file-based event object. Properties are now pure JavaScript types and property names have changed. Blockly users need to resave their scripts.
ALERT;JavaScript Automation: Automatic injection of the openHAB JavaScript library now allows for more fine-grained control. It is recommended to manually import required namespaces from the openhab library in file-based scripts and transformations and disable automatic injection for file-based scripts and transformations.
ALERT;KNX Binding: Using secure tunnel or secure router with autodiscovered Gateway Things may cause configuration loss on restart. To recover: delete the IP Gateway Thing from the Inbox and restart. The Gateway will be rediscovered automatically. Note: Routers may appear as both tunneling and routing devices; choose the appropriate type from the Inbox. File-based configurations are not affected.
ALERT;PythonScripting Automation: Python "openhab.Timer" removed. Can be replaced with default Threading or Timer implementation.
ALERT;PythonScripting Automation: Changed parameter of "openhab.Registry.addItem"
ALERT;PythonScripting Automation: Replace "NotInitialisedException" with "NotFoundException" in "openhab.Registry.getItem, "openhab.Registry.removeItem", "openhab.Registry.getThing", "openhab.Registry.getChannel"
ALERT;PythonScripting Automation: "openhab.Registry.getItemMetadata", "openhab.Registry.setItemMetadata" and "openhab.Registry.removeItemMetadata" replaced by "<Item>.getMetadata().get", "<Item>.getMetadata().set" and "<Item>.getMetadata().remove"
ALERT;PythonScripting Automation: "openhab.Registry.safeItemName" move to "openhab.Item.buildSafeName"
ALERT;Shelly Binding: Thing type shellyplushtg3 was renamed to shellyplusht. Delete the existing things and re-discover the devices.
ALERT;SMHI Binding: Due to updates to SMHI's API, the channel ids have changed. Measures have been taken to ensure backwards compatibility, but to avoid future issues all items need to be relinked to the new channels.
[[PRE]]
[2.2.0]
DEFAULT;$OPENHAB_USERDATA/etc/org.ops4j.pax.logging.cfg
[3.0.0]
DEFAULT;$OPENHAB_USERDATA/etc/log4j2.xml
DEFAULT;$OPENHAB_USERDATA/etc/org.ops4j.pax.logging.cfg
[3.1.0]
DEFAULT;$OPENHAB_USERDATA/etc/org.apache.karaf.log.cfg
[3.2.0]
DEFAULT;$OPENHAB_USERDATA/etc/log4j2.xml
[4.0.2]
DEFAULT;$OPENHAB_USERDATA/etc/log4j2.xml
[[POST]]
[2.3.0]
DELETE;$OPENHAB_USERDATA/etc/org.openhab.addons.cfg
DELETEDIR;$OPENHAB_USERDATA/kar
Then there is just update (without any extension), which seems to be a bash script, here is the start:
#!/bin/sh
###########################################################################
# NOTE: changes in this script should be reflected in update.ps1 as well
###########################################################################
setup(){
## Keep the script general by allowing the user to provide the version number to download.
if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
echo "Usage: ./runtime/bin/update [VersionNumber] [openHAB Dir]"
echo ""
echo " e.g. ./runtime/bin/update << Updates to the next version"
echo " ./runtime/bin/update 5.1.0 << Updates to a specific version"
echo " ./update 5.1.0 /opt/openHAB << Updates a specific root folder"
echo " ./runtime/bin/update 5.2.0-SNAPSHOT << Updates to latest SNAPSHOT"
echo ""
echo "Use this script to change openHAB to another version. Specifying the version allows"
echo "you to upgrade or downgrade to that version, or to the latest snapshot. Not specifying"
echo "any parameters will attempt to find the next version for you."
echo ""
echo "You can place this script anywhere, but you should run it from inside the openHAB root folder."
echo "Do not try to run the script from inside the runtime folder."
echo ""
exit 0
fi
## Ask to run as root to prevent us from running sudo in this script.
if [ "$(id -u)" -ne 0 ]; then
echo "Please run this script as root! (e.g. use sudo)" >&2
exit 1
fi
## Second parameter can be the openHAB path, if not assume the script is called from root!
if [ -z "$2" ]; then
if [ -n "$OPENHAB_HOME" ]; then
WorkingDir="$OPENHAB_HOME"
DirError="'OPENHAB_HOME' does not point towards openHAB's root directory."
else
WorkingDir="."
DirError="The script must be called from openHAB's root directory."
fi
Whether any, or all, of these files are packaged with package distributed installations I don’t know, but I would suspect so, as e.g. the backup script is also found there.
What I think is unique for the Windows script is that it actually downloads different OH versions. Why this is different for Windows and other platforms I don’t know.
He said that it had happened, but I don’t know if that exact scenario happened. That said, I’ve met similar “impossible situations” many, many times - where one thing excudes something because deprecated/no longer supported while another thing requires just that to allow you to progress. It probably won’t be long until Java 8 starts to disappear here and there either, and I think this absolutely is a relevant situation. You can’t install an OS/system that is old enough to work, both because actually getting working installation files for older systems can be hard (sure, you get some file, but then it goes online to fetch the rest - and that doesn’t exist anymore) and because the new hardware has some feature that is "only supported since Kernel x.y) which at the same time excludes some of the packages you need. I am one of those people that do set up old systems when I need to run something “outdated”, and the hoops one often have to jump through just boggles the mind.
It’s clearly a better strategy to allow another way of doing the required changes than actually installing the old version and upgrade from there. I’m not saying that strategy can’t be used if possible, but it often isn’t “possible” if the “distance” is big enough.
I’m still not sure - does this upgrade script exist, or is it the same as the update script?
I’m not sure if that is true. But, it most probably be done differently if OH is running. The JSONSDB should be the easiest to handle, just make sure that “storage” (I think it’s called) isn’t running, and you can do what you want with the JSON DB. When it comes to the cache, I’m less sure, but I think there are ways to do these things from within Karaf - which means that OH can probably also initiate it programmatically - at least for bundles not started. If one made one “startup bundle” that could run alone, it should theoretically be able to clear all the other stuff while it itself is running. Maybe there are other “caches” involved too, but in most cases, a similar logic applies. The fact that the JVM itself is running one small bundle/module, probably doesn’t prevent most operations.
edit: This is the content of /usr/share/openhab/runtime/bin on my openHABian production installation:
total 2.7M
drwxrwxr-x 2 openhab openhab 4.0K Dec 11 2024 ./
drwxrwxr-x 6 openhab openhab 4.0K Dec 11 2024 ../
-rwxr-xr-x 1 openhab openhab 7.4K Nov 24 2024 backup*
-rwxr-xr-x 1 openhab openhab 4.2K Nov 24 2024 client*
-rwxr-xr-x 1 openhab openhab 6.3K Nov 24 2024 common.psm1*
-rwxr-xr-x 1 openhab openhab 9.3K Nov 24 2024 inc*
-rwxr-xr-x 1 openhab openhab 4.2K Nov 24 2024 instance*
-rwxr-xr-x 1 openhab openhab 14K Nov 24 2024 karaf*
-rwxr-xr-x 1 openhab openhab 874 Nov 24 2024 oh_dir_layout*
-rwxr-xr-x 1 openhab openhab 7.9K Nov 24 2024 restore*
-rwxr-xr-x 1 openhab openhab 5.0K Nov 24 2024 setenv*
-rwxr-xr-x 1 openhab openhab 4.1K Nov 24 2024 shell*
-rwxr-xr-x 1 openhab openhab 2.8K Nov 24 2024 start*
-rwxr-xr-x 1 openhab openhab 2.6K Nov 24 2024 status*
-rwxr-xr-x 1 openhab openhab 2.6K Nov 24 2024 stop*
-rwxr-xr-x 1 openhab openhab 259 Nov 24 2024 update*
-rw-r--r-- 1 openhab openhab 33K Nov 24 2024 update.lst
-rw-r--r-- 1 openhab openhab 2.5M Nov 24 2024 upgradetool.jar
-rw-r--r-- 1 openhab openhab 933 Nov 24 2024 userdata_sysfiles.lst
So, the update file is very much there - I don’t know where the upgrade file is though - if it exists.
The whole update/upgrade thing is confusing anyway. Just look at apt vs yum/dnf for example. The latter use “update” where the former use “upgrade”. The latter use “refresh” where the former use “update”. So, this isn’t only a confusion here in OH-land
Which is all that I meant. Only the Windows version downloads the packge when the script is called. I did not mean that Winows was the only version that had any scripts at all.
update script.
What ever it’s called. There is just the one that has the following in it.
# Clearing the cache, marketplace and tmp folders is necessary for upgrade.
I misspoke as I didn’t have a computer in front of me to check.
There is only one script for Linux that we are talking about here, not two.
There is more to this story. Somebody here must know more about this. I’ve looked in the update bash script, and it very much downloads new versions as well, snippet:
if test "${OHVersion#*-SNAPSHOT}" != "$OHVersion"; then
DownloadLocation="https://ci.openhab.org/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab/target/openhab-$OHVersion.zip"
AddonsDownloadLocation="https://ci.openhab.org/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab-addons/target/openhab-addons-$OHVersion.kar"
elif [ "$OHVersion" = "$CurrentVersion" ]; then
echo "You are already on openHAB $CurrentVersion" >&2
exit 1
elif [ -n "$milestoneVersion" ]; then
DownloadLocation="https://www.openhab.org/download/milestones/org/openhab/distro/openhab/$OHVersion/openhab-$OHVersion.zip"
AddonsDownloadLocation="https://www.openhab.org/download/milestones/org/openhab/distro/openhab-addons/$OHVersion/openhab-addons-$OHVersion.kar"
else
DownloadLocation="https://www.openhab.org/download/releases/org/openhab/distro/openhab/$OHVersion/openhab-$OHVersion.zip"
AddonsDownloadLocation="https://www.openhab.org/download/releases/org/openhab/distro/openhab-addons/$OHVersion/openhab-addons-$OHVersion.kar"
fi
However, when I look inside the update script found on openHABian, it only has this content:
#!/bin/sh
echo "Please use your system's package manager to update!"
echo " e.g. \"sudo apt-get update && sudo apt-get upgrade\""
echo " \"sudo yum update\""
echo ""
echo "See https://www.openhab.org/docs/installation/linux.html for information."
So, clearly, the content of this file is replaced in the “packaged version”. That still leaves the question of where the script that does the cache clearing etc. lives, because in the update script that comes with the “manual install” archive that you can download, both things are done as part of the same operation:
## Clearing the cache and tmp folders is necessary for upgrade.
echo "Clearing cache..."
rm -rf "${OPENHAB_USERDATA:?}/cache"
rm -rf "${OPENHAB_USERDATA:?}/tmp"
rm -rf "${OPENHAB_USERDATA:?}/marketplace"
## Unzip the downloaded folder into openHAB's directory WITHOUT replacing any existing files.
echo "Updating openHAB..."
unzip -nq "$OutputFile" -d "$WorkingDir/" || {
echo "Failed to unzip archive, restoring system files..." >&2
## An error has occured so try to restore openHAB to it's previous state.
cp -a "$TempDir/runtime" "$WorkingDir/runtime"
cp -a "$TempDir/userdata/etc/"* "${OPENHAB_USERDATA:?}/etc/"
exit 1
}
It also goes through update.lst, shows warnings etc:
transferFile="update.lst"
CurrentVersionNumber=$(getVersionNumber "$CurrentVersion")
case $CurrentVersion in
*"-"* | *"."*"."*"."*) CurrentVersionNumber=$((CurrentVersionNumber-1));;
esac
## Go through a list of transitional commands that are stored in the update archive.
echo "New update list required, extracting from zip..."
unzip -qp "$OutputFile" "runtime/bin/$transferFile" > "$TempDir/$transferFile" || {
echo "Additional update commands not found in archive, exiting..."
exit 1
}
## Notify the user of important changes first
echo "The script will attempt to update openHAB to version $OHVersion"
printf 'Please read the following \033[32mnotes\033[m and \033[31mwarnings\033[m:\n'
scanVersioningList "MSG" "Important notes for version"
if [ -z "$OPENHAB_NONINTERACT" ]; then
printf '\nIs this okay? [y/N]: '
read -r answer
case $answer in
[Yy]*)
;;
*)
echo "Cancelling update..."
rm -rf "${TempDir:?}"
exit 0
;;
esac
fi
So, it seems to me like this is all a bit “mixed together” and that there might not be an easily identifiable “upgrade script” that can be run to just apply the version-wise steps that are listed in update.lst.
That said, for anybody that knows about update.lst, it’s quite easy to see what steps are performed between what versions:
The changes for 3.0.0 were pretty substantial, but it seems that nothing has been done to files since 4.2.0.
