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 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, CentOS Stream, Ubuntu, SUSE Linux Enterprise Server, Red Hat Enterprise Linux, OpenSUSE, Debian, AlmaLinux, Rocky Linux, and Fedora
- 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
- 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.
- 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.
- Modify the user data of an existing instance. On the Instances page, find the instance whose user data you want to modify and choose 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.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
- 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.
- View the user data passed into the instance and the result of running the user data.
User-data scripts
- 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.
#!/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
- 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.
#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
- 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.
#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
.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.
#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 first line starts with
#upstart-job
, and the header cannot include spaces. - Upstart job scripts are run each time the instance starts.
#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
- 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.
#!/bin/sh
# Modify DNS
echo "nameserve8.8.X.X.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
- 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.
[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.X.X [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.
#!/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
- 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.
[test@iZbp1csxtw7jo9zp12s**** ~]$ cd /root -bash: cd: /root: Permission denied [test@iZbp1csxtw7jo9zp12s**** ~]$ sudo cd /root [test@iZbp1csxtw7jo9zp12s**** ~]$