Using the Metadata API

Modified: 02 Dec 2015 17:02 UTC

The Metadata API is used to transfer data from SmartDataCenter to a SmartMachine or Virtual Machine. Joyent-supplied images use the metadata to transfer the SSH keys stored in the Customers API to the customer's machine, setting and generating passwords, and executing a custom user script.

In this page:

At a Glance

The Metadata API is a lightweight interface that lets your machine get data from its SmartDataCenter record.

Setting the Metadata

The metadata is JSON-formatted key/value data that resides on the compute node that hosts the SmartMachine or Virtual Machine. Each machine has its own Metadata store.

You can set the metadata through the Operations Portal or through CloudAPI. You can set the metadata before provisioning a machine, or you can change the metadata after provisioning.

The Metadata API does not rely on networking. On SmartMachines, the Metadata API communicates with the compute node through a zsocket. On Virtual Machines, the Metadata API uses the second serial port available on the machine. For Linux machines, this is typically /dev/ttys1. For Windows machines this is COM2.

Accessing Metadata from a Machine

You can use the Metadata API from a machine with the mdata-get command. This command line tool has a simple syntax: it takes a keyname and returns the value associated with the key.

$ mdata-get <keyname>
Type of machine Location of the mdata-get command
SmartMachine /usr/sbin/mdata-get
Virtual Machine running a Unix-like OS /lib/smartdc/mdata-get
Virtual Machine running Windows C:\smartdc\bin\mdata-get

List of Metadata Keys

The following is a list of metadata keys that are available within a machine.

Key Description
user-script user-definable script data
Runs on first boot on Virtual Machines. Runs on every boot on SmartMachines.
user-data user-definable data
not executed but copied to machine on boot
administrator-pw Administrator's initial password (Windows only)

To get information from one of these keys, use the mdata-get command like this:

Type of machine Use this command
SmartMachine /usr/sbin/mdata-get <keyname>
Virtual Machine running a Unix-like OS /lib/smartdc/mdata-get <keyname>
Virtual Machine running Windows C:\smartdc\bin\mdata-get <keyname>

How Metadata is Used in Joyent-Supplied Images

On SmartMachines the mdata:fetch SMF service runs at boot time to fetch the user-script. Another SMF service, mdata:execute, executes the contents of user-script if it was not empty. Other SmartMachine images may use additional key/value pairs such as credentials for third party software, passwords, user data, etc. The output to stdout from the user-script is captured in the mdata:execute service. You can find this log by using the following command:

headnode# svcs -L mdata:execute

On Virtual Machines, SmartDataCenter creates an entry in the metadata with the key root_authorized_keys. The value of this entry is the set of public SSH keys listed in the CAPI record for the Virtual Machine owner. A startup script (on Ubutnu it's /etc/rc.local) executes /lib/smartdc/set-root-authorized-keys to copy the SSH keys to /root/.ssh/authorized_keys.

Using Metadata in Your Custom Images

If you create your own images, you will probably want to use the Metadata API to set the root account's SSH keys. The scripts and tools to set this up are part of the SDC Guest Tools.

  1. Get the SDC Guest Tools for Linux and Windows from
    You can download either a tarball or an ISO image. Be sure to get the latest version of the tools.
  2. Run the installation script.
    Operating System Installation Script Installation Directory
    Linux /linux/ /lib/smartdc
    Windows /windows/install.bat C:\smartdc

The installation scripts install the commands, drivers, and startup scripts appropriate for the operating system.