Using the metadata API
The Metadata API is used to transfer data to a running infrastructure container or hardware virtual machine. MNX-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 Triton-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:executeOn 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.
