Skip to main content
> Equinix Deploy

User Data

When provisioning a server on Equinix Metal™ you have the option to include User Data, which can be used to perform various automation tasks after the server is ready, such as executing common scripts, installing packages, or triggering other more advanced configuration processes.

Usage

Equinix Metal user data is based on open-source project cloudbase-init and officially supports two user data formats.

User Data Scripts

Scripts are for executing shell scripts and begin with #! for Linux shell or #ps1 for Windows Powershell.

#!/bin/bash
export DEBIAN_FRONTEND=noninteractive
apt-get update && apt-get upgrade -y
apt-get install nginx -y

#ps1
New-Item C:/Users/Admin test.txt
Set-Content C:/Users/Admin/test.txt "Hello world"

$password = ConvertTo-SecureString "P@55w0rd!" -AsPlainText -Force
New-LocalUser -Name "user01" -Password $password

Cloud Config Data

Cloud Config data must use valid yaml syntax and begins with #cloud-config

#cloud-config
package_upgrade: true
packages:
    -  nginx

Info

Support for formats other than #!<script> and #cloud-config are experimental.

Provisioning with User Data

When provisioning a server from the Metal console, add User Data by expanding the Optional Settings > User data tab.

Example User Data Field when Provisioning

Paste your script into the field. Click Deploy Now. The script is read and executed during the server provisioning process.

When provisioning a server from the CLI, use the metal device create command and include your user data script with -u, --userdata or include a path to a file that contains your user data script on your local machine with --userdata-file.

metal device create --project-id <project_UUID> --plan <server_type> --metro <metro_code> --operating-system <os_code> --userdata-file <local_file_path>

When provisioning in the API, send a POST request to the projects/{id}/devices endpoint and include your user data script with the "userdata" parameter in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
    "metro": "<metro_code>",
    "plan": "<server_type>",
    "operating_system": "<os_code>"
    "userdata": <string>
}'

Note

Depending on the length of your script, allow some time for the server provisioning process to execute after you see the server as "Active."

Managing User Data

A server's user data is available in the server's Settings tab, under User Data.

Example User Data field for a Server

To retrieve a server's user data from the CLI, use the metal device get command, specifying with the -o, --output flag to retrieve the full json output, which will include the user data in the "userdata" field.

metal device get -i <device_id> -o json

To retrieve a server's user data from the API, send a GET request to the /devices/{id}/userdata endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/devices/{id}/userdata

Info

You can also access the user data from the server from its metadata endpoint. SSH into the server and send a request to https://metadata.platformequinix.com/userdata.

Verifying User Data on the Server

To verify the user data stored on your server, check for it at /var/lib/cloud/instance/user-data.txt.

The server logs for user data are available at /var/log/cloud-init.log and /var/log/cloud-init-output.log

Adding User Data Post-Provisioning

During provisioning, user data is executed on a server's first bootup. You can add user data to an already provisioned server, but you must reinstall the server first to execute the new user data.

Caution

Reinstalling is a disruptive operation and has options that include deleting data. Proceed with caution.

Update the user data field in the server's Settings tab, under User Data.

Example User Data field for a Server

Click Save. The new user data will be written to the server and appear in the server's metadata immediately, but will not be executed until you preform a server Reinstall.

To update user data, use the metal device update command and include your updated user data script with -u, --userdata or include a path to a file that contains your updated user data script on your local machine with --userdata-file.

metal device update --project-id <project_UUID> --plan <server_type> --metro <metro_code> --operating-system <os_code> --userdata-file <local_file_path>

The new user data will be written to the server and appear in the server's metadata immediately, but will not be executed until you preform a server Reinstall.

When provisioning in the API, send a PUT request to the projects/{id}/devices endpoint and include your updated user data script with the "userdata" parameter in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
    "userdata": <string>
}'

The new user data will be written to the server and appear in the server's metadata immediately, but will not be executed until you preform a server Reinstall.

Copied code to clipboard