Skip to end of metadata
Go to start of metadata

OS Virtualized Machines, hereafter referred to as Zones, is a lightweight virtualization technology. Zones are fully isolated user-land environments, they do not possess their own kernel and therefore have effectively no performance overhead allowing for bare metal performance. Network and disk virtualization are provided by ZFS and the SmartOS networking stack ("Crossbow"). The result is a virtual environment that in every way acts like a complete environment.

Creating Zones

The process of creating zones is simple:

  1. Download a Zone Image
  2. Create a Manifest describing the Zone
  3. Create the Zone using vmadm
  4. Use the Zone

Obtaining a Zone Image

Zone creation requires an image to use as a template.

To find a zone image, use the command imgadm avail. Images with the OS type "smartos" are zone images. The "base" and "base-64" images are minimal images with only a basic 32bit or 64bit pkgsrc installation and should be considered for building your own custom images.

# imgadm avail | grep base-64
c02a2044-c1bd-11e4-bd8c-dfc1db8b0182  base-64-lts             14.4.0      smartos  2015-03-03T15:55:44Z
24648664-e50c-11e4-be23-0349d0a5f3cf  base-64-lts             14.4.1      smartos  2015-04-17T14:15:04Z
4166f6d6-ea5f-11e4-addd-8351b159d9b6  base-64                 15.1.0      smartos  2015-04-24T08:52:36Z
b67492c2-055c-11e5-85d8-8b039ac981ec  base-64-lts             14.4.2      smartos  2015-05-28T17:12:26Z
0edf00aa-0562-11e5-b92f-879647d45790  base-64                 15.1.1      smartos  2015-05-28T17:50:41Z
5c7d0d24-3475-11e5-8e67-27953a8b237e  base-64                 15.2.0      smartos  2015-07-27T15:37:17Z

Import an image by specifying its UUID:

# imgadm import 5c7d0d24-3475-11e5-8e67-27953a8b237e
Importing 5c7d0d24-3475-11e5-8e67-27953a8b237e (base-64@15.2.0) from "https://images.joyent.com"
Gather image 5c7d0d24-3475-11e5-8e67-27953a8b237e ancestry
Must download and install 1 image (127.2 MiB)
Imported image 5c7d0d24-3475-11e5-8e67-27953a8b237e (base-64@15.2.0)

You will referenced this images UUID when you create the zone manifest.

The Zone Manifest

A manifest is a JSON object which describes your zone. There are many options which are fully described in the vmadm(1m) man page. The most important are:

  • brand: This must be set to "joyent" for Zones
  • image_uuid: The UUID of the image you are using as a template (images were previously called "datasets")
  • alias: An arbitrary name displayed in vmadm list output in addition to the UUID
  • hostname: Hostname that will be set within the zone
  • max_physical_memory: Amount of RAM (RSS) available to the zone in MB
  • quota: Amount of disk space in GB
  • resolvers: DNS nameservers for this zone to use (placed in the zone's /etc/resolv.conf file)
  • nics: One or more network interfaces attached to this zone

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:

Creating the Zone

With your image imported and your manifest created, you can now create the zone. Do this by simply passing the manifest to vmadm create -f manifest.json:

# vmadm create -f web01.json
Successfully created VM d6a0a022-3855-4762-a2e5-3f16969ca2fb

Alternatively, you can pass the manifest via STDIN:

# vmadm create <<EOL
  (manifest json here)
EOL

The zone is now created and running.

Connecting to your Zone

Once you have created a zone with vmadm create, you can log into your zone via one of two methods:

or

Please refer to the manpage for vmadm(1m) and zlogin(1) respectively, for the escape sequence to exit out of console mode.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Oct 23, 2012

    How to set up a Chinese character set in smartOS machine: zh_CN.gbk
    # locale  -a
    ...
    zh_CN.UTF-8
    ...
    But I did not find zh_CN.gbk
    Can you help me?

  2. Oct 28, 2012

    It'd be great to add information on where to look for login credentials for joyent templates. Case in point I have just created a new VM using the base64 template and I have no idea what username / password to use on its console. 

    ...

    So I realised I should use the 'zlogin UUID' method as that doesn't require authentication, then 'passwd admin' etc. (as opposed to 'vmadm console UUID' which of course gives you the console login prompt).

    I also tried replacing the password in the zones shadow file but that didn't seem to work. 

    1. Feb 19, 2015

      You can set those passwords for the two predefined users yourself.

      Just add a section to your json while creating the machine:

      You can use the username "admin" to connect via ssh or root/admin if you use the console on the GZ

      Behaviour changed
      in the later SmartOS versions all metadata keys that end in '_pw' need to go into 'internal_metadata':
      1. Nov 03, 2012

        xin

        Hi, Daniel

        As you mentioned, "username" and "password" can be added in the coustermer_metedata.

        Do you know any other keys can be added in the metedata field?

        Assuming I wanna install mysql in the vm, what should I do in the creatation stepps?

        thank you! 

      2. Feb 10, 2013

        it should be noted that "root" and "admin" are the only accounts this works with, and that this is specific to the zoneinit scripts in specific datasets.  You can't, for example, use: "ryan_pw": "secretstuff" ... that will not work.

  3. Mar 21, 2013

    I've did this little hack to make my ssh_key working for the root and admin account, add the following to your json file, it's not perfect, but it works.

    "customer_metadata" : {
       "root_authorized_keys" : " ssh-rsa lalalalbbalak x@whatever\nssh-rsa 98ydoiowiu y@blah",
       "user-script" : "/usr/sbin/mdata-get root_authorized_keys > ~root/.ssh/authorized_keys ; /usr/sbin/mdata-get root_authorized_keys > ~admin/.ssh/authorized_keys"
    }
    

    That's it

    1. Sep 16, 2013

      Sebastien, that is brilliant!  Thank you for sharing that.  Really cool.  That just saved me a lot of headaches.

  4. Sep 27, 2013

    How do I create a zone on a dedicated disk? I've 4 SATA disks, during setup, I specified the first disk and then used another one for dump. Created two VMs as well. Now I'd like each one of these VMs to have exclusive access to one disk each. How do I do that?

    Thanks.