How it works
provider panel: the "User data" / "Cloud-init" field
│ at server creation
▼
first boot: cloud-init reads the file → modules in order:
users, ssh, write_files, swap, package_update/upgrade, packages, runcmd, reboot
│
▼
/var/log/cloud-init-output.log — output of every command
cloud-init is in every Ubuntu cloud image. The file runs once, on first boot. Running it again takes
sudo cloud-init clean --reboot, which reapplies everything in the file.
Whether a provider supports user data, check its panel: the field is called “User data”, “Cloud-init” or “Startup script”. No field — set up by hand, following the set (A new Ubuntu server).
The file, block by block
#cloud-configThe first line is a required format marker. Without it cloud-init takes the file for a script or skips it.
hostname: web1
timezone: Europe/Berlin # your own zoneHostname and time zone, as in First login to a server. The time zone decides when “4:00” comes for the automatic reboot.
users:
- name: example-user
groups: [sudo]
shell: /bin/bash
lock_passwd: false
hashed_passwd: "$6$Qm…$…"
ssh_authorized_keys:
- ssh-ed25519 AAAAC3Nza… laptop-2026
- ssh-ed25519 AAAAC3Nza… desktop-2026Your own sudo user with two keys from different devices. The password is given as a hash: sudo and the provider console need it, but it won’t log you in over SSH. Make the hash on your computer with openssl passwd -6, so the password itself never lands in the file. lock_passwd: false — the password isn’t locked.
default:lock_passwd trueshell /bin/sh
ssh_pwauth: false
disable_root: truessh_pwauth: false — cloud-init writes PasswordAuthentication no into its own 50-cloud-init.conf. disable_root: true — root’s keys are replaced with a hint to log in as example-user. No root password is set at all.
default:ssh_pwauth as in the provider’s imagedisable_root true
write_files:
- path: /etc/ssh/sshd_config.d/00-hardening.conf
content: |
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
PermitRootLogin no
AllowUsers example-user
MaxAuthTries 3
LoginGraceTime 30
X11Forwarding no
AllowAgentForwarding no
ClientAliveInterval 300
ClientAliveCountMax 2Your own sshd file — the same as in sshd_config. write_files runs before packages and runcmd, so the settings are in place by the first reboot.
- path: /etc/apt/apt.conf.d/52unattended-upgrades-local
content: |
Unattended-Upgrade::Automatic-Reboot "true";
Unattended-Upgrade::Automatic-Reboot-Time "04:00";
Unattended-Upgrade::Automatic-Reboot-WithUsers "true";
Unattended-Upgrade::Remove-Unused-Kernel-Packages "true";
Unattended-Upgrade::Remove-New-Unused-Dependencies "true";
Unattended-Upgrade::Remove-Unused-Dependencies "true";
Unattended-Upgrade::AutoFixInterruptedDpkg "true";
- path: /etc/systemd/journald.conf.d/00-size.conf
content: |
[Journal]
SystemMaxUse=500M
SystemKeepFree=1G
- path: /etc/sysctl.d/99-swappiness.conf
content: |
vm.swappiness=10Auto-updates with reboots (unattended-upgrades), the journal limit and swappiness (Swap, journal and time) — as files too.
swap:
filename: /swapfile
size: 2GSwap via the built-in module: it creates the file, sets permissions and writes the /etc/fstab line.
package_update: true
package_upgrade: true
package_reboot_if_required: true
packages:
- ncdu
- htopUpdates at creation and a reboot if the kernel changed. Packages — what comes in handy in the first hour: ncdu for disk, htop for memory.
default:package_update falsepackage_upgrade false
runcmd:
- ufw default deny incoming
- ufw default allow outgoing
- ufw allow OpenSSH
- ufw allow 80,443/tcp
- ufw --force enable
- sysctl --system
- systemctl restart sshThe firewall, as in The ufw firewall: the SSH rule before enable. --force skips the y/n prompt. The last line restarts sshd so it reads our file.
- curl -fsSL https://get.docker.com | shDocker and CrowdSec could go here as runcmd commands too, but an error in them only shows in the log. While there are few steps, do them by hand after the first login (Docker on Ubuntu, CrowdSec against SSH brute force).
What’s not here
| What | Why |
|---|---|
a plain-text password (passwd, chpasswd) |
user data is stored at the provider, and any process on the server can read it from the metadata address 169.254.169.254 |
| API keys, tokens | same reason: put secrets on the server after creation (Secrets in Docker stacks) |
| settings that will change | the file runs once; live configs belong in git (Server configs in git) |
If it doesn’t work
The server was created, but nothing from the file was applied
- Cause
- The first line isn’t
#cloud-config— without it the file isn’t treated as a config. Or a YAML error: cloud-init skips the whole file. - Fix
- On the server:
sudo cloud-init schema --system --annotateshows the error with its line; the log is/var/log/cloud-init.log.
Logging in as example-user works, but sudo asks for a password that doesn’t exist
- Cause
- The user has
lock_passwd: trueand nohashed_passwd: there’s no password, andsudorequires one. - Fix
- Set
hashed_passwd(a hash fromopenssl passwd -6) andlock_passwd: false— or runpasswd example-useras root through the provider console.
One runcmd command failed, the rest worked
- Cause
runcmddoesn’t stop on errors: each line runs on its own.- Fix
- Look at
/var/log/cloud-init-output.log— it has every command’s output in order; run the fixed command by hand.
A minute after creation SSH lets nobody in
- Cause
- cloud-init is still working: installing updates and rebooting the server (
package_reboot_if_required). - Fix
- Wait 3–5 minutes. Check the status with
cloud-init status --waitthrough the provider console.
How to check
3–5 minutes after creation, from your computer:
ssh [email protected] 'cloud-init status --long'
# status: done
# extended_status: done
# boot_status_code: enabled-by-generator
# detail: DataSourceNoCloud …
# errors: []
errors: [] means every module finished. Then check from outside, also from your computer:
# open — only 22; 80 and 443 are closed: ufw lets them through, but nothing listens on them yet;
# every other port is filtered
nmap -Pn --top-ports 1000 203.0.113.10
# root is refused
ssh [email protected]
# [email protected]: Permission denied (publickey).
# swap is on, the journal has a limit, the clock is synced
ssh [email protected] 'swapon --show; journalctl --disk-usage; timedatectl show -p NTPSynchronized --value'