Using the metadata API
The Metadata API is used to transfer data to a running infrastructure container or hardware virtual machine. Joyent-supplied images use the metadata to transfer the SSH keys stored in the Customers API to the customer's machine, to set and generate passwords, and to execute customized user scripts.
The Metadata API is a lightweight interface that lets your instance get data from its VMAPI record.
Setting the metadata
The metadata is JSON-formatted key/value data that resides on the compute node that hosts the instance. Each container and hardware VM 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 infrastructure containers, the Metadata API communicates with the compute node through a
zsocket. For hardware virtualized containers (HVM), 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
Accessing metadata from an instance
You can use the Metadata API from a instance 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 VM||Location of
List of metadata keys
The following is a list of some of the metadata keys that are available within an instance.
|user-script||User definable script data; Runs on first boot on HVM instances, runs on every boot for SmartOS instances.|
|user-data||User definable data; not executed but copied to machine on boot.|
|operator-script||Set by the provisioning system. This represents a program that must be executed on every boot, prior to running any user-script.|
|administrator-pw||Administrator's initial password (Windows only).|
To get information from one of these keys, use the
mdata-get command like this:
|VM Type||Command to Use|
To view more of the keys, read the metadata dictionary.
Each instance has a set of read-only keys. The names of these keys are prefixed with the string
The keys provide information about the host system and the instance. The names of these keys do not appear in the output of the
KEYS metadata operation or in the output of the
mdata-list command. They may be read with the
GET operation, but not modified with
It is possible that some of the keys will not be present (such as
||The unique identifying number associated with each instance|
||The unique identifying number associated with each SmartOS hypervisor|
||The unique identifying number associated with a Triton account, as seen in DNS names created with Triton CNS|
||Optionally assigned name for an instance for a user-friendly way of identifying deployed instances|
||String configured by cloud operator to represent the physical location of a particular data center|
||JSON array of associated NICs including configuration information and details, such as:
||Array of IPv4 and IPv6 addresses to use for name resolution|
||Hostname for the VM|
||Domain that should be searched when performing a host name lookup|
||Collection of static routes to add to the OS’s routing table|
How metadata is used in Joyent-Supplied images
On infrastructure containers, 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 infrastructure container 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 both Hardware Virtualized Linux (HVM) and Container Native Linux, Triton 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 instance owner. A startup script executes
/lib/smartdc/set-root-authorized-keys to copy the SSH keys to