Vultr Startup Scripts Quickstart Guide

<?xml encoding="utf-8" ??>

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.

Script Types

Vultr uses two main categories of scripts: Startup and iPXE.

• iPXE scripts automatically install operating systems.

• Startup scripts execute on your server the first time it starts. They do not run on later reboots. Server instances at Vultr use one of three startup methods, depending on the operating system: Boot scripts, cloud-init, and Ignition.

  • Windows and *BSD systems use Boot scripts.
  • Linux system use cloud-init.
  • Fedora CoreOS uses Ignition.

Boot Scripts

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.

Boot Scripts on *BSD

• The script is saved to /tmp/firstboot.exec.
• It is executed with /bin/sh as the root user.
• The output is saved to /tmp/firstboot.log.

Boot Scripts on Windows

• The script is saved to C:\image\firstboot.cmd.
• It is executed with cmd.exe as the Administrator.
• The output is saved to C:\image\firstboot.log

How to Add a Boot Script to Your Account

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:

1. Navigate to the Add Startup Script page.
2. Choose a name for your script.
3. Select Boot for the type.
4. Replace the example with your script.
5. Click Add Script.

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.

Linux Boot Script Example: Query Instance Metadata

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.

Linux Boot Script Example: Pre-Load SSH Public Key

This example installs a public key for SSH authentication. Replace "ssh-rsa AA... [email protected]" with your SSH public key.

#!/bin/sh

mkdir -p /root/.ssh
chmod 700 /root/.ssh
echo ssh-rsa AA... [email protected] > /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 Scripts

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.

How to use Cloud-init User-data in the Customer Portal

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

• To set user data on a new deployment, include user-data in the call to create-instance.
• To update user data, use the update-instance endpoint.

How to use Cloud-init User-data with Vultr-CLI

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.

How to use Cloud-init User-data with the Vultr API

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"

    }

Retrieve User Data with Vultr API

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 Scripts

Ignition startup requires a YAML formatted .ign file. See our Ignition user guide and the Fedora CoreOS documentation to learn more about Ignition.

iPXE Scripts

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.

Requirements

• Must be a valid iPXE script.
• You can select an iPXE script when deploying an instance under the Upload ISO option on the deploy page.

See the article iPXE Boot Feature for more information.

iPXE Script Example: Boot CoreOS

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

More Information

• The Vultr API offers several endpoints to manage boot scripts.

  • Create a new startup script.
  • Get information for a startup script.
  • List all startup scripts.
  • Update a startup script.
  • Delete a startup script.
• See the cloud-init documentation for more details about user-data.
• See the Vultr's Ignition documentation and the Fedora CoreOS documentation to learn more about Ignition.