Ever so often I see questions like
I'm coming from OpenWrt release 'A' and want to upgrade to release 'B'.
Can I check the "Keep settings box or not?
Would it make sense to show the "keep/don't keep" in a table like this one?
Your input to this table is appreciated.
[Table removed to avoid false interpretations]
Two thoughts:
As the config "API" is hopefully constant within a given release, as well as that I don't think we should be suggesting anyone upgrade to anything but the latest, maintained releases, this probably could be simplified to just from the major versions, 12, 14, 15, 17, and 18, then to 17 and 18. Labeling the older releases with their names seems valuable as well.
There are some subtle changes I've seen, such as key and sae_key in /etc/config/wireless. Assuming those changes could be catalogued, noting those exceptions would be valuable.
Commits around that specific change include:
d88934aa5aa9b61ec66a6f7ae0fb61d1ef889884
eba3b028e46dbfe54f1208e9edf47bb0c6f73ac8
I also consider this upgrade matrix to be slightly overkill. As mentioned by jeff, upgrading within a given stable release (e.g. 17.01.n --> 17.01.m) should always be safe with keeping settings. So far 17.01.x --> 18.06 also seems to be fine in general. Upgrading by keeping configuration files older than that (15.05.x or older) can not be considered safe in a large number of cases (because of changed switch/ vlan configurations, containing dnsmasq to its dedicated system user, etc. while there are mitigations in place, there is a high risk for soft-bricking the device in practice).
Providing any assumptions for even older releases (12.09, 14.07, etc.) -or for upgrades between versions of already long-unsupported releases- feels rather challenging, more than 4 years after every security conscious person has forgotten about them and the details required for upgrading them. Obviously their settings are not safe to be kept for upgrading to current (17.01.x/ 18.06.x).
This matrix might also transport the semblance of being able to avoid these compatibility issues by upgrading in stages, e.g. coming from 12.09 that you'd just have to upgrade to 14.07 first, before installing 15.05.x and 17.01.x by keeping the configuration files and never touching them - this is not going to help. sysupgrades in general don't 'migrate' config files during the upgrade, while the file list might be pruned slightly, the files are usually kept verbatim (yes, there are some upgrade scripts in place, attempting a config migration for targetted issues, like e.g. making sure to create a dnsmasq system user, but we've already established that these aren't always working). If your configuration has been created by firmware versions older than 17.01.x, it's not generally safe to retain them (and trying to restore an old configuration tarball would be even more fatal, as the existing/ incomplete migration scripts won't run in that case at all), even if it might work in some cases (depending on the chosen configuration and the devices in question).
Currently there are no (major) issues to be expected with upgrading from 17.01.0 or later, but there are always exceptions (e.g. lantiq changing the name of the dsl device) - and there will continue to be such issues (e.g. migrating targets to the dsa switch driver architecture).
As the issue has come up a few times recently, I'd like to add that restoring a configuration tarball made on an older router on newer/ different hardware is not possible, as very crucial and basic configuration settings are hardware dependent (switch and vlan configuration, LED/ GPIO settings, WLAN config (device paths), etc.).
I largely agree with slh.
My main points:
In nutshell, when upgrading to 18.06.x:
My personal experience here is 17.01 -> 18.06 has been pretty painless, and I was able to keep my settings on ar71xx / mt7621 / x86_64.
That being said, I vividly remember things like paths for wireless interfaces changing between 15.05 and 17.01. So I concur anything < 17.01 should not be upgraded while keeping settings (unless someone's idea of fun is finding the proverbial needle in the haystack breaking things, that is). The only way to use older configuration data would be as a reference so you don't have to start from scratch again, like @slh and @hnyman already stated.
@tmomas It might be a good idea to introduce master / future 19.x into the equation as well, since at least for ar71xx -> ath79 there will be breaking changes, and I understood DSA would be ready for prime time then as well. All stuff that would break existing configurations, to my knowledge.
Master surely is a moving target, and I don't know if project policy includes mandatory migration paths, which would render upgrades painless but might make devices choke on downgrades (since people are unaware of settings being migrated, then downgrade and get bitten). Then again, dowgrades might be beyond the scope of your decision table.
I guess it gives me a warm and fuzzy feeling to see a "keep" for those transitions, plus it will allow to catch potential problematic revisions; think:
18.06.1 -> 18.06.2: don't keep
18.06.1 -> 18.06.3: keep
imho maintenance releases could be added on an as-needed basis, there's no need to clutter the table for 17.01.x, nor 18.06.0 --> 18.06.1 yet - if, hypothetically, 18.06.2 would require special attention, it could be added (as an exception).
Thanks for your input so far!
Simplified table:
What about upgrades to / from master, keep or don't keep settings? I would guess "don't".
Keeping settings from newer versions while downgrading is never safe (although it might work), even less the larger the steps get (this shouldn't be considered an option, unless we're only talking about a few weeks between master snapshots).
17.01.x --> master should still be safe for the most part, exceptions apply.
18.06.x --> master is also still safe, but this might change in the future (DSA) - this would then also apply to upgrading from older versions (as in 17.01.x)
This could help sanitizing kept settings for upgrades in the future (at least for unmodified files).
If you're messing around with master you (hopefully) know what you're doing and aren't going to be consulting this chart. Given what I think the target audience would be, I'd not mention "development builds" at all.
In my experience, what configuration worked on master in the morning may fail in the evening's build.
That might happen, but very, very rarely - and if it happens, it will usually affect the next stable release alike.
More a comment that master isn't "guaranteed stable" and might be "broken" in various ways at any specific commit. Yes, usually things are "fixed" in later commits (as was, I believe the options mentioned above), but that anyone working with master should not expect that configuration will be completely compatible between any two commits. And that they already should know that before embarking on flashing a snapshot or building their own images off a live development branch.
Your initial table's logic suggests that keeping settings is always okay as long as you upgrade one version at a time. This is simply not true and a recipe for disaster. I would even go so far to suggest you remove it from your initial post, on the off-chance that someone would find it in a cursory search and accept it as a guideline.
Your second table is smaller in scope, but still makes a dangerously generic statement. For example, I could easily name configuration changes that happened between 17.04 and 18.06 you mark with a green "keep". Also consider that "master" is a moving target, and while is very close to the released version now, it will depart from the release version and from older "master" versions as time progresses. Are you really comfortable to give a green "keep" between a "master" of today and a "master" of six months from now?
I'm afraid there is no generic answer that is valid across versions, targets and devices. Even further, consider that a number of users who want to "keep configuration" want to do so not only for their base system, but also for the additional packages they installed. I'm not entirely sure about the value of your table if you changed every green "keep" to a plaid "maybe, maybe not" and how you would mark "your device will probably not break, but something may not work anymore, good luck chasing down the option that changed."
While I understand the frustration of not being able to give a simple answer, IMNSHO the only responsible guideline is: While it is possible, and increasingly possible the closer the versions are to each other, do not assume you can retain your unaltered configuration between versions. The prudent action would be to backup the configuration for the values, upgrade without retaining the configuration, and successively fill in in the saved configuration values. Yes, this is annoying, and yes, you could just wing it and retain the configuration, but that's entirely at your own risk.
We could also offer a table with clear caveats. As in: orange instead of green, and refer to notes lower on the page for specific upgrade paths. I assume you are referring to stuff like OpenVPN breaking etc., but that is advanced, and we cannot possibly cover every upgrade path. A sane starting point is a default configuration, but it wouldn't hurt to point out extras like OpenVPN or the likes (although OpenVPN and stuff seems to break on every major upgrade), and refer people to the respective documentation for that software.
Yes, but not limited to. A few devices actually had changes in basic configuration.
Which is exactly what I am trying to convey. There's a conflict of objectives here. An advanced user already knows about the intricacies of upgrading. You are trying to make a simple statement for inexperienced users about an advanced topic.
Look, I'm not trying to say that this is not an effort worth taking, it is certainly good and necessary to talk about the upgrade process. I just don't think that starting out by displaying the best-case scenario in an "easy table" and then narrowing it down is the ideal way to do it.
But I could also be wrong. I have been wrong before (once in 1993, I think).
Reviving this topic with an update: https://openwrt.org/inbox/keep_settings_at_sysupgrade
Is this better than before?
First bullet point should be "ALWAYS make a manual settings backup" just in case.
Possible link or mention of extroot interplay / further reading may or may not be relevant.
Page updated accordingly.
I don't think so. Now the table pretty much only says one thing:
"You can upgrade within the same major version and keep settings." (edited, sorry)
and the page spends a whole lot of text explaining all the cases that might not be correct.
Furthermore, the orange entries are directly contradicting themselves. On the one hand you say "it's generally OK (to keep config when upgrading to the next major version)", on the other hand you say "don't restore a config backup from an earlier major version". Upgrading while keeping settings and restoring a config backup are the same thing (quite literally, sysupgrade backups the config and restores it after flashing the new version.)
I know you are coming from a good place and making an effort, but I stand by my point I made a year ago: No table. Describe in a few easily comprehensible sentences what's going on when upgrading and what to take care about.
OK, so it was a stupid idea in the first place. Page deleted.