Why Should You Create an Image?

The pkg command can be used to create and manage images. The pkg image-create subcommand sets up a relationship between the image, a publisher and a package repository that can be used to retrieve package information and content and perform packaging operations within an image.

An image is a location on your system where packages and their associated files, directories, links, and dependencies can be installed.

An image can be one of these types:

Full images, capable of providing a complete system
Partial images, which are linked to a full image (parent image), but do not provide a complete system on their own
User images, which contain only relocatable packages

After you have completed the installation of the OpenSolaris 2009.06 release on your system, the root file system and its contents are already contained within an image. As a result, you do not need to create an image to perform software management tasks for the installed system. However, creating images is required to provide logical separation between different software applications, such as those that occur during a zone creation process.

The following figure shows the concept of an image:

Figure 4-1 Concept of an Image

See the Zones section in the Solaris Containers - Resource Management and Solaris Zones guide to learn about zones.

The following image creation and image management tasks are supported:

Note - See the Table 10-1 section for a complete list of options supported with each pkg(1) command.

How to Create an Image
How to Display Image Properties
How to Set Image Properties
How to Remove Image Properties
How to Update an Image (Update All Installed Packages)

How to Create an Image

Before You Begin

Ensure that you have write privileges to the directory where you are attempting to create an image.

See the Image Creation: Important Considerations section for important information about image creation.

Use the following command to create an image. A user image is created by default.
$ pfexec pkg image-create -[R]-[FfPUz] -p prefix=repository_url directory_location

Example 4-1 Creating a Full Image

In this example, a full image is created with a package repository located at http://pkg.example.com, with example.com set as the preferred publisher. The image is created in the directory /aux0/example_root. The -p option is used to specify the location of the package repository such as http://pkg.example.com/.

$ pfexec pkg image-create -F -p example.com=http://pkg.example.com/ /aux0/example_root

How to Display Image Properties

Use the following command to view the properties of an image :

$ pkg property [-H] [propname]

The following properties are displayed :

Property Name	Description
send-uuid	This property causes the client to include a Universally Unique Identifier (UUID) in transactions with servers for the image. This property enables the server to uniquely identify clients.
require-optional	This property forces packages that are listed as an optional dependency of another package to be installed during installation, upgrade, or removal of a package.
flush-content-cache-on-success	A value of `True` will cause the download cache to be purged for the image upon successful completion of a packaging operation such as installation, uninstallation, or an image-update.
display-copyrights	Read—only for OpenSolaris 2009.06 release.
preferred-publisher	Read—only for OpenSolaris 2009.06 release.
pursue-latest	Read—only for OpenSolaris 2009.06 release.

Example 4-2 Displaying Image Property

$ pkg property 
PROPERTY                       VALUE 
send-uuid                      False 
require-optional               False 
flush-content-cache-on-success  False 
display-copyrights             True 
preferred-publisher            opensolaris.org 
pursue-latest                  True

How to Set Image Properties

Use the following command to set the property of an image:
$ pfexec pkg set-property propname

Note - The following properties are read-only and cannot be set using this command.
- display-copyrights
- preferred-publisher
- pursue-latest

Example 4-3 Set the Value of an Image Property

This example sets the value of the send-uuid property.

$ pkg  property
PROPERTY                       VALUE
send-uuid                      False
require-optional               False
flush-content-cache-on-success False
display-copyrights             True
preferred-publisher            opensolaris.org
pursue-latest                  True

$ pkg -R set-property send-uuid True
$ pkg property
PROPERTY                       VALUE
send-uuid                      True
require-optional               False
flush-content-cache-on-success False
display-copyrights             True
preferred-publisher            local
pursue-latest                  True

How to Remove Image Properties

Use the following command to remove one or more properties of an image.
$ pfexec pkg unset-property propname
The pkg unset-property command removes the specified properties and resets the property to the default value the next time a pkg(1)command is executed.

Note - The following properties are read-only and cannot be removed by using this command.
- display-copyrights
- preferred-publisher
- pursue-latest

Example 4-4 Remove an Image Property

This example removes the send-uuid property.

$ pkg unset-property send-uuid
$ pkg property
PROPERTY                       VALUE
send-uuid                      False
require-optional               False
flush-content-cache-on-success False
display-copyrights             True
preferred-publisher            local
pursue-latest                  True

How to Update an Image (Update All Installed Packages)

This task updates all installed packages in the current image to the latest available version.

Note - All packages that have been updated in the repository will be downloaded and installed.

All packages for the publishers configured in the image, excluding disabled publishers, will be retrieved and upgraded for those that have newer versions available. If more than one publisher offers the same package, then the package will be downloaded from the preferred publisher.

Use the following command to update all packages in the current image to the latest version.
$ pfexec pkg image-update

Example 4-5

$ pfexeec pkg image-update 
A clone of opensolaris exists and has been updated and activated.
On next boot the Boot Environment opensolaris-1 will be mounted on '/'.  
Reboot when ready to switch to this updated BE.
os# beadm list  
BE     Active Active on Mountpoint Space
Name  reboot               Used 
----   ------ --------- ---------- -----
opensolaris   yes    no   legacy   57.5K 
opensolaris-1 no     yes       -    2.59G

In this example, the initial boot environment created by the installer is named opensolaris. The boot environment created by the pkg image-update command is automatically named opensolaris-1.

After rebooting to the changed boot environment, any inactive boot environment can be destroyed to save space by running the beadm destroy command. For more information regarding boot environments and the beadm(1) command, see the Upgrading and Managing Your Boot Environments section.

Example 4-6 Update an Image in a Mounted, Inactive Boot Environment

This example updates an image in a boot environment that is mounted at /mnt.

# beadm mount BE1 /mnt
# pkg -R /mnt image-update

Image Creation: Important Considerations

When using the image-create subcommand, avoid creating an image at the location of an already existing image such as / for an installed system or within a directory contained within an existing package such as /usr. This will cause you to lose packaging information within an image, or prevent IPS from properly managing packages within the image.
You must set publisher and package repository information when you create an image. Use the -p option to provide this information.
When you have multiple images on your system, use the PKG_IMAGE environment variable or the -R option to specify what image you're operating on.
The current design of IPS assumes that only one version of a package is installed in a single image. To install multiple versions of the same package, ensure that the name of the package includes the version number, and dependencies reflect the version number and bind to the appropriate package version.

Updating Your Image: Important Considerations

When you run the pkg image-update command or update your image using the Package Manager, the process of updating all the packages automatically creates a clone: a new, bootable environment. The process of updating all the packages applies the changes to the clone instead of to the original boot environment. After the successful completion of the changes to the clone and system reboot, the new clone is provided as the default, active boot environment in the GRUB menu. The original boot environment remains on the GRUB menu as an alternate selection.
A clone of the boot environment includes everything hierarchically under the main root dataset of the original boot environment. Shared file systems are not under the root dataset and are not cloned. Instead, the boot environment accesses the original shared file systems.
The pkg image-update command does not upgrade zones. If you have included zones in your OpenSolaris environment, the pkg image-update command clones these existing zones into the new boot environment, but these zones are not upgraded. You must manually upgrade each of these zones.
After upgrading an image or boot environment, you can use the beadm list command to see a list of the boot environments on the system, including the new boot environment that was created by the pkg image-update command.