You can add and assign scripts to your Vultr cloud server instances in the Customer Portal or through the Vultr API. This guide explains the different types of scripts available at Vultr and how to use them.
Vultr uses two main categories of scripts: Startup and iPXE.
Boot scripts are standard shell scripts executed by your server instance. The server's operating system determines where the script is stored, what script interpreter is used, and where the log output is saved.
/tmp/firstboot.exec
./bin/sh
as the root user./tmp/firstboot.log
.C:\image\firstboot.cmd
.cmd.exe
as the Administrator.C:\image\firstboot.log
Boot scripts use a two-step process. First, you add a script to your account, then assign that script to an instance. You can add a script to your account through the customer portal:
You can also add a script to your account through the Vultr API with the create-startup-script
endpoint.
After adding the boot script, you can assign the script when you deploy a new instance through the customer portal. Choose your script from the list, or if you need to add a new script, use the Manage link or the Add New button.
You can also assign a script to a new instance with the Vultr API by passing the script_id
to the create-instance
endpoint.
Boot scripts may query the Vultr Metadata API to discover information about the instance. This example script logs the server's metadata to /tmp/metadata.json
during the first boot.
#/bin/sh
curl -o /tmp/metadata.json http://169.254.169.254/v1.json
This could be useful if you parse the JSON metadata with tools such as jq, Python, sed, awk, or grep. For example, you could use the metadata to discover your IP address and generate configuration files automatically on the first boot.
This example installs a public key for SSH authentication. Replace "ssh-rsa AA... youremail@example.com" with your SSH public key.
#!/bin/sh
mkdir -p /root/.ssh
chmod 700 /root/.ssh
echo ssh-rsa AA... youremail@example.com > /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys
Other common uses for boot scripts are installing software, running updates, and adding users. It's possible to fully configure a system with boot scripts with a little creativity.
Cloud-init is an open-source project compatible with most Linux distributions. Cloud-init is designed to handle the early initialization of a cloud instance and uses user-data to describe the cloud instance's configuration settings. When cloud-init detects user data, it applies the settings to the cloud instance.
User-data is used for many purposes, and you can supply user-data in several formats, as described in the cloud-init documentation. One popular format is the user-data script. A user-data script is typically used by those who just want to execute a shell script.
⚠️ A user-data script MUST begin with a valid shebang like
#!/bin/sh
or similar.
User-data scripts do not support escape sequences such as\t
(tab),\n
(newline),\r
(carriage return), etc.
User-data scripts run as the final step during cloud-init's first boot, using the interpreter declared in the script's shebang. As a result, scripts may take several minutes to begin running, depending on the number of updates and other tasks cloud-init must perform first.
When you deploy a new instance that supports cloud-init through the customer portal, you can add user-data in the Additional Features section.
⚠️ Use plain text user-data in the Customer Portal
For example, a simple script to drop a test file in the /root
home directory would look like this:
Cloud-init systems log their script output to /var/log/cloud-init-output.log
You can use vultr-cli
to get and set instance user-data.
⚠️ Use plain text user-data with vultr-cli.
For example:
$ vultr-cli instance user-data
Usage:
vultr-cli instance user-data [command]
Available Commands:
get Get the user-data of an instance
set Set the plain text user-data of an instance
Flags:
-h, --help help for user-data
You'll find more information about vultr-cli on GitHub.
You can also set and get user-data with the Vultr API.
⚠️ Use base-64 encoded user-data with the Vultr API
User-data supplied to the API must be base-64 encoded. For example, consider this user-data script:
#!/bin/sh
echo "Hello World" > /root/hello-world.txt
That script in base-64 is:
IyEvYmluL3NoCmVjaG8gIkhlbGxvIFdvcmxkIiA+IC9yb290L2hlbGxvLXdvcmxkLnR4dA==
The payload with user-data supplied to the create-instance
endpoint looks like this:
{
"region": "ewr",
"plan": "vc2-6c-16gb",
"label": "Example Instance",
"os_id": 215,
"user_data": "IyEvYmluL3NoCmVjaG8gIkhlbGxvIFdvcmxkIiA+IC9yb290L2hlbGxvLXdvcmxkLnR4dA==",
"backups": "enabled",
"hostname": "my_hostname"
}
To retrieve user data, use the Vultr API endpoint:
https://api.vultr.com/v2/instances/{instance-id}/user-data
You can also use the Metadata API /latest/user-data
endpoint to retrieve the user-data from the running instance.
# curl http://169.254.169.254/latest/user-data
The /latest/user-data
Metadata endpoint is cached. If you update a running instance, this endpoint will old values until the instance is rebooted or reinstalled.
Ignition startup requires a YAML formatted .ign
file. See our Ignition user guide and the Fedora CoreOS documentation to learn more about Ignition.
An iPXE script automates the installation of a custom operating system. An iPXE script is executed by iPXE each time the server starts if no operating system is installed on the server's disk. After an operating system is installed, iPXE scripts do not run.
See the article iPXE Boot Feature for more information.
This is an example that boots CoreOS. You need to add your SSH key before this will work.
#!ipxe
set base-url http://stable.release.core-os.net/amd64-usr/current
kernel ${base-url}/coreos_production_pxe.vmlinuz sshkey="ssh-rsa AAAA..." cloud-config-url=http://169.254.169.254/2014-09-12/coreos-init
initrd ${base-url}/coreos_production_pxe_image.cpio.gz
boot