Using the metadata API

Modified: 26 Sep 2019 21:20 UTC

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 COM2.

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 mdata-get Command
SmartOS /usr/sbin/mdata-get
Linux/Unix /lib/smartdc/mdata-get
Windows C:\smartdc\bin\mdata-get

List of metadata keys

The following is a list of some of the metadata keys that are available within an instance.

Key Description
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
SmartOS Based /usr/sbin/mdata-get <keyname>
Unix-like OS /lib/smartdc/mdata-get <keyname>
Windows C:\smartdc\bin\mdata-get <keyname>

To view more of the keys, read the metadata dictionary.

Read-only metadata

Each instance has a set of read-only keys. The names of these keys are prefixed with the string sdc:.

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 PUT or DELETE.

It is possible that some of the keys will not be present (such as sdc:dns_domain or sdc:hostname).

Key Description
sdc:image_uuid, sdc:uuid The unique identifying number associated with each instance
sdc:server_uuid The unique identifying number associated with each SmartOS hypervisor
sdc:owner_uuid The unique identifying number associated with a Triton account, as seen in DNS names created with Triton CNS
sdc:alias Optionally assigned name for an instance for a user-friendly way of identifying deployed instances
sdc:datacenter_name String configured by cloud operator to represent the physical location of a particular data center
sdc:nics JSON array of associated NICs including configuration information and details, such as: mac, ips, mtu, primary, and gateways
sdc:resolvers Array of IPv4 and IPv6 addresses to use for name resolution
sdc:hostname Hostname for the VM
sdc:dns_domain Domain that should be searched when performing a host name lookup
sdc:routes 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 /root/.ssh/authorized_keys.