Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

Images are managed using the imgadm tool. With this tool you can:

  • View & Download images available on a public image server
  • Import remote images or Install from local images
  • List, Show or Print details about an image
  • Destroy images

Here we'll discuss how to find available images and start using them. Then we'll look at what images are and how to create our own.


Viewing & Downloading Public Images

The default image server is and will be found in your /var/db/imgadm/sources.list file. Using the command imgadm update, you'll cause the local cache (/var/db/imgadm/imgcache.json) to be updated with the available images on the servers found in your sources.list. Once your local cache is updated, you can list all available images for use using imgadm avail:

# cat /var/db/imgadm/sources.list

# imgadm update
updating local images database...

# imgadm avail | head
UUID                                 OS      PUBLISHED  URN
6bf31ce2-f384-11e1-a338-e39c2fe4ab59 smartos 2012-08-31 sdc:sdc:mongodb:1.3.2
a0f8cf30-f2ea-11e1-8a51-5793736be67c smartos 2012-08-30 sdc:sdc:standard64:1.0.7
3390ca7c-f2e7-11e1-8818-c36e0b12e58b smartos 2012-08-30 sdc:sdc:standard:1.0.7
9604da58-f1ee-11e1-aba1-dbda3337ec46 smartos 2012-08-29 sdc:sdc:mongodb:1.3.1
15c77de2-f1ed-11e1-8688-47d8455c7932 smartos 2012-08-29 sdc:sdc:standard64:1.0.5
2baee822-f1eb-11e1-8383-f762d43a424c smartos 2012-08-29 sdc:sdc:standard:1.0.5
e8c41d40-f161-11e1-b839-a3631c115653 smartos 2012-08-28 sdc:sdc:base64:1.7.2
9012a9c2-f15d-11e1-a33a-afaec53ebde9 smartos 2012-08-28 sdc:sdc:base:1.7.2
45e0fa58-db5e-11e1-a1f0-df041127b335 smartos 2012-07-31 sdc:sdc:mongodb:1.3.0

To download one of these images, say "base64", we'll import it using the images UUID:

# imgadm import e8c41d40-f161-11e1-b839-a3631c115653
e8c41d40-f161-11e1-b839-a3631c115653 doesnt exist. continuing with install
e8c41d40-f161-11e1-b839-a3631c115653 successfully installed
image e8c41d40-f161-11e1-b839-a3631c115653 successfully imported

# imgadm list
UUID                                 OS      PUBLISHED  URN
e8c41d40-f161-11e1-b839-a3631c115653 smartos 2012-08-28 sdc:sdc:base64:1.7.2

To learn how to create a Zone or VM from these images, please refer to:

  • ...
  • ...

Advanced Topics

What is an Image?

An image is the data and metadata required to create a new VM. The "data" is one or more compressed ZFS filesystems (for Zones) or ZVols (for KVM instances) which will be cloned to create a new VM. The "metadata" describes, in JSON, the data and outlines the specification for a machine that would utilize it.

Here is an example of the two files:

benr@magnolia:~/datasets$ ls -lh
total 41M
-rw-rw-r-- 1 benr benr 996 Sep 10 14:54 smartos-1.3.12.dsmanifest
-rw-rw-r-- 1 benr benr 41M Jun 10  2011 smartos-1.3.12.zfs.bz2

If we look at the manifest (taken from the public repository:, it looks like this:

    "name": "smartos",
    "version": "1.3.12",
    "type": "zone-dataset",
    "description": "Base template to build other templates on",
    "created_at": "2011-04-11T08:45Z",
    "updated_at": "2011-04-11T08:45Z",
    "os": "smartos",
    "files": [
        "path": "smartos-1.3.12.zfs.bz2",
        "sha1": "246c9ae158dc8f204643afdd6bd4d3c4aa35e733",
        "size": 42016482,
        "url": ""
    "requirements": {
      "networks": [
          "name": "net0",
          "description": "public"
    "uuid": "febaa412-6417-11e0-bc56-535d219f2590",
    "vendor_uuid": "352971aa-31ba-496c-9ade-a379feaecd52",
    "creator_uuid": "352971aa-31ba-496c-9ade-a379feaecd52",
    "creator_name": "sdc",
    "platform_type": "smartos",
    "cloud_name": "sdc",
    "urn": "sdc:sdc:smartos:1.3.12",
    "published_at": "2011-04-11T08:45Z"

The following properties are required:

  • '''uuid''': The UUID of the image (use an online UUID generator)
  • '''name''': The name of the image (eg: "centos-6")
  • '''version''': The version of the image (eg: "1.0.0")
  • '''description''': A short description of the image
  • '''published_at''': A timestamp for the date of publication on an image server (this does not need to be accurate); to output the current time in the proper format use the command: date +"%Y-%m-%dT%T.000Z"
  • '''creator_uuid''': The UUID of the author of the image (use an online UUID generator if you don't have one)
  • '''creator_name''': The name of the image author
  • '''urn''': A special string for describing the image in the form "cloud_name:creator_name:name:version"; for the "cloud_name" I suggest "smartos" if you are unsure, the creator name is usually your organization. The string should not contain spaces. (eg: "smartos:cuddletech:plan9:1.0.0")
  • '''type''': The type of image, either "zvol" for KVM or "zone-dataset" for Zones
  • '''os''': The OS of this image (this is required, but not validated or used, so use whatever you like)
  • '''files''': An array of one or more file objects, containing the following properties for each:
    • '''path''': Local file path to the image data file (compressed zfs dump)
    • '''sha1''': The SHA1 for the image data file; to obtain the SHA1 hash use: digest -a sha1 <file>
    • '''size''': The file size of the image data file; to obtain use: ls -l <file>

PROCESS: Creating a Custom Zone Image

PROCESS: Creating a Custom KVM Image

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.