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:

$ BENAME="nightly-`date +%Y-%m-%d`" && \
  sudo beadm create "$BENAME" 
$ BEROOT="/a" && \
  sudo beadm mount "$BENAME" "$BEROOT"

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

$ BEROOT="/tmp/.$BENAME.$$" && \
  sudo beadm mount "$BENAME" "$BEROOT" 

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:

$ sudo pkg -R "$BEROOT" set-publisher -P -e --no-refresh \
  -O http://<builder-IP-address>:8151/ on-nightly


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

$ sudo pkg -R "$BEROOT" set-publisher --no-refresh \

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

$ sudo pkg -R "$BEROOT" publisher -a

PUBLISHER                     TYPE     STATUS   URI
on-nightly       (preferred)  origin   online  (non-sticky) origin   online  (non-sticky) origin   online
sfe                           origin   online
sfe-encumbered                origin   online

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):

$ sudo pkg -R "$BEROOT" refresh --full

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:

$ sudo pkg -R "$BEROOT" list entire && \
  sudo pkg -R "$BEROOT" uninstall entire

                Packages to remove:     1
           Create boot environment:    No
PHASE                                        ACTIONS
Removal Phase                                  55/55 

PHASE                                          ITEMS
Package State Update Phase                       1/1 
Package Cache Update Phase                       1/1
Image State Update Phase                         2/2 

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:

$ sudo pkg -R "$BEROOT" image-update --no-refresh -v -n

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):

$ sudo pkg -R "$BEROOT" image-update --no-refresh -v

Creating Plan...
               Packages to install:     2
                Packages to update:   960
           Create boot environment:    No
               Services to restart:     3
              Rebuild boot archive:   Yes
Changed fmris:
DOWNLOAD                                  PKGS       FILES    XFER (MB)
Completed                              962/962 11137/11137  337.8/337.8

PHASE                                        ACTIONS
Removal Phase                              5094/5094 
Install Phase                              5357/5357 
Update Phase                             14097/14097 

PHASE                                          ITEMS
Package State Update Phase                 1922/1922 
Package Cache Update Phase                   960/960 
Image State Update Phase                         2/2 

NOTE: Please review release notes posted at:


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

$ sudo beadm activate "$BENAME" 

Activated successfully

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

$ sudo beadm list

BE                 Active Mountpoint                    Space Policy Created
nightly-2012-02-13 R      /tmp/.nightly-2012-02-13.9342 13.6G static 2012-02-13 19:37
oi_148a            -      -                             477M  static 2011-03-25 22:31
oi_148a-1          -      -                             4.27G static 2011-04-12 12:46
oi_151a            N      /                             433K  static 2012-01-23 22:23
openindiana        -      -                             702M  static 2011-03-22 20:12

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:

$ sudo beadm umount "$BENAME" 
$ sudo beadm destroy "$BENAME" 
Are you sure you want to destroy nightly-2012-02-13?
This action cannot be undone (y/[n]): y

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:

$ sudo init 6

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:

$ sudo pkg update --require-new-be --be-name nightly-2012-02-23

                Packages to update:   344
           Create boot environment:   Yes
DOWNLOAD                                  PKGS       FILES    XFER (MB)
Completed                              344/344     891/891      4.6/4.6

PHASE                                        ACTIONS
Update Phase                               3588/3588 

PHASE                                          ITEMS
Package State Update Phase                   688/688 
Package Cache Update Phase                   344/344 
Image State Update Phase                         2/2 

A clone of nightly-2012-02-14 exists and has been updated and activated.
On the next boot the Boot Environment nightly-2012-02-23 will be mounted on '/'.
Reboot when ready to switch to this updated BE.

NOTE: Please review release notes posted at:

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

$ sudo beadm list

BE                 Active Mountpoint Space Policy Created
nightly-2012-02-14 N      /          176K  static 2012-02-14 19:37
nightly-2012-02-23 R      -          15.6G static 2012-02-24 00:42
oi_148a            -      -          477M  static 2012-02-13 23:46
oi_148a-1          -      -          4.27G static 2012-02-13 23:20
oi_151a            -      -          8.36M static 2012-01-23 22:23

$ sudo init 6