about:upgrades

Contents

1. Upgrades
2. Methods
   1. Migration
   2. Upgrade-In-Place
   3. reprovision

Upgrades

A common question is how to upgrade from one pkgsrc release to another, specifically when using a branch-based package set in a SmartOS zone instance.

It should be noted that upgrading from say 2023Q4 to 2024Q4 should be treated like any other major OS upgrade. There will be many thousands of packages that have been upgraded, some of which may introduce incompatible changes. Back up your data, and be prepared to roll back at any point.

This document is mostly specific to SmartOS instances. Users that are using a trunk package set do not (usually) need any special consideration. Simply continue to "pkgin upgrade" every few days to receive the latest packages.

Methods

There are a few different approaches to consider. We will deal with them in order of recommendation.

Migration

The most reliable method is to provision a new instance that is running the new image, and migrate your applications and data across until the previous instance can be deleted. This method ensures that:

• The new instance is a full, clean, properly-prepared install. Any potential risks due to upgrade issues, remnants from a previous install breaking things, or missing upgrade steps are eliminated.

• The upgrade can proceed at a slower pace while services are migrated across, allowing for a more considered and reliable approach that is less likely to miss important steps compared to directly upgrading a live service.

• Configuration management scripts and documentation can be verified to ensure they are still accurate and able to provision from scratch all the way through to production.

• There is always a backup on the previous instance available should any issues be found post-upgrade, both as a copy of the live data but also as a way to fully roll-back if necessary.

The downsides are that it is more work, and in cases where the instances are running publicly-available network services, it can be tricky to configure everything to switch across to a new instance with IP address changes, etc.

Upgrade-In-Place

This approach is more akin to a traditional OS upgrade. All of the existing packages are upgraded to the newest versions available in the new repository.

Benefits:

• Easy to use and perform.

• Mostly works really well.

Downsides:

• Some packages may have incompatible changes, requiring data migration, configuration file changes, etc.

• Occasional bugs in the upgrade process.

• Any issues during upgrade have the potential to bring down live services until the problem is fixed.

• There may be some files that are not updated and will still refer to the previous install. Notably /etc/pkgsrc_version will not be upgraded automatically, and will need to be modified manually.

This method is certainly a lot more reliable now than it used to be, but there is always the potential for some unforeseen upgrade issue with a package, especially with complex dependencies, that might leave you in a state that needs manual intervention.

Steps:

• Head to https://pkgsrc.smartos.org/packages/SmartOS/bootstrap-upgrade/ and download the bootstrap tarball that you wish to upgrade to.

• Unpack it to the root, for example:

$ tar -zxpvf bootstrap-2024Q4-x86_64-upgrade.tar.gz -C /
./opt/local/etc/mk.conf
./opt/local/etc/pkg_install.conf
./opt/local/etc/pkgin/repositories.conf
./opt/local/etc/gnupg/pkgsrc.gpg

• First upgrade the package tools, and then upgrade all packages:

$ pkg_add -U pkgin pkg_install
$ pkgin upgrade

• Restart any services (svcs -a | grep pkgsrc can help).

If there are any issues with upgrades then please report them at https://github.com/TritonDataCenter/pkgsrc/issues as while there are almost unlimited ways an upgrade can go wrong due to reliance on third-party software behaving itself, we still want to ensure they are as smooth as possible.

Reprovision

This method is more destructive than migration, and is not suitable for cases where there is a live service that needs to be continuously running, but it does offer some of the same benefits of ensuring that the instance is a fresh install of the newer release.

Note that vmadm reprovision is marked as experimental, and is not documented in the vmadm(8) manual page, but has been used by many users to successfully upgrade.

Reprovision essentially replaces the entire contents of the instance with a fresh copy of the new image. All of your data, except for delegated datasets, will be lost!

In light of that, why is this method useful?

• It retains the existing instance IP address and other settings that may be hard-coded in enough places that migration is not a reasonable option.

• With a delegated dataset to store all of the instance data and well-written configuration management, it's possible to reprovision an instance and have it back up and running on a clean install of the new image in very little time.

• If an instance has no custom data and is simply used as a general purpose shell account it's a very quick way to get an instance to upgrade.