So what happened?
We’ve introduced a requested feature in SmartOS: the ability to select a platform image from loader(4), aka OS-8231.
To enable this feature, you must (using example bootable pool bootpool):
- Update BOTH the boot bits and the Platform Image to this release. Normally piadm(1M) updates both, so please use either latest or another ISO-using installation.
- Once booted to this PI, utter piadm activate 20210812T031946Z OR install another ISO-using installation (even if you never use it) to have the new piadm(1M) generate the /bootpool/boot/os/ directory the new modifications to loader require.
This represents a minor flag day because an older piadm(1M) will not update an existing /bootpool/boot/os/ directory. The PI-selection menus live in /bootpool/boot/os/, and will remain in an inconsistent state with older PIs using piadm(1M). It is safe to remove /bootpool/boot/os/ if you wish, as the activated (default) PI always boots correctly modulo actual /bootpool/boot/ corruption regardless.
So Tell Me about the Internals and the os/ Directory!
There were two SmartOS repositories that had changes. The first changeset was in illumos-joyent’s loader(5) Forth files. Alongside some additional support routines, the crux of the change is this addition to the main Joyent loader menu:
\
\ If available, load the "Platform Image Selection" option.
\
try-include /os/pi.rc
If the piadm(1M)-generated file /bootpool/os/pi.rc does not exist, the Joyent loader menu appears as it did prior to this fix.
The os/ Directory and illumos Needing platform/
The os/ directory in a bootable pool’s bootpool/boot filesystem contains directories of Platform Image stamps and the aforementioned pi.rc file.
[root@smartos-efi ~]# piadm list
PI STAMP BOOTABLE FILESYSTEM BOOT IMAGE NOW NEXT
20210715T010227Z bootpool/boot available no no
20210805T161859Z bootpool/boot available no no
20210812T031946Z bootpool/boot next yes yes
[root@smartos-efi ~]# ls /bootpool/boot/os
20210715T010227Z 20210805T161859Z pi.rc
[root@smartos-efi ~]#
Each PI stamp directory contains a single platform symbolic link up to the platform-STAMP directory that contains the PI.
[root@smartos-efi ~]# ls -lt /bootpool/boot/os/20210805T161859Z
total 1
lrwxrwxrwx 1 root root 31 Aug 12 14:41 platform -> ../../platform-20210805T161859Z
[root@smartos-efi ~]#
The Triton Head Node loader menu has a pointer to the “prior Platform Image” has the explicit path of …/os/STAMP/platform contain the platform image. It was a design mistake of the original standalone SmartOS to not lay out platform image in this manner, but given that piadm(1M) must generate the pi.rc file anyway, it is not much more difficult to add symbolic-link construction as well.
The pi.rc File
The pi.rc file includes an additional menu item for the main Joyent loader screen:

It also contains up to three pages of platform images to choose from. Here’s an example of page 1 of 3:

The default PI is on every page, and up to five (5) additional PIs can appear per page. This means 16 PIs (default + 3 * 5) can be offered on a loader screen. Every time a platform image is activated, deleted, or added, the piadm(1M) command regenerates the entire os/ directory, including pi.rc.
So How and Why Do I Use This?
- Temporarily revert to and older Platform Image may be useful to check for regressions or to isolate behavior to a specific release.
- Developers can use *just* platform-image installations (platform-yyyymmddThhmmssZ.tgz to test their new builds without making the bootable pool unusable.
The piadm list output indicates being booted into a non-default PI by its NOW column:
PI STAMP BOOTABLE FILESYSTEM BOOT IMAGE NOW NEXT
20210114T041228Z zones/boot available no no
20210114T163038Z zones/boot available no no
20210211T055122Z zones/boot none no no
20210211T163919Z zones/boot none no no
20210224T232633Z zones/boot available no no
20210225T124034Z zones/boot none no no
20210226T213821Z zones/boot none no no
20210311T001742Z zones/boot available no no
20210325T002528Z zones/boot available no no
20210422T002312Z zones/boot available no no
20210520T001536Z zones/boot available no no
20210617T001230Z zones/boot available no no
20210701T204427Z zones/boot available no no
20210715T010227Z zones/boot available no no
20210729T002724Z zones/boot available no no
20210804T003855Z zones/boot available no no
20210805T161859Z zones/boot available yes no
20210812T031946Z zones/boot next no yes
In the above example, the SmartOS machine is booted into 20210805T161859Z, but its default is 20210812T031946Z. It would also look this way if piadm activate 20210812T031946Z was just invoked, as the semantics are the same.