User data on a dedicated server

User data is user-defined server operating system configuration parameters. 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 using the cloud-init agent during the first operating system boot. Using user data helps automate server configuration.

Specify user data during the operating system installation.

For more information about cloud-config and bash script formats, see the User data formats guide in the 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 domain name resolver configuration file resolv.conf.

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

Specify user data

You can specify user data only during OS autoinstallation based on Linux. The script text is entered in the User data field.

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

Update repositories and install packages

Cloud-config

Example script for installing packages:

• pwgen — a utility for generating random passwords;
• pastebinit — a command-line tool for publishing text (such as command outputs, logs, etc.) to online services from the terminal.

#cloud-config

package_update: true
packages:
- pwgen
- pastebinit

Bash script

Example script for installing packages:

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

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

Place an SSH key on the server

Cloud-config

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

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

Bash script

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

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

Configure the configuration file

Cloud-config

Example script for the domain name resolver resolv.conf:

#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 the DNS servers that the system will use to resolve domain names, for example 4.4.4.4`` and 8.8.8.8;
• <searchdomain_1>, <searchdomain_2> — domains to be appended to short (incomplete) hostnames when accessed;
• <domain> — (legacy) the main DNS domain to be appended to short (incomplete) hostnames when accessed.

Bash script

Example script for the domain name resolver resolv.conf:

#!/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) the main DNS domain to be appended to short (incomplete) hostnames when accessed;
• <dns_server_ip_address_1>, <dns_server_ip_address_2> — IP addresses of the DNS servers that the system will use to resolve domain names, for example 4.4.4.4`` and 8.8.8.8;
• <searchdomain_1>, <searchdomain_2> — domains to be appended to short (incomplete) hostnames when accessed.

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 an OS with the Containers Ready application, you can use a script in the User data field to configure containers. To access the Portainer panel by domain, you need to insert the following 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> — contents of the Docker Compose file for the docker-compose.yaml file. For more details, see the docker compose guide in the Docker documentation;

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

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

  • portainer_use_le: true — a parameter for automatic TLS(SSL) certificate issuance from Let’s Encrypt®;
  • <example.com> — the domain to access Portainer. To make the domain accessible via the server's public IP address, add an A record in your DNS hosting control panel and set the server's public IP address as the record value. You can copy the IP address from the control panel: in the top menu, click Products → Dedicated Servers → server page → tab Operating System → in the IP field click . If the domain is delegated to Servercore DNS Hosting (actual), use the Add a resource record guide. After OS installation, a TLS(SSL) certificate from Let’s Encrypt® will be automatically issued for the domain. If TLS(SSL) certificate issuance fails, the Portainer panel will be available via the server's IP address;
  • <root@example.com> — the Containers Ready administrator email address for account creation and receiving Let’s Encrypt® notifications.