Skip to end of metadata
Go to start of metadata

Creating KVM VM's

Before creating a new KVM VM, a zone template image must be imported. KVM templates are ZFS zvol snapshots with a (typically) freely-distributable operating system such as a Linux variant pre-installed. Images are available through the imgadm tool.

You will then be able to create and install zones and virtual machines using vmadm create.

To list all available KVM images from Joyent:

note that KVM images usually say something like "linux" or "bsd" in the "OS" column of this output and "zvol" as the "TYPE".
"smartos" images (zone templates) and images with "LX" in their names (datasets for use with LX-branded zones)
aren't appropriate for the process being described here. These images cannot be used to create KVM VM's.

To list all local images installed in on your SmartOS host:

To import an image from Joyent, use the UUID of the image (from imgadm avail):

The image is now downloaded and installed at zones/UUID.

vmadm create is a tool for fast provisioning of zones and KVM VMs; it takes a json payload and clones an image into a working virtual machine.

To use vmadm create you must first start by creating your VM/zone definition file, for instance copying this in to /tmp/myvmspec (substituting the image_uuid, network information, and machine dimensions that are appropriate):

First, ensure you've imported the image you've specified in the vmspec file. In the above example, you'd

then simply

and vmadm will respond with a status and your VM will be created and booted.

Once you have created the VM with vmadm create, you can see your VM's video console by finding it's VNC connection info:

Then connect to that VNC service with your local workstation's VNC viewer.

Be aware that the VNC console service is NOT authenticated, and is intended to run on a private network. Typically, your SmartOS machine won't have it's primary interface on the internet. Please be aware of what services you're exposing, and apply firewall rules as necessary.
RealVNC VNC Viewer will crash when connecting unless you set FullColour to True in the options.  On Windows make sure to go to Options, click Advanced, go to the Expert tab and set FullColour to True.

Note that the VM images distributed by Joyent at are designed to be used with SmartDatacenter, and typically have hooks to set passwords and/or ssh keys from SmartDatacenter services. To use them with the open-source SmartOS, you'll probably need to first boot single-user and set a password for the root user.

Passing SSH keys to the VM

With some images you won't be able to log in to unless you pass an SSH public key to validate your connection with. Adjust your config to contain a customer_metadata block:

Passing cloud-init data to the VM

SmartOS provides the ability to inject cloud-init data into a zone/VM. This is useful for automating the menial tasks one would need to perform manually like setting up users, installing packages, or pulling down a git repo. Basically, anything you can stuff into cloud-init user-data is at your disposal.

Since SmartOS zone definitions are in JSON and cloud-init data is in yaml, it’s not immediately obvious how to supply this information. Maintaining proper yaml indentation, escape all double-quotes (“) and line-feeds.

Here’s an example cloud-init yaml file that creates a new user and imports their ssh key from

Here's what it would look like in our zone definition.

You can find more on cloud-init at

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