View Source

{info:title=New!}March 26, 2012: [VM Guest tools|] contains scripts and drivers that are used to create virtualized machine images in SmartOS.{info}

In SmartOS, virtual machines are created using the {{vmadm create}} tool. This tool takes a JSON payload and creates either a 'kvm' or 'joyent' brand zone with the properties specified in the input JSON. Normal output is a series of single-line JSON objects with type set to one of:

* success
* failure
* update
* notice

each object having at least the 'type' and 'message' fields. A message of type 'success' or 'failure' will be followed by the process exiting with the exit status 0 indicating success and all other exits indicating failure.

{code}vmadm create -f <filename.json>{code}

h1. Getting Started

You will need

* The latest copy of SmartOS, available from []&nbsp;(release details [here|Download SmartOS])
* The ISO of your OS of choice
* A VNC client

h1. The Machine JSON Description

Save the code snippet below to a file called "vmspec.json". You can make changes to the networks and other variables as appropriate. This is by no means an exhaustive list of all options. For all options see [vmadm(1m)|]. (Sizes are listed in MiB)
"brand": "kvm",
"vcpus": 1,
"autoboot": false,
"ram": 1024,
"resolvers": ["", ""],
"disks": [
"boot": true,
"model": "virtio",
"size": 40960
"nics": [
"nic_tag": "admin",
"model": "virtio",
"ip": "",
"netmask": "",
"gateway": "",
"primary": 1
{note}For releases before December 15, 2011, you will need to include the {{default_gateway}} attribute in the root:
"default_gateway": "",
This must match the gateway of one of the nics so that the default gateway and resolvers will be set via DHCP in the VM.{note}
When installing OS's that do not ship with&nbsp;{{virtio}} support instead of using&nbsp;{{virtio}} on the disk for the model use&nbsp;{{ide}} and&nbsp;{{e1000}} for the network model.

h1. Create the Empty Virtual Machine

Create the empty virtual machine using the create-machine tool. Please note that the virtual machine will not be running.

{code}$ vmadm create{code}

Note the UUID in the last step. This UUID is the ID of the VM and will be used to reference it for the rest of its lifecycle.

$ vmadm create < vmspec.json

{"percent":1,"type":"update","message":"checking and applying defaults to payload"}
{"percent":2,"type":"update","message":"checking required datasets"}
{"percent":28,"type":"update","message":"we have all necessary datasets"}
{"percent":29,"type":"update","message":"creating volumes"}
{"percent":51,"type":"update","message":"creating zone container"}
{"percent":94,"type":"update","message":"storing zone metadata"}
{"uuid":"b8ab5fc1-8576-45ef-bb51-9826b52a4651","type":"success","message":"created VM"}

h1. Copy your OS ISO to the zone

$ cd /zones/b8ab5fc1-8576-45ef-bb51-9826b52a4651/root/
$ wget

h1. Ensure permissions are correct on the ISO
$ chown root debian.iso
$ chmod u+r debian.iso

h1. Boot the VM from the ISO Image

{{vmadm}} is the virtual machine administration tool. It is used to manage the lifecycle of a virtual machine after it already exists. We will boot the virtual machine we have just created, but tell it to boot off of the ISO image the first time it comes up.

{code}vmadm boot b8ab5fc1-8576-45ef-bb51-9826b52a4651 order=cd,once=d cdrom=/debian.iso,ide{code}

Please note that the path for the ISO image will be the relative path of the ISO to the zone you are in. This is why it starts with the '/'

h1. Use VNC to Connect to the VM

The {{vmadm}} tool can print out the information on the VM. You can also append a section to print specificially.

$ vmadm info b8ab5fc1-8576-45ef-bb51-9826b52a4651 vnc

"vnc": {
"display": 39565,
"port": 45465,
"host": ""

Your VM is now running. You can shutdown your virtual machine and it will still remain on disk. To learn more about managing the lifecycle of a virtual machine, run {{vmadm \--help}}.

h2. Troubleshooting

h3. Zone Networking Issues

If you are running SmartOS as a guest vm then you might have networking issues with your zones. In order to fix this we need to create a bridge.
If you look at&nbsp;[] You can see that the script will create a bridge for vmare products but if you are using VirtualBox or Parallells then you need to do it manually.

$ ifconfig -a
e1000g0: flags=1100943<UP,BROADCAST,RUNNING,PROMISC,MULTICAST,ROUTER,IPv4> mtu 1500 index 2
inet netmask ffffff00 broadcast
ether 8:0:27:e1:35:cb

$ dladm create-bridge -l e1000g0 vboxbr
Your zones should now be able to access the network. You don't need to change the nic_tag for any of the zones, leave them as "admin" or "external".

There is a way to make this happen on boot with my adding an smf script to&nbsp;/opt/custom/smf. Here is a nice write up that shows you how it's done.&nbsp;[|]

h1. Further Reading

Those versed in JavaScript can learn a lot more by reading the [vmadm.js source|].