Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022



distro_const - Utility for creating Oracle Solaris images and media


/usr/bin/distro_const -h
/usr/bin/distro_const build [-v] [-r checkpoint_name]
    [-p checkpoint_name] [-l] manifest


The distro_const command enables users to create an image by using a specified manifest file as the blueprint for the image.

    You can create any of the following images:

  • A text installer image that can be used to install the Oracle Solaris operating system on either x86 systems or SPARC systems.

  • A SPARC AI ISO image that can be used for network installations of the Oracle Solaris OS on SPARC clients, or an x86 AI ISO image that can be used for network installations of the Oracle Solaris OS on x86 clients.

  • A custom ISO image.

  • A bootable x86 disk image suitable for import into a cloud environment such as Oracle Cloud Infrastructure (OCI).

The distro_const build command with no options creates a full image in one step.

Options enable you to pause and resume the image creation process at various checkpoints, thus enabling you to review status of the image and to check for bugs at each stage. Checkpointing saves time during builds by allowing you to bypass lengthy steps that have already been done at least once.

Note - You must assume the root role or have root privileges to run the distro_const command.

When using the distribution constructor, you can create only SPARC images on a SPARC system, and you can create only x86 images on an x86 system. Also, the operating system release version on your system must be the same release version as the image that you are building.

When building an x86 disk image, you may create a raw img file, a qcow2 image, or a vmdk image. Creating a qcow2 image requires the qemu-img command, which is provided as part of Solaris. Creating a vmdk image depends on the VBoxManage command that is provided as part of VirtualBox, which can be downloaded from https://www.virtualbox.org. A raw img file can be streamed directly to a raw disk device using /usr/bin/dd or converted to other formats using tools such as qemu-img or VBoxManage.



Display a usage message.

Sub Commands

The distro_const command has the subcommand and options listed below. Also see the “Examples” section.

build [–v] [–r resume_checkpoint] [–p pause_checkpoint ] [–l] manifest

With no options, create a full image, using the specified manifest file as the blueprint for that image.


Show verbose output.


List all valid checkpoints at which you can choose to pause or resume building an image. This option queries the manifest manifest file for valid checkpoints. Use the names provided by this option as valid values for the other checkpointing options.

–p pause_checkpoint
–-pause pause_checkpoint

Build an image, pausing at the specified checkpoint name. Use the –l option to find valid checkpoint names. You can combine the –p and –r options.

–r resume_checkpoint
–-resume resume_checkpoint

Resume building the image from the specified checkpoint name. The specified checkpoint name must be either the checkpoint at which the previous build stopped executing, or an earlier checkpoint. A later checkpoint is not valid. Use the –l option to determine which checkpoints are resumable. You can combine the –r and –p options.


Example 1 Create an Image Using Checkpoint Options
  1. Check which checkpoints are available.

    # distro_const build -l /usr/share/distro_const/dc_text_x86.xml
    Checkpoint           Resumable Description
    -----------          --------- -----------------------
    transfer-ips-install X         Transfer pkg contents from IPS
    set-ips-attributes   X         Set post-install IPS attributes
    pre-pkg-img-mod      X         Pre-package image modification
    ba-init              X         Boot archive initialization
    ba-config            X         Boot archive configuration
    ba-arch              X         Boot archive archival
    boot-setup           X         Set up GRUB menu
    pkg-img-mod          X         Pkg image area modification
    create-iso                     ISO media creation
    create-usb                     USB media creation
    checksums                      Checksum calculation for media
  2. Start building the image and pause at the ba-init checkpoint.

    # distro_const build -p ba-init /usr/share/distro_const/dc_text_x86.xml
  3. Restart the build from the ba-init checkpoint. Finish creating the image.

    # distro_const build -r ba-init /usr/share/distro_const/dc_text_x86.xml
Example 2 Create an Image in One Step

To run a complete build of an image without pausing, use the distro_const command with no options.

# distro_const build /usr/share/distro_const/dc_text_x86.xml


See attributes(7) for descriptions of the following attributes:

Interface Stability

See Also


Creating a Custom Oracle Solaris 11.4 Image