User data

User data are scripts that use the cloud-config format, designed to be run by the cloud-init process. These scripts are generally used for the initial configuration of a server and run on the first boot.

Put simply, deploying a server with a user data allows you to run arbitrary commands and change several aspects of the server during provisioning.

Here are a few examples of what you can do with user data scripts:

  • Change user passwords
  • Server hardening
  • Notify people or systems that a new device has been deployed
  • Install packages and dependencies

File format

UNIX-like systems

If you're using a UNIX-like OS like Linux, your scripts must be written using the YAML file format, which uses whitespace and new-lines to delimit lists, associative arrays, and values.

These files are generally fairly intuitive and easy to understand, but there are a few things you need to keep in mind when using them. Here is a good getting started guide that can help.

📘

Always validate your YAML code. Google 'YAML validator' if you don't have a linter on your IDE, but remember never to add sensitive data to these services.

Windows systems

For Windows, you'll have to use the cloud-baseinit convention. This is just a fancy way of saying that your user data will have to be written as if you were using Powershell. Here's a straightforward example:

mkdir c:/test
New-Item c:/test/test.txt
Set-Content c:/test/test.txt 'Hello World'

Adding a user data

  1. Go to Project Settings > User data
  2. The name of your script needs to be preceded by a number and a dash. We use this to define the order of the scripts that you select. For instance, a script named 01-Script will run before 02-Script because 01 takes execution precedence over 02.
  3. Click on add and proceed with deploying your server.

Variables

To make development easier, we provide variables that can be used on your user data script so you can access data that is only available during or right after a deployment.

Variables are wrapped in double curly brackets ({{ VAR }}). Here are the available variables that can be used by any user data script.

Variable

Value

{{ HOSTNAME }}

The normalized hostname.

{{ PASSWORD }}

Root password of the deployed server.

{{ USER_DISTRO }}

Distro name. Examples: ubuntu, centos, windows.

{{ MAC_ADDRESS }}

MAC Address.

{{ WAN_IP }}

WAN IP address.

{{ SSH_KEYS }}

An array of the SSH keys you chose to deploy your server with, if any.

Examples

Here's an example of a user data script that uses the {{ PASSWORD }} variable to change the root password and allow for root logins.

#cloud-config
user: root
chpasswd: {expire: false}
password: {{ PASSWORD }}
disable_root: false
ssh_pwauth: true
runcmd:
- echo "PermitRootLogin yes" >> /etc/ssh/sshd_config
- systemctl restart ssh

You can find more great examples on cloud-init's docs.


Did this page help you?