== Installing and pinning specific versions of OmniOS packages

Suppose, not entirely hypothetically, that you want to install some
additional OmniOS systems with their kernels pinned to a specific
version, one that you know works because it's what you're already
running on your current OmniOS machine (in fact, perhaps you are
having problems with a more recent kernel on your test machine).
In order to do this, you're going to need to do three things: [[you
need to find out what versions of what packages to pin
OmniOSPkgVersionFinding]], then you need to actually install those
specific versions of the packages, and finally you need to keep
them from changing.

Once you have the full FMRIs of the packages you want to have a
specific version of when you install a new system, there are two
cases: install time upgrades and downgrades. The simplest approach
is upgrades; you start from an old OmniOS installer image for your
OmniOS version, then upgrade the packages you need to only their
specific version instead of all the way to the latest one. This is
done by giving '_pkg update_' the full package FMRIs on the command
line; if you have a file called _pkg-versions_, this is:

.pn prewrap on
>  pkg update $(cat pkg-versions)

But wait, as they say, there is a complication (at least for the
kernel). Kernel upgrades require a new boot environment (and are
done in that new BE) and if you're installing from an older image,
you have other packages to upgrade too and some of them may also
require a new boot environment. So what you really want to do is
install both your specific versions and 'the latest updates to other
packages' at the same time. This is done by also giving '_pkg
update_' an explicit _"*"_ argument:

>  pkg update $(cat pkg-versions) "*"

This lets you do the whole process in a single new BE and a single
reboot.

If you're installing from the very latest OmniOS installer image
for your OmniOS version, you actually need to downgrade your packages.
According to the documentation this is also done with '_pkg update
$(cat pkg-versions)_', but I haven't tested it so I don't know if it
works right. My moral is ~~save your old OmniOS installer images~~,
partly because I trust 'upgrade only to a specific version' more
than 'start with a more recent version and downgrade'

(It's possible that old installer images are still available
somewhere, but I don't know where to find them. Old package versions
are kept around in at least the r151014 repo and this will hopefully
continue to be the case.)

Once you've actually installed your versions of the specific packages,
you need to freeze them against further upgrades. This is done with the
straightforward '_pkg freeze <FMRI> [...]_':

>  pkg freeze -c "known to work kernel" $(cat pkg-versions)

However, once again boot environments get in the way. Installing
our kernel packages created a new boot environment, and you have
to freeze packages in the new BE, not the current one. So the easy
way to go is to reboot into the new BE before you run the '_pkg
freeze_'.

(It's possible that you could manually mount the new BE with '_beadm
mount_' and then point '_pkg freeze_' at it with _pkg_'s _-R_
argument, per [[here OmniOSPkgVersionFinding]]. However I haven't
tested it and I honestly think it's probably simpler to reboot into
the new BE first under most circumstances.)

PS: It's unfortunate that '_pkg freeze_' won't freeze specific
versions that are later than what you have installed. Otherwise the
easy approach would be to freeze first, run a general '_pkg upgrade_'
(which should upgrade your packages to their frozen versions and
everything else to the latest versions), and then reboot into your
new BE. But that would probably make freezing more complex in the
_pkg_ code, so I can sort of see why it isn't allowed.