Skip to end of metadata
Go to start of metadata

Redirection Notice
This page should redirect to Creating Your Own Images.

In addition to the Joyent-provided images, you can provision a SmartMachine from your own custom image.

This page shows you how to create a custom image from a running SmartMachine.

To complete this procedure, you will need to send a request to Joyent support. The estimated turn around time is approximately 4 business days for custom SmartOS images and 10 business days for custom KVM (Linux).

In this page:

At a Glance

This page describes how to create a custom image based on a running SmartMachine.

Overview

To create a custom image to that you can use to provision your own SmartMachines, you will need the following:

The procedure for creating a custom image is:

  1. Provision a SmartMachine using the base or base64 image.
  2. Update and upgrade the pkgsrc repository on that machine.
  3. Install the software that you want to be part of the image on the machine.
  4. Create a snapshot of the machine.
  5. Use the sm-prepare-image to make the machine image-ready.
  6. Power down the machine.
  7. Set the metadata for the image.
  8. Create a snapshot of the machine.
  9. Send a support request that includes the UUID of the machine and the name of the snapshot.

Custom images are intended to help you provision machines that contain the software you need. They are not intended to pre-populate databases or custom configuration. See Managing Application Configurations to learn about using configuration management tools.

Set Up the SmartMachine

It's best to use the base image. This image has only the minimal software, and it includes the tools that you will need to prepare the machine as an image.

  1. Provision a SmartMachine using the base or base64 image.
  2. Log in to the SmartMachine and bring the pkgsrc repository up to date.
  3. Upgrade the outdated packages.

Customize the SmartMachine

Install the software that you want included in every SmartMachine provisioned from this image. In this example, the only thing that we are adding to the base image is the Git source code control system.

  1. Install GIT. The name of the package is scmgit.
  2. Change the login message so you can easily identify your machine.

At this point, you can create user accounts that you want to appear in every machine provisioned from this image. To learn about creating user accounts see About Machine Accounts and Passwords.

The custom image should be no larger than 1GB and much smaller if possible. Large images take longer to transmit and to provision. To get an idea of how big your image is, use the df -h / command. The size reported in the Used column is the approximate size of the image:

Do not use custom images to pre-populate your machine with data. Use custom images to pre-install software packages and to set up user accounts that you will need on every machine that you provision. For data and machine configuration, use a package like Chef. See Managing Application Configurations.

Create a Snapshot

Preparing a SmartMachine to be the basis of an image makes permanent changes to it. It is a good idea to create a snapshot of it. The snapshot also gives you a starting point if you want to make a new version of of your image.

To create a snapshot, use the CloudAPI command line interface on a laptop or on a desktop machine. You will need the UUID of the SmartMachine you are using as basis of your image. The UUID is usually the default hostname of the machine, which you can find in the prompt.

If you have changed the host name or if you have changed the prompt, you can use the zonename command to get the UUID of the SmartMachine:

  1. Create the snapshot using your laptop or desktop machine. Use the sdc-createmachinesnapshot command with the UUID of the SmartMachine you are using as the basis of your image. Use the --name switch to give your snapshot a name.

    The name element in the response is the name of the snapshot.

  2. Check that the snapshot was created successfully. Use the sdc-getmachinesnapshot command passing the UUID of the machine and the name of the snapshot as an argument to the --snapshot switch.

    The snapshot is created successfully if the state element is either created or success.

Prepare the Machine

Back on the SmartMachine that you are using as the basis for your custom image, run the sm-prepare-image command. This command removes log files and other machine-specific files. It also removes references to specific IP addresses.

Run the command and follow the prompts.

If your image includes user accounts that you want to generate passwords for, don't power down the machine.

Create a file in /var/zoneinit/includes named 05-users.sh that sets the USERS environment variable to a space-separated list of user accounts. This list must include admin and root.

/var/zoneinit/includes/05-users.sh

Set the Metadata

After you have powered down the SmartMachine, go back to your laptop or desktop machine, and use the CloudAPI command line interface to set the SmartMachine's metadata. The image-creation process uses the metadata to set up information about the image.

Metdata key Description
image_name The name of the image. Must begin with "a-z" and may contain only the characters a-z, 0-9, ".", "-", "_".
image_version The version of the image.
image_description A short description of the image.
image_users (optional) A list of usernames separated by spaces that passwords should be generated for.

Use the CloudAPI sdc-updatemachinemetadata command on your laptop or desktop machine to set the metadata like this. The last parameter is the UUID of the SmartMachine.

Create the Snapshot for the Image

Finally, create another snapshot of the SmartMachine. This snapshot contains the state of the SmartMachine after it was prepared. This is the snapshot that Joyent support will use to create the image.

  1. Create the snapshot using your laptop or desktop machine.
  2. Check that the snapshot was created successfully.

Note the name of this snapshot. In this example, the name of the snapshot is prepared.

Send Request to Support

Create a support ticket containing the following information:

  • UUID of the SmartMachine
  • name of the snapshot
Do not power on the SmartMachine that you used as the basis for your custom image until you have received confirmation that the image was created and you have provisioned a machine with the image.
Labels:
creating creating Delete
smartmacine smartmacine Delete
image image Delete
customize customize Delete
snapshot snapshot Delete
api api Delete
command command Delete
line line Delete
metadata metadata Delete
setting setting Delete
up up Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.