This topic describes how to prepare user data for Linux Elastic Compute Service (ECS) instances and how to pass in user data and verify the result of running the user data.

Prerequisites

If you want to modify the user data of an instance, make sure that the instance is in the Stopped state.

Background information

The user data feature for Linux instances uses the open source cloud-init architecture. After you pass user data into an instance by using the ECS console or by calling an API operation, you can view the user data in the instance metadata. cloud-init uses the metadata of Linux instances as data sources to configure the instances. When an instance starts, the system uses the administrator or root permissions to run user data.
The following limits apply to user data:
  • The user data feature is supported only for instances that reside in virtual private clouds (VPCs).
  • The instances must be created from the following public images or custom images derived from public images:
    • Alibaba Cloud Linux, CentOS, Ubuntu, SUSE Linux Enterprise, OpenSUSE, and Debian
    • Windows Server 2008 R2 and later
  • The user data feature is supported for all available instance types. For retired instance types, the user data feature is supported only for I/O-optimized instances. For more information, see Retired instance types.
  • The user data that you want to run must be encoded in Base64. The size of the user data cannot exceed 16 KB before it is encoded.
    Note You can enter the user data that has not been encoded in Base64 in the console. The console automatically encodes the user data in Base64. If you do not want to enter the user data in the console, you must encode it in Base64 on your own.

Procedure

  1. Prepare user data.
    You can run a variety of scripts to prepare user data for Linux instances. For more information about the characteristics of different scripts and their examples, see the following sections:
    Note If you want to use include files or gzip compressed content, you must upload script files to available storage services, obtain the links to the files, and then set validity periods for the links. We recommend that you use Alibaba Cloud Object Storage Service (OSS). For more information, see Upload objects and Configure lifecycle rules. You can also learn more about the ways to prepare user data from the cloud-init documentation. For more information, see User-Data Formats.
  2. Pass the user data into an instance.
    • Pass in the user data when you create an instance. In the System Configurations (Optional) step, click Advanced to show advanced options and enter the user data in the User Data field. If the user data is encoded in Base64, select Enter Base64 Encoded Information.
      The following figure shows an example on how to write the system time to a specific file the first time the instance starts. createinstance-userdata
    • Modify the user data of an existing instance. On the Instances page, find the instance whose user data you want to modify and choose More > Instance Settings > Set User Data in the Actions column. In the Set User Data dialog box, enter new user data in the User Data field
      Note If you want to start a pay-as-you-go instance immediately after you modify its user data, we recommend that you set the stop mode of the instance to Standard Mode.
      The following figure shows an example on how to write the system time to a specific file each time an instance starts. modifyinstance-userdata
      After user data is modified for a Linux instance, the script type and module type determine whether new user data is run when the instance starts. Examples:
      • User-data scripts are not run.
      • Cloud-config data is not run if modules such as Byobu and Set Passwords are configured.
      • Cloud-config data is run if modules such as Bootcmd, Update Etc Hosts, and Yum Add Repo are configured.

      For information about the characteristics of the modules, see the module frequency line of each module in Modules

  3. View the user data passed into the instance and the result of running the user data.
    1. Connect to your instance. For more information, see Connection methods.
    2. Run the following command to view the user data in the metadata of the instance: 
      curl http://100.100.100.200/latest/user-data
      In this example, the user data that was passed in in Step 2 is used. If the user data is included in the command output as shown in the following figure, the user data is passed in as expected. view-user-data
    3. View the result of running the user data. 
      cat userdata_test.txt

      The result of running a script is related to its content. The following figure provides an example of the result of writing the system time to a specific file.

      view-result

User-data scripts

User-data scripts are directly executed as shell scripts after they are passed into Linux instances. User-data scripts have the following characteristics:
  • The first line starts with a number sign and an exclamation mark (#!).
  • User-data scripts are run once only the first time the instance starts.
Example: 
#!/bin/sh
echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt

The example user-data script can be run to write the system time to the userdata_test.txt file the first time the instance starts.

Cloud-config data

Cloud-config is a convenient way to pre-configure specific services (such as YUM repository update, SSH key import, and dependency installation) for instances. Cloud-config data has the following characteristics:
  • The first line starts with #cloud-config, and the header cannot include spaces.
  • The script must follow the YAML syntax.
  • The frequency at which the user data is run varies based on your configured modules. For example, if you configure the Apt Configure module, the user data is run only once for each instance. If you configure the Bootcmd module, the user data is run each time the instance starts.
Example: 
#cloud-config
apt:
 primary:
  - arches: [default]
    uri: https://us.archive.ubuntu.com/ubuntu/
    bootcmd:
     - echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt

The example cloud-config data can be run to modify the default software repository and write the latest system time to the userdata_test.txt file each time the instance starts.

Include files

An include file contains one or more script links, one per line. When the instance starts, cloud-init reads each script link and script content. If an error occurs while a script is being read, the remaining scripts are not read. Include files have the following characteristics:
  • The first line starts with #include, and the header cannot include spaces.
  • Each script cannot exceed 16 KB in size before it is encoded in Base64.
  • The frequency at which the user data is run varies based on the types of scripts and modules.
Example: 
#include
https://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/myscript.sh

The example include file contains a script link. The running frequency is determined by the type of the script. For example, if the script is a user-data script, the script is run once only the first time the instance starts.

Gzip compressed content

If your user-data script, cloud-config data, or include file may exceed 16 KB in size, you can gzip compress the user-data script, cloud-config data, or include file to the .gz format, create a link to the gzip compressed content, and then pass in the link as an include file. cloud-init automatically decompresses the gzip compressed content. The result of running the decompressed content shows no difference from that of running a script that is directly passed in. Gzip compressed content has the following characteristics:
  • The first line starts with #include, and the header cannot include spaces.
  • The size of the gzip compressed content cannot exceed 16 KB before it is encoded in Base64.
  • The frequency at which the user data is run varies based on the types of scripts and modules.
Example: 
#include
https://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/myscript.gz

The example include file contains a link to gzip compressed content. cloud-init reads the gzip compressed content and automatically decompresses and runs it. The running frequency is determined by the script type. For example, if the gzip compressed content is obtained by compressing a user-data script, the gzip compressed content is run once only the first time the instance starts.

Upstart job scripts

The content of upstart job scripts is placed into a file in the /etc/init directory. Upstart job scripts have the following characteristics:
  • The first line starts with #upstart-job, and the header cannot include spaces.
  • Upstart job scripts are run each time the instance starts.
Note To use upstart job scripts, you must install the upstart service for the instance. The upstart service is supported for instances that run one of the following operating systems: CentOS 6, Ubuntu 10, Ubuntu 12, Ubuntu 14, Debian 6, and Debian 7.
Example: 
#upstart-job
description "upstart test"
start on runlevel [2345] #Starts at run levels 2, 3, 4, and 5.
stop on runlevel [!2345] #Stops at run levels other than 2, 3, 4, and 5.
exec echo "Hello World. The time is now $(date -R)!" | tee /root/output.txt

Example 1: Use user-data scripts to customize YUM repositories and the NTP and DNS services

When an instance starts, the system configures the default YUM repository, the Network Time Protocol (NTP) service, and the Domain Name System (DNS) services. You can use the user data of the instance to change the default YUM repository and NTP and DNS services that are configured. Take note of the following items:
  • If you customize a YUM repository, Alibaba Cloud stops providing YUM repository support.
  • If you customize the NTP service, Alibaba Cloud stops providing time synchronization services.
The following code provides a sample user-data script that can be run on an instance that runs a CentOS 7.2 operating system:
#!/bin/sh
# Modify DNS
echo "nameserver 8.8.8.8" | tee /etc/resolv.conf
# Modify yum repo and update
rm -rf /etc/yum.repos.d/*
touch myrepo.repo
echo "[base]" | tee /etc/yum.repos.d/myrepo.repo
echo "name=myrepo" | tee -a /etc/yum.repos.d/myrepo.repo
echo "baseurl=https://mirror.centos.org/centos" | tee -a /etc/yum.repos.d/myrepo.repo
echo "gpgcheck=0" | tee -a /etc/yum.repos.d/myrepo.repo
echo "enabled=1" | tee -a /etc/yum.repos.d/myrepo.repo
yum update -y
# Modify NTP Server
echo "server ntp1.aliyun.com" | tee /etc/ntp.conf
systemctl restart ntpd.service
Note
  • In the preceding example, the URL is for reference only. You can replace it to suit your needs.
  • You can also use cloud-config data to change the YUM repository. However, cloud-config data is not as flexible as user-data scripts and is not applicable to scenarios where Alibaba Cloud pre-configures some YUM repositories. We recommend that you use user-data scripts.
Pass in the user data when you create the instance. After the instance starts, log on to the instance to view the result of running the user data. Check whether the configurations of the YUM repository and NTP and DNS services are as expected, as shown in the following figure. 
[root@iZbp1csxtw7jo9zp12s**** ~]# cat /etc/yum.repos.d/myrepo.repo
[base]
name=myrepo
baseurl=https://mirror.centos.org/centos
gpgcheck=0
enabled=1
[root@iZbp1csxtw7jo9zp12s**** ~]# cat /etc/resolv.conf
nameserver 8.8.8.8
[root@iZbp1csxtw7jo9zp12s**** ~]# ping www.baidu.com
PING www.a.shifen.com (14.215.XX.XX) 56(84) bytes of data.
64 bytes from 14.215.XX.XX (14.215.XX.XX): icmp_seq=1 ttl=52 time=26.3 ms
64 bytes from 14.215.XX.XX (14.215.XX.XX): icmp_seq=2 ttl=52 time=26.3 ms
64 bytes from 14.215.XX.XX (14.215.XX.XX): icmp_seq=3 ttl=52 time=26.2 ms
^Z
[2]+  Stopped                 ping www.baidu.com
[root@iZbp1csxtw7jo9zp12s**** ~]# cat /etc/ntp.conf
server ntp1.aliyun.com
[root@iZbp1csxtw7jo9zp12s**** ~]# systemctl status ntpd.service
● ntpd.service - Network Time Service
   Loaded: loaded (/usr/lib/systemd/system/ntpd.service; enabled; vendor preset: disabled)
   Active: active (running) since Mon 2021-09-06 14:53:19 CST; 13min ago
 Main PID: 5795 (ntpd)
   CGroup: /system.slice/ntpd.service
           └─5795 /usr/sbin/ntpd -u ntp:ntp -g

Sep 06 14:53:19 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: Listen and drop on 1 v6wildcard :: UDP 123
Sep 06 14:53:19 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: Listen normally on 2 lo 127.0.XX.XX UDP 123
Sep 06 14:53:19 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: Listen normally on 3 eth0 192.168.XX.XX UDP 123
Sep 06 14:53:19 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: Listening on routing socket on fd #20 for interface updates
Sep 06 14:53:19 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: 0.0.XX.XX c016 06 restart
Sep 06 14:53:19 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: 0.0.XX.XX c012 02 freq_set kernel 0.000 PPM
Sep 06 14:53:19 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: 0.0.XX.XX c011 01 freq_not_set
Sep 06 14:56:34 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: 0.0.XX.XX c61c 0c clock_step +0.464773 s
Sep 06 14:56:35 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: 0.0.XX.XX c614 04 freq_mode
Sep 06 14:56:36 iZbp1cjdaurreftzgpgvqoZ ntpd[5795]: 0.0.XX.XX c618 08 no_sys_peer

Example 2: Use user-data scripts to customize the administrator account

By default, Linux instances use the root account as the administrator account. You can use the user data of an instance to configure another account as the administrator account.

The following code provides a sample user-data script that can be run on an instance that runs a CentOS 7.2 operating system:
#!/bin/sh
useradd test
echo "test   ALL=(ALL)        NOPASSWD:ALL" | tee -a /etc/sudoers
mkdir /home/test/.ssh
touch /home/test/.ssh/authorized_keys
echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCRnnUveAis****" | tee -a /home/test/.ssh/authorized_keys
Note Replace ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCRnnUveAis**** in the preceding example with your public key.
The sample user-data script can be run to obtain the following results:
  • An account named test is created and used as the administrator account.
  • The account can use only SSH key pairs to log on to the instance and cannot use passwords for logon.
  • If you want to use the account to perform operations that require the administrator permissions, you must run the sudo command to grant administrator permissions to the account, without the need to enter a password.
Pass in the user data when you create the instance. After the instance starts, log on to the instance by using the test account and the SSH key pair. An error is reported if you attempt to use a password for logon. After you connect to the instance, you can run the sudo command to grant administrator permissions to the test account and then perform operations that require the administrator permissions, as shown in the following figure. 
[test@iZbp1csxtw7jo9zp12s**** ~]$ cd /root
-bash: cd: /root: Permission denied
[test@iZbp1csxtw7jo9zp12s**** ~]$ sudo cd /root
[test@iZbp1csxtw7jo9zp12s**** ~]$