User data on a dedicated server

User data are user-defined operating system configuration parameters for a server. They are described as scripts in cloud-config format (text files with YAML syntax) or as a bash script. The scripts are automatically encoded in Base64, transferred to the server, and executed by the cloud-init agent upon the first OS boot. Using user data helps automate server configuration.

You can specify user data during operating system installation.

Learn more about cloud-config and bash script formats in the User data formats guide in cloud-init documentation.

Scripts can be used to pass individual operating system configuration parameters or entire sequences of parameters. For example:

• set the time zone;
• create a directory and upload files to it;
• update repositories and install packages;
• place an SSH key on the server;
• configure the resolv.conf DNS resolver configuration file.

See other examples in the Cloud config examples guide in cloud-init documentation.

Specify user data

You can specify user data only during Linux-based OS auto-installation. Enter the script text in the User data field.

After automatic installation is complete, the text in the User data field cannot be changed.

The maximum size of a script containing data not encoded in Base64 is 16 KB.

User data examples

Set the time zone

Cloud-config

Example script to set the Europe/Moscow time zone:

#cloud-config

timezone: Europe/Moscow

Bash script

Example script to set the Europe/Moscow time zone:

#!/bin/bash

timedatectl set-timezone Europe/Moscow

Create a directory and upload files to it

Cloud-config

Example script to create a directory and upload a file to it over the network:

#cloud-config

runcmd:
- mkdir <directory>
- [ wget, "<url>", -O, <directory>/<file_name> ]

Specify:

• <directory> — directory on the server, for example, /run/newdir;
• <url> — URL to the file, for example, https://repo.local/static/page.html;
• <file_name> — file name under which the uploaded file will be saved in the directory, for example, index.html.

Bash script

Example script to create a directory and upload a file to it over the network:

#!/bin/bash
mkdir <directory>
wget <url> -O <directory>/<file_name>

Specify:

• <directory> — directory on the server, for example, /run/newdir;
• <url> — URL to the file, for example, https://repo.local/static/page.html;
• <file_name> — file name under which the uploaded file will be saved in the directory, for example, index.html.

Update repositories and install packages

Cloud-config

Example script for installing packages:

• pwgen — utility for generating random passwords;
• pastebinit — command-line tool for publishing texts, such as command output, logs, etc., from the terminal to online services.

#cloud-config

package_update: true
packages:
- pwgen
- pastebinit

Bash script

Example script for installing packages:

• pwgen — utility for generating random passwords;
• pastebinit — command-line tool for publishing texts from the terminal, such as command output, logs, etc., to online services.

#!/bin/bash
apt update
apt install pwgen pastebinit

Place an SSH key on the server

Cloud-config

Example script for placing two SSH keys on the server. The key will be added to the OS user, which by default is root, to the directory ~/.ssh/authorized_keys.

#cloud-config

ssh_authorized_keys:
 - ssh-rsa <ssh_key_user_1> <user_name_1>@<host_name_1>
 - ssh-rsa <ssh_key_user_2> <user_name_2>@<host_name_2>

Specify:

• <ssh_key_user_1> — public SSH key of the first user, for example, AAAAB3N…V7NZ;
• <user_name_1>@<host_name_1> — comment for the first user's SSH key, where:
  • <user_name_1> — name of the first user who generated the SSH key;
  • <host_name_1> — name of the device on which the SSH key was generated;
• <ssh_key_user_2> — public SSH key of the second user, for example, AAAAB3N…NtHw==;
• <user_name_2>@<host_name_2> — comment for the second user's SSH key, where:
  • <user_name_2> — name of the second user who generated the SSH key;
  • <host_name_2> — name of the device on which the SSH key was generated.

Bash script

Example script for placing two SSH keys on the server. The key will be added to the OS user, which by default is root, to the directory ~/.ssh/authorized_keys.

#!/bin/bash
echo "ssh-rsa <ssh_key_user_1> <user_name_1>@<host_name_1>" >> /root/.ssh/authorized_keys
echo "ssh-rsa <ssh_key_user_2> <user_name_2>@<host_name_2>" >> /root/.ssh/authorized_keys

Specify:

• <ssh_key_user_1> — public SSH key of the first user, for example, AAAAB3N…V7NZ;
• <user_name_1>@<host_name_1> — comment for the first user's SSH key, where:
  • <user_name_1> — name of the first user who generated the SSH key;
  • <host_name_1> — name of the device on which the SSH key was generated;
• <ssh_key_user_2> — public SSH key of the second user, for example, AAAAB3N…NtHw==;
• <user_name_2>@<host_name_2> — comment for the second user's SSH key, where:
  • <user_name_2> — name of the second user who generated the SSH key;
  • <host_name_2> — name of the device on which the SSH key was generated.

Configure the configuration file

Cloud-config

Example script for the resolv.conf DNS resolver:

#cloud-config

manage_resolv_conf: true
resolv_conf:
 nameservers: ['<dns_server_ip_address_1>', '<dns_server_ip_address_2>']
 searchdomains:
   - <searchdomain_1>
   - <searchdomain_2>
 domain: <domain>
 options:
   rotate: true
   timeout: 1

Specify:

• <dns_server_ip_address_1>, <dns_server_ip_address_2> — IP addresses of DNS servers that the system will query to resolve domain names, for example, 4.4.4.4 and 8.8.8.8;
• <searchdomain_1>, <searchdomain_2> — domains that will be appended to short (unqualified) hostnames when querying them;
• <domain> — (legacy) main DNS domain that will be appended to short (unqualified) hostnames when querying them.

Bash script

Example script for the resolv.conf DNS resolver:

#!/bin/bash
cat <<EOF > /etc/resolv.conf
domain <domain>
nameserver <dns_server_ip_address_1>
nameserver <dns_server_ip_address_2>
search <searchdomain_1> <searchdomain_2>
options rotate
options timeout:1
EOF

Specify:

• <domain> — (legacy) main DNS domain that will be appended to short (unqualified) hostnames when querying them;
• <dns_server_ip_address_1>, <dns_server_ip_address_2> — IP addresses of DNS servers that the system will query to resolve domain names, for example, 4.4.4.4 and 8.8.8.8;
• <searchdomain_1>, <searchdomain_2> — domains that will be appended to short (unqualified) hostnames when querying them.

Disable internet access

Bash script

Example script to turn off a network interface with a public IPv4 address:

#!/bin/bash
ip addr show
public_interface=$(ip -4 addr show | awk '/inet/ && !/127.0.0.1/ && !/10\./ && !/172\.(1[6-9]|2[0-9]|3[0-1])\./ && !/192\.168\./ {print $NF}')
if [ -n "$public_interface" ]; then
    ip link set down dev "$public_interface"
else
    echo "Public interface not found."
fi

Python script

Example script to turn off a network interface with a public IPv4 address:

#!/usr/bin/env python3
import subprocess
import re
import logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
def disable_public_interface():
    logging.info('Starting disable_public_interface function.')
    output = subprocess.check_output('ip -4 addr show', shell=True).decode('utf-8')
    interfaces = re.findall(r'^\d+: (\S+):.*?\n(?:.*\n)*?\s+inet (\d+\.\d+\.\d+\.\d+)/\d+', output, re.MULTILINE)
    public_interfaces = []
    for iface, ip in interfaces:
        if iface == 'lo':
            continue
        if re.match(r'^(127\.|10\.|172\.(1[6-9]|2[0-9]|3[0-1])\.|192\.168\.)', ip):
            continue
        public_interfaces.append(iface)
    for interface in public_interfaces:
        command = ['ip', 'link', 'set', 'dev', interface, 'down']
        try:
            subprocess.run(command, check=True)
            logging.info(f'Successfully disabled interface: {interface}')
        except subprocess.CalledProcessError as e:
            logging.error(f'Failed to disable interface: {interface}, error: {e}')
if __name__ == "__main__":
    logging.info('Script started.')
    disable_public_interface()
    logging.info('Script finished.')

Configure container configurations for installing an OS with the Containers Ready application

When installing the OS with the Containers Ready app, you can configure containers using a script in the User data field. To access the Portainer panel via a domain, paste the script into the User data field:

#cloud-config

write_files:
  - path: "/opt/containers/docker-compose.yaml"
    permissions: "0644"
    content: |
      version: "3.9"
      services:
        <containers>

  - path: "/opt/containers/.env"
    permissions: "0644"
    content: |
      <environment_variables>

  - path: "/opt/user-values.yaml"
    permissions: "0644"
    content: |
      portainer_use_le: true
      portainer_domain: "<example.com>"
      portainer_le_email: "<root@example.com>"

Specify:

• <containers> — Docker Compose file contents for the docker-compose.yaml file. Learn more in the docker compose guide in Docker documentation;

• <environment_variables> — environment variables for the .env file. If the file is not needed, delete the code block. Learn more in the Use environment variables guide in Docker documentation;

• in the content code block for the /opt/user-values.yaml file, specify the configuration parameters for Portainer:

  • portainer_use_le: true — parameter for automatically issuing a TLS(SSL) certificate from Let’s Encrypt®;
  • <example.com> — domain for accessing Portainer. To open the domain using the server's public IP address, add an A record in the control panel of your DNS hosting provider and specify the server's public IP address as the record value. You can copy the IP address in the control panel: in the top menu, click Products → Dedicated Servers → server page → Operating system tab → in the IP field, click . If the domain is delegated to Servercore DNS hosting, use the Add resource record instructions. After the OS is installed, a TLS(SSL) certificate from Let’s Encrypt® will be automatically issued for the domain. If an error occurs when issuing the TLS(SSL) certificate, the Portainer panel will be available at the server IP address;
  • <root@example.com> — Containers Ready administrator email for creating an account and receiving Let’s Encrypt® notifications.