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.
The default image server is datasets.joyent.com 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:
To download one of these images, say "base64", we'll import it using the images UUID:
To learn how to create a Zone or VM from these images, please refer to:
An image is the data and metadata required to create a new VM. The "data" is one or more compressed ZFS datasets which will be cloned to create a new VM. The "metadata" describes, as JSON, the data and outlines the specification for a machine that would utilize it.
Here is an example of the two files:
The following is an example manifest taken from the public repository https://datasets.joyent.com/datasets/ (re-arranged and line breaks added for clarity).
You'll notice we have properties to identify the image (UUID, name, version, description, etc), the author (creator_name, creator_uuid, etc), when the image was created/updated/published, and then an array identifying the ZFS Dataset file or files, and finally an array outlining some requirements.
When creating your own manifest, 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>
The requirements section is recommended but not currently required, nor is it enforced.
The process of creating a zone image looks like this:
- Create and customize a zone as you wish
- Purge the logs, etc.
- Halt the zone: vmadm stop <UUID>
- Snapshot the Zone dataset: zfs snapshot zones/<UUID>@image
- Dump & Compress the dataset: zfs send zones/<UUID>@image | gzip > image_name.zfs.gz
- Create the manifest as described above
You can now import the image locally via imgadm or transfer it to an image server.
Datasets must be compressed. You may use either GZip or BZip2. BZip2 will offer a smaller file, but GZip compression is faster. Particularly for datasets larger than 10GB, GZip is highly recommended.
The process of creating a KVM image looks like this:
- Create and customize a KVM instance as you wish
- Purge and ready the instance
- Halt the VM: vmadm stop <UUID>
- Snapshot the disk0 ZVol: zfs snapshot zones/<UUID>-disk0@image
- Dump & Compress the dataset: zfs send zones/<UUID>-disk0@image | gzip > image_name.zvol.gz