opnsense-update offline update help

[fossbrandon]

Hi there, I'm currently trying to perform an offline update and I have a few questions regarding the best way to use the opnsense-update command. I apologize in advance if the answers to my questions are obvious. I did read the man pages for this tool but started to confuse myself on which options I should use regarding different situations.

1. What options are required vs implied vs recommended with the opnsense-update utility to perform a major update using a local directory?
   • I've tried doing opnsense-update -l "local/update/set" -ur 22.1 -BP and I get an exit code of 1.
     • Are options B and P implied when using -ur or are they explicitly required?
     • Are options b, k, and p only required for minor updates?
2. Follow up question to number 1: Which options would be required vs implied vs recommended for only a minor update?
3. I want the local update to verify signatures of the local file sets if possible without having to specify the -i option. Is this possible assuming that I include the .sig file for every corresponding update file in my local data set directory?
4. When I update my OPNsense version, can I assume that all plugins are also updated? If so, do they retain their current settings or do they revert to a default setup?

Let me know if you want any additional information from me. Otherwise, thanks in advance for any help you can give me regarding my questions!

[fossbrandon]

I looked into this some more and I believe I answered some of the questions.

Question 3: I'm going to have to specify the -i option since I'm archiving my own packages tar file and I'm unable to generate the .sig file for it.

Question 4: It looks like the packages tar file updates all the plugins and I believe it retains the previous settings.

I'm still looking for advice on questions 1 and 2. After rereading the documentation, it seems like I should be using the following process for major upgrades:

1. opnsense-update -bkpiu -l "/local/update/sets" -r 22.1
2. reboot
3. opnsense-update -B
4. reboot
5. opnsense-update -P
6. reboot

However, if I just do the command opnsense-update -bkpiu -l "/local/update/sets" -r 22.1 followed by one reboot command, it seems like it performs its own series of follow up reboots without having to run opnsense-update -B or opnsense-update -P. Also, when I try the process above, I run into errors with steps 3 and 5 because it can't find the /var/cache/opnsense-update/.base.pending or the /var/cache/opnsense-update/.pkgs.pending directory depending on which command I run. So, am I safe to just perform steps 1 and 2, or am I possibly doing something wrong since steps 3 and 5 don't work?

For minor updates, it seems like I should use the following process:

1. opnsense-update -bkpi -l "/local/update/sets" -r 22.1
2. reboot

However, I get errors when I don't specify the -u option since it tries to update the OPNsense repository catalogue using the mirror rather than the packages tar file in the given local directory. So, it almost seems likes I should always be using the u option regardless of whether or not it is a major upgrade. Could you elaborate some if that is incorrect?

[fichtner]

Hi Brandon,

For 1. you use opnsense-update -l "local/update/set" -ur 22.1. -B and -P are post-boot operations performed by the core from here:

https://github.com/opnsense/core/blob/8e444c3b32bc910b04d16967ebda0429b25a8078/src/etc/rc.syshook.d/early/05-upgrade#L5

and these actions don't need to be done manually.. it just requires a reboot. BTW, -u implies "-bkp", but uses a special handling for "-b" and "-k" due to ABI-safe updates (install and boot kernel first, then install base and reboot, then install packages and reboot).

For 2. minor updates are "-bkp" but -l doesn't work for local package sets... package sets are a concept for major upgrades. minor upgrades use a "online" package database you could mirror locally, but it requires editing /usr/local/etc/pkg/repos/OPNsense.conf similar to what "-P" is doing internally.

3. Yes, the sig file is to be put side by side with the actual set file. For kernel and base you can use vanilla files from the server but packaging your on packages set misses a signature (we only publish the initial set for upgrades like 22.1 along with a signature).

4. pkg-upgrade internally always upgrades everything it can (and that is actually included in the packages to be updated) and no settings are lost.

Cheers, Franco

[fossbrandon]

Thanks for the super helpful response! That clears up a lot of my questions.

The only thing I'm still wondering about is whether or not I should/could use the major upgrade option for minor upgrades (ex: Upgrading from 22.1 to 22.1.4)? I tested it out using the major upgrade command and it seems to upgrade to 22.1.4 using my local files rather than a mirror. Would this cause any issues that you know of?

[fichtner]

If you package your own packages set from a mirror you can do major upgrades for minor versions for sure. Keep in mind that this tries to pull in the "same" kernel and base version so you either have to rename the latest one available to match the packages set version even though it isn't an update because it just reinstalls the same version to fulfil its intended workflow.

The reasons why we don't provide a packages set for minor iterations are plenty:

1. We want to save mirror space and thus favour the minor updates over major upgrades. Minor updates also save bandwidth, update complexity (the majority of provided packages do not change during a minor iteration anyway), time wasted on spurious reinstalls and critical reboot amount.
2. Major upgrade procedure is done as an ABI-safe offline update to prevent the system from breaking mid-update. But that means they can't be supervised as easily as minor updates.
3. Major upgrades require a base and kernel set due to their ABI-safe design.
4. Major upgrades do not handle third party packages even if configured. This is also to prevent the core from breaking and failing to bring up a system afterwards due to package dependency errors on unsupervised updates. The FreeBSD package tools has a couple of longterm bugs that are not being worked on and they can kill a system even when using their own safeguards (such as vital package annotation).
5. Last but not least major upgrades require more testing which we don't want to spend our time with for each minor release testing the packages sets for OpenSSL and LibreSSL on top of testing minor updates incrementally and cumulatively.

That's all from the top of my head. If you have more specific question please don't hesitate to ask.

Cheers, Franco

[fossbrandon]

Thanks for answering all my questions. I am packaging everything myself and then transferring those files to the device running OPNsense so always performing a major upgrade should work for me.

Thanks again for the detailed responses! I'll go ahead and close this.