Skip to end of metadata
Go to start of metadata

You may want to build illumos on one Operating Environment (a build host, local zone or a VM) and install the resulting packages on another. The page on Redistributing built packages describes how to run the package depot server on the build environment. Below we describe how to install those packages on your test environment.

Create and mount a new BE on the target host

While it is possible to change the publisher globally and/or have pkg update create your new boot environment (BE), this might not replace all packages (from default providers over to your nightly build), i.e. because "pkg:/" would block many of the updates.

NOTE: PKG publisher replacement logic can be reviewed viz. /code/illumos-gate/usr/src/tools/scripts/onu script, see configure_publishers()and update() routines.

Following the logic of ONU script, some steps are to be done manually, starting with the new alternate boot environment (ABE); if interested in more gory details, see that script's source code for procedures of updating a local zone's packages:

If the typically-used alternate BE mountpoint "/a" is for some reason occupied on your system, you could use another (available) path, like this:

Reconfigure the target host (new BE) to use your PKG depot over HTTP

On the target machine you should set up the (preferred, enabled) use of your new package publisher. On a test host you might want to set the publisher in a current global zone (without the -R option); that will be your default after boot anyway. But since the point of using alternate BEs is to be able to roll back to known-good configurations, we will only change the publishers in ABE, as onu does:


  • If you've used the proxy_base option to modify the PKG depot server's base URI, you should modify the client settings accordingly, to match the example above:

  • If you're doing this on a target host (local zone), on which you've already tried to use the filesystem-based repository, and it did not work (or you no longer wish to use it), you should remove the URL from your pkg client settings:

Lower the priority of original publisher, i.e.:

You may want to check now what publishers you have configured. Depending on other repositories you're using, the output might look like this:

  • NOTE: for file-based publisher (perhaps configured as a fallback, or on a target where you failed to remove it) you would see a line like this:

You may also want to pre-rebuild known-package indexes on the target machine (in particular, this tests access to all repositories). If you do this manually, you can save some time by skipping the catalog-refreshing stage during "dry-run" and "real" OS updates later on (by using the --no-refresh option to pkg update):

Update the OS on your target host (new BE)

After your target host has been configured to use your build host's package repository and the catalogs have been refreshed (as described above), you can just image-update the target machine and create a new boot environment in a standard manner.

First, remove the "entire" consolidation from the new BE, as that would block you from updating into packages fetched from another publisher:

If you only want to test if the image-update process is feasible (server-client connectivity is okay, enough free space on target, etc.), you can do a read-only "update" run instead of a real one:

NOTE that a dry-run still downloads the required packages (or at least their metadata) into the ABE's "$BEROOT/var/pkg/*" subdirectories. Keep this in mind if you have little free space actually available, or if your internet connectivity is paid-for (it is needed to check's packages), or if you require a proxy server to access the PKG depot (see below for HTTP proxy workarounds).


For a real OS upgrade you would do something like this (following the onu script logic):


  • If your connection from target machine to the PKG depot server requires an intermediate HTTP forward-proxy server, that can be arranged with http_proxy and/or https_proxy environment variables. Note that they might not transcend through the sudo command; so you might need to use syntax like this:

    or, to inherit your current user's settings:

If the installation reported no errors, promote the new BE for use after reboot:

List the resulting (current) boot environments to make sure all is OK:

Rinse and repeat (if needed)

If you want to reinstall today's build (i.e. test other building options) before rebooting into it, you should delete that BE first:

This should reactivate your currently-running BE for next boot. You may still want to run beadm list to make sure :)

After this, go back to the point where you beadm create a new BE - if you do want to try out your own build of illumos ;)

Reboot into the new BE

When you're finally satisfied, have your (remote) console access to the target host ready (just in case), and reboot the target into the newly generated build, and you will then be running your own build of illumos:

For more information about updating an OS image see:

To update an illumos (OpenIndiana) installation into newly built packages

If the currently booted BE already has the required package depots (local or remote) configured, you can update into a new build (forcing creation of a new BE) like this:

Like above, test that the new BE is ready for booting, and reboot: