How to supply a script or #cloud-config that runs on first boot when you order or reinstall a cloud server: formats, examples, limits and how to check the result.
Contents
User data is a script that the server runs once, on its first boot after the operating system has been installed. You can use it to install packages, create users, place configuration files and do the initial set-up of services — without logging in to the server. The script is processed by cloud-init, the standard mechanism for initial configuration of cloud servers.
Where to set User data
- When ordering a cloud server — in the order form, under “Additional settings”, using the “User data” toggle.
- When reinstalling the operating system — in your control panel: server page → Operating system tab → Reinstall, using the “User data” toggle.
You can paste the text into the field or upload it as a file: .txt, .sh, .yaml, .yml, .cfg or a MIME archive. A gzip-compressed file (.gz) is unpacked in your browser — only the text is sent to the server.
Formats
| First line | Format | Purpose |
|---|---|---|
#!/bin/bash | Script | Shell commands, run as root. Any interpreter installed on the system will do: #!/bin/sh, #!/usr/bin/env python3. |
#cloud-config | cloud-init configuration (YAML) | Packages, users, files and commands — described rather than scripted. |
Content-Type: multipart/mixed | MIME archive | Several parts of different formats in one document. |
#include | List of URLs | The parts are downloaded from the given links; the server must be able to reach them. |
Also recognised are #cloud-boothook, #part-handler and ## template: jinja templates — for experienced cloud-init users.
Limits
- The size must not exceed 32 KB of text.
- The script runs once — on the first boot after installation. It is not repeated on reboot; when you reinstall the system, the script you set during the reinstall is run.
- The settings that we apply — the root password, SSH keys, server name and network — are applied first and cannot be overridden: #cloud-config is merged with them (lists are extended), and a script runs after our commands.
- An error in the script does not cancel the installation: the server will still be created, but the User data configuration may be left unfinished.
Examples
Install and start nginx (Ubuntu, Debian)
#!/bin/bash
apt-get update
apt-get install -y nginx
systemctl enable --now nginxFor AlmaLinux, use dnf install -y nginx in place of the two apt-get commands.
Packages, a user and a file (#cloud-config)
#cloud-config
package_update: true
packages:
- git
- htop
users:
- name: deploy
groups: sudo
shell: /bin/bash
sudo: ALL=(ALL) NOPASSWD:ALL
ssh_authorized_keys:
- ssh-ed25519 AAAA… deploy@example
write_files:
- path: /etc/motd
content: |
Server for the Daisy project
runcmd:
- echo "Setup complete" >> /var/log/first-boot.logThe sudo line gives the user administrator rights without a password — include it only if you need it. On AlmaLinux the administrators’ group is called wheel, not sudo.
How to check the result
Connect to the server over SSH and run:
cloud-init status --long— the status:done— the script has run,error— it ran with errors./var/log/cloud-init-output.log— the output of scripts and commands./var/log/cloud-init.log— the detailed cloud-init log.sudo cloud-init query userdata— the document the server received.
Security
The script runs with root rights on your server. Use only scripts you trust, and download files and parts from links (#include, curl in a script) only from trusted sources.
It is best not to put passwords or access keys for third-party systems in User data: after installation the document remains in cloud-init’s working files on the server (the /var/lib/cloud/instance/ directory). On our side, User data is stored encrypted until the system has been installed and is deleted afterwards.
See also
Didn’t find the answer? Ask our support team — we’ll help.