Creating Your Own SmartMachine Image

Modified: 05 Jan 2015 18:06 UTC
Error formatting macro: redirect: java.lang.NullPointerException
Writer's Note

Deprecated. See 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.
    [root@e4b806d6-e78c-4d45-ab19-a56af0a68634 ~]# pkgin updates
    pkg_summary.gz                      100%  435KB 217.3KB/s 194.5KB/s   00:02
    processing remote summary (http://pkgsrc.joyent.com/sdc6/2012Q1/i386/All)...
    updating database: 100%
    
  3. Upgrade the outdated packages.
    [root@e4b806d6-e78c-4d45-ab19-a56af0a68634 ~]# pkgin upgrade
    calculating dependencies... done.
    2 packages to be upgraded: smtools-20120704 nodejs-0.8.1
    2 packages to be installed: smtools-20120712 nodejs-0.8.2 (15M to download, 0B to install)
    proceed ? [Y/n]
    downloading packages...
    smtools-20120712.tgz                100%   23KB  23.1KB/s  23.1KB/s   00:01
    nodejs-0.8.2.tgz                    100% 4880KB 488.0KB/s 196.3KB/s   00:10
    removing packages to be upgraded...
    removing smtools-20120704...
    removing nodejs-0.8.1...
    pkg_install warnings: 0, errors: 0
    installing packages...
    installing smtools-20120712...
    installing nodejs-0.8.2...
    pkg_install warnings: 0, errors: 0
    reading local summary...
    processing local summary...
    updating database: 100%
    

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.
    [root@e4b806d6-e78c-4d45-ab19-a56af0a68634 ~]# pkgin install scmgit
    calculating dependencies... done.
    
    nothing to upgrade.
    17 packages to be installed: p5-Digest-SHA-5.62 p5-Digest-MD5-2.51nb1 heimdal-1.5.2nb1 libgetopt-1.4.4 libssh2-1.2.2nb1 libidn-1.24 p5-GSSAPI-0.28nb2 p5-Digest-HMAC-1.03 perl-5.14.2nb5 p5-MIME-Base64-3.13nb1 p5-Error-0.17017 p5-Authen-SASL-2.15nb1 expat-2.1.0 curl-7.24.0 scmgit-docs-1.7.9.3 scmgit-base-1.7.9.3 scmgit-1.7.9.3 (228M to download, 0B to install)
    
    proceed ? [Y/n] Y
    downloading packages...
    
    ...
    
    installing scmgit-1.7.9.3...
    pkg_install warnings: 0, errors: 0
    reading local summary...
    processing local summary...
    updating database: 100%
    marking scmgit-1.7.9.3 as non auto-removable
    [root@e4b806d6-e78c-4d45-ab19-a56af0a68634 ~]# git --version
    git version 1.7.9.3
    
  2. Change the login message so you can easily identify your machine.
    [root@e4b806d6-e78c-4d45-ab19-a56af0a68634 ~]# cat > /etc/motd <<EOF
    > Welcome to Base + Git
    > EOF
    

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:

$ df -h /
Filesystem                                  Size  Used Avail Use% Mounted on
zones/e4b806d6-e78c-4d45-ab19-a56af0a68634   31G  375M   30G   2% /
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:

[root@e4b806d6-e78c-4d45-ab19-a56af0a68634 ~]# zonename
e4b806d6-e78c-4d45-ab19-a56af0a68634
  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.
    $ sdc-createmachinesnapshot --name basis e4b806d6-e78c-4d45-ab19-a56af0a68634
    {
      "name": "basis",
      "state": "queued",
      "created": "2012-07-23T15:14:30+00:00",
      "updated": "2012-07-23T15:14:30+00:00"
    }
    

    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.
    $ sdc-getmachinesnapshot e4b806d6-e78c-4d45-ab19-a56af0a68634 --snapshot basis
    {
      "name": "basis",
      "state": "success",
      "created": "2012-07-23T15:14:30+00:00",
      "updated": "2012-07-23T15:14:35+00:00"
    }
    

    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.

[root@e4b806d6-e78c-4d45-ab19-a56af0a68634 ~]# sm-prepare-image

*** WARNING: PLEASE READ CAREFULLY!  THIS SCRIPT WILL ALTER YOUR SYSTEM ***

This script cleans up the file system of your machine, and makes it ready
for turning into a provisionable image. Irreversible changes are made to this
machine's filesystem for the sake of the image preparation, so if you intend
to continue to use this machine, make sure you have a sanity snapshot created
first that you can roll back to when you're done. If you made this machine for
the image purposes only and are fine discarding it later on, you do not
need a snapshot.

This script will:

  Change hard coded IP addresses to variables [optional]
  Delete transient files and log files
  Unset passwords for 'root' and 'admin' users
  Reset network information

If you are at all unsure, stop now and check the script.

Do you want to proceed? y/N y

=> Removing volatile files

=> Removing users' volatile information
==> Removing files for user root
==> Unsetting password for user root
==> Removing files for user admin
==> Unsetting password for user admin

=> Cleaning up old network configuration

=> Looking for hard coded IP addresses

The script will look for IP addresses associated with this machine, which
won't match those of the machines provisioned from the image you are about
to create. You can have the addresses turned into placeholders that will be
automatically populated by the IP addresses when provisioning.

We recommend you avoid using hardcoded IP addresses in the first place, unless
there is no other alternative.

Do you want place holders put in place of IP addresses? Y/n y
. /etc/ipf/ipf.conf: '10.88.88.12' => '@PRIVATE_IP@'

=> Creating a basic zoneinit instance

=> File system prepared successfully, finishing

The script is finished now.

This machine should now be powered off, a snapshot taken, and an image created
from the snapshot. Please contact support to have the image created, and refer
to "Creating Your Own SmartMachine Image" in the wiki (http://wiki.joyent.com/wiki/x/zgCC)
for more information.

One reason to not power off now would be to inspect the zoneinit files (start
scripts executed when a new machine is provisioned) at /var/zoneinit and
optionally implement your own ones in /var/zoneinit/includes.

Do you want to power this machine off now? Y/n y

Powering down in 10 seconds... (Ctrl C if not desired)

[root@e4b806d6-e78c-4d45-ab19-a56af0a68634 ~]# Connection to 10.88.88.12 closed by remote host.
Connection to 10.88.88.12 closed.

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
USERS="admin root bert ernie"

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.

$ sdc-updatemachinemetadata \
> -m image_name="base-git" \
> -m image_version="1.0.0" \
> -m image_description="base 1.7.0 + git" \
> e4b806d6-e78c-4d45-ab19-a56af0a68634
{
  "image_name": "base-git",
  "image_version": "1.0.0",
  "image_description": "base 1.7.0 + git"
}

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.
    $ sdc-createmachinesnapshot --name prepared e4b806d6-e78c-4d45-ab19-a56af0a68634
    {
      "name": "prepared",
      "state": "queued",
      "created": "2012-07-23T15:22:38+00:00",
      "updated": "2012-07-23T15:22:38+00:00"
    }
    
  2. Check that the snapshot was created successfully.
    $ sdc-getmachinesnapshot --machine e4b806d6-e78c-4d45-ab19-a56af0a68634 prepared
    {
      "name": "prepared",
      "state": "success",
      "created": "2012-07-23T15:22:38+00:00",
      "updated": "2012-07-23T15:22:41+00:00"
    }
    

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:

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.