Using the Metadata API
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:
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.
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.
|Type of machine||Location of the mdata-get command|
|Virtual Machine running a Unix-like OS||/lib/smartdc/mdata-get|
|Virtual Machine running Windows||C:\smartdc\bin\mdata-get|
The following is a list of metadata keys that are available within a machine.
|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|
|Virtual Machine running a Unix-like OS||/lib/smartdc/mdata-get <keyname>|
|Virtual Machine running Windows||C:\smartdc\bin\mdata-get <keyname>|
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:
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.
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.
- Get the SDC Guest Tools for Linux and Windows from https://download.joyent.com/pub/vmtools/.
You can download either a tarball or an ISO image. Be sure to get the latest version of the tools.
- Run the installation script.
Operating System Installation Script Installation Directory Linux /linux/install-tools.sh /lib/smartdc Windows /windows/install.bat C:\smartdc
The installation scripts install the commands, drivers, and startup scripts appropriate for the operating system.