OPKG upgrade / package upgrade warning

Ok.... here's a stab at what we can put in this warning (maybe it can be in the main warning page with a sentence or two excerpted for the canned response.... feedback welcome.

The use of opkg upgrade is very highly discouraged, and should be avoided in almost all circumstances. This is also distinctly different from the sysupgrade path for upgrading both major versions and maintenance upgrades of OpenWrt -- the two are not equivalent.

Just because there is an updated version of a given package does not mean it should be installed or that it will function properly.

Unlike the 'big distros' of Linux, OpenWrt is optimized to run on systems with limited resources. This includes the opkg package manager, which does not have built-in ABI (Application Binary Interface) compatibility and kernel version dependencies verification. Although sometimes there may be no issues, there is no guarantee and the ugprade can result in various types of incompatibilities that can range from minor to severe, and it may be very difficult to troubleshoot. In addition, the opkg upgrade process will consume flash storage space and as it does not overwrite the original (stored in ROM), but stores it in the r/w overlay.

In the vast majority of cases, any security patches of significant importance/risk will be rapidly released in an official stable maintenance release to be upgraded using the sysupgrade system. This is the recommended method for keeping up-to-date.

Those looking to be on the bleeding edge can consider using the snapshot releases, but should be mindful of the differences between stable and snapshot. The remaining users who still want to use opkg upgrade should only do so with individual packages (do not blindly update) and they should be aware that problems may occur that could necessitate a complete reset-to-defaults to resolve.

If you're already having issues, or wish to 'undo' the upgraded packages: create a backup (optional; can be restored after the reset is complete) and then perform a reset to defaults (firstboot).

If the team is good with my proposal for the opkg upgrade warning, I can edit the wiki accordingly and then make a very quick revision to the canned reply. Any thoughts?

I agree as long as the canned reply is not that long and discourages the user to read it all. Keep a TL:DR in the canned reply and the rest as a hyperlink to the wiki.


Agreed. Canned reply should be short, details see wiki.

1 Like

Agreed! I updated the Wiki - please let me know if anything needs to be changed (or feel free to change it yourself).

I have updated the canned reply slightly, too...

opkg upgrade can result in major problems. It is generally highly discouraged, unless you know what you are doing or if there is specific instruction to do so.


I'm going to update the wiki warning for upgrading packages information about LuCI's upgrade feature being the same thing as the CLI method (both discouraged, of course).

Just a quick question for confirmation: is the "upgrade" feature in LuCI new in 19.07? I don't recall seeing it in 18 or earlier.

Just updated the package upgrade wiki warning.

As always, comments and/or updates to the wiki to correct or clarify anything in my update are welcome!

EDIT: I also updated the canned response (below) and re-titled it as "Package upgrade warning" (previously opkg upgrade warning):

Upgrading packages (via the CLI opkg upgrade command or the LuCI Upgrade... button can result in major problems. It is generally highly discouraged, unless you know what you are doing or if there is specific instruction to do so.

Hmmm... this infobox is way too long. tl;dr :wink:

The character of an infobox should be: short, and for further information see <link to page with more detailed information>

It should be short enough to be placed on other wiki pages like https://openwrt.org/packages/start

See the first revision of this infobox page where a link to a details page was included:

The link to a details page included in this page revision should of course point to a better suited place, e.g.https://openwrt.org/docs/guide-user/additional-software/upgrading_packages

@psherman Do you think you can shorten the infobox and create a new page for more detailed explanations (including some examples for package upgrades gone wrong)?

Further thoughts (possible content for the details page):

  • we should stress that this warning is directed to users who
    • upgrade packages via script (==blindly)
    • who manually upgrade packages via LuCI just because they are shown as upgradable, and without prior checking if it is safe to upgrade (==blindly)
  • we should anticipate and try to answer subsequent questions from the user:
    • How can I know if it is safe to upgrade package xyz?
    • Which packages are known to be problematic?
    • What can I do if I want to have the latest update for package xyz?
  • we should point out alternatives to upgrading packages
    • wait for the next release
    • build your own image (link to instructions how to do so)
  • What to do if a package upgrade has gone wrong? How to revert the upgrade? How to get the device operational again?
1 Like

Moved to new topic since it deserves more thorough public discussion.

Thanks for splitting this out @tmomas.

Yeah, maybe I overdid it with the detail in the warning page :crazy_face:. I agree that a few sub-pages and links could make it more readable. I don't think I'll get to it immediately, but I'll aim to make some revisions as you suggested.

As an aside, I checked 18.06.x and the LuCI upgrade feature was not there -- so this is indeed new in 19. Which begs the question: why was it added, and is this addition believed to be beneficial in general? A while back, I had suggested some technical measures to make it just a bit harder to use the CLI upgrade method (maybe a warning similar to sudo first-time use on many linux distros or maybe a check [y/n] that states the warning and then the user says "yes, I'm really sure I want to do this." This new LuCI feature, while handy, seems to work in the opposite direction, making it easier for novices to fall into the upgrade trap.

Maybe @jow knows the reasons behind this?

It was added because being able to upgrade packages is useful. Especially on release branches, package updates are almost exclusively bug fixes, security fixes or feature backports.

1 Like

Obviously that can be true with specific packages and/or for those who know what they are doing. But as we have seen, the feature is often used by users without appropriate knowledge (even at the command line), and that can cause serious problems (as we have seen in many threads). LuCI makes it that much easier to use the feature -- normally I wouldn't be concerned about making something easier :laughing: -- which is not necessarily a good thing in this case.

Since it seems that the general consensus from the actual developers is to avoid adding technical methods to dissuade the use of upgrade, I'd like to suggest a very minor change (if not too complicated) targeted for OpenWrt 20.x --- hide the LuCI update/upgrade tab unless enabled in the /etc/config/luci file (maybe add an option like below):

config internal 'upgrade_visibility'
	option enable '0'
1 Like

I believe that these reports are biased to some extend, after all nobody will write about successful package upgrades.

I am an actual developer and I disagree with that opinion. I invested a lot of work into things like ABI tracking, updated binary package repositories, packaging quirks, opkg fixes etc.

I'd rather work on making upgrades reliable in cases where they fail.

@jow -- I want to apologize if my last message came across as anything other than constructive. It was not intended to be combative in any way, just in case it seemed less than friendly.

You have a very good point! This type of bias is very common -- especially in product reviews and such, so it is likely present here, too.

I actually forgot to put in a disclaimer in my last post ("I am not a developer, and I don't pretend to be one"). I have a ton of respect for all that you and the rest of the dev team do and I know that the opkg upgrade system presents a complex and challenging development effort.

I totally agree with that philosophy. My only disagreement here is that until it is robust and reliable for the average user, those that use the upgrade feature without understanding the potential risks may end up frantically asking for help on the forum. In the forums, we frequently see that these are the same users who do not create a backup of their configurations for easy restoration after a reset or flash operation. So hiding the LuCI upgrade button (and allowing it to be unhidden via a switch in the luci config file) could be a good way to prevent these unfortunate situations.

I feel that a substantial part of the problems come from people blindly upgrading low-level core packages like ubus, ubox, busybox, opkg etc. in bulk just because they are listed as upgradeable. Upgrading them (or maybe just upgrading them in wrong order) may cause lockups, and even break further opkg actions.

The difficulty comes from the fact that although upgrading normal packages is relatively ok, touching some of the core packages may cause serious difficulties. And the casual user does not have any idea which are serious core packages, and which are light-impact user add-ons.

One approach might be to mark more core packages essential(?) and prevent opkg upgrades of them.

Other part might be to add some warning to the LuCI page, so that user would be encouraged to upgrade just such packages for which he understands the package's role.

I am not actually sure if "hold" or "essential" is the better description.
At the first glance only opkg and busybox are marked "essential" in the main repo at the moment, and libs/toolchain and kernel are marked "hold" causing librt, libgcc, libpthread etc. musl components getting marked hold.


@jow - I would also love to get your feedback about the package upgrade warning page that I've been editing. As part of the restructuring (to make it a nice TL;DR + detail pages) that @tmomas suggested, maybe we can improve the descriptions about what is generally safe and what is not, and any other color that might be useful (especially when considering that you have a much deeper understanding of the opkg underpinnings and package compatibility considerations).

If you'd like to work together on rewriting/revamping that section, I'm totally up for the help/guidance.

That may very well be the case, but it's fair to agree that it breaks things for some people. We might not know the percentage, but it's probably more than individual cases.

Why it works for some people and causes problems for others could be a matter of technical knowledge or just pure luck. But I think @psherman's suggestion of hiding it in LuCI by default can help people to avoid unknowingly break things. If after that people enable it and then upgrade packages without reading, or if they do it from the command line without reading what they are copying and pasting then that's their fault.

Similar approach is done for example with Developer Mode in Android


And it happened again for another user here.

Edit: fixed link.

1 Like

Can you rewrite the following command
Avoid the above packages?

opkg list-upgradable | sed 's/ - .*//' | sed 's/^/opkg -V upgrade /' | sh