If your selected OS is not supported by Alibaba Cloud, and cloud-int cannot be installed, you can select Customized Linux when importing a customized image. Alibaba Cloud will then regard the customized Linux image as an unrecognized OS type (that is, it lacks necessary standard configuration information for ECS instance start for the first time). In this case, you need to add a parsing script to the customized image before importing the image, so as to facilitate automatic configuration of the instance at the first start.

Limitations

  • The first partition of the customized Linux image must be writable.

  • The first partition type of the customized Linux image must be FAT32, EXT2, EXT3, EXT4, or UFS.

  • The size of the virtual file of the customized Linux image must be larger than 5 GiB.

  • Security requirements for customized Linux images are as follows:

    • There is no high-risk vulnerability that can be remotely exploited.
    • When you log on to an instance for the first time through the Management Terminal of the ECS console, you must change the initial default password (if there is any) before performing subsequent actions.
    • There is no default SSH private key pair. The initial SSH private key pair must be randomly generated by Alibaba Cloud.

Procedure

  1. Create the aliyun_custom_image directory in the root directory of the first image partition.

    When the instance that is created using the customized Linux image is started for the first time, Alibaba Cloud will write configuration information into the os.conf file in the aliyun_custom_image directory. Alibaba Cloud will automatically create an os.conf file if there is none.

  2. Create a parsing script in the image to parse system configurations of the os.conf file. For details about how to write a script, see attentions on script parsing and parsing script example.

Example of the os.conf file

For instances using classic networks
hostname=iZ23r29djmjZ
password=cXdlcjEyMzQK
eth0_ip_addr=10.171.254.123
eth0_mac_addr=00:8c:fa:5e:14:23
eth0_netmask=255.255.255.0
eth0_gateway=10.171.254.1
eth0_route="10.0.0.0/8 10.171.254.1;172.16.0.0/12 10.171.254.1"
eth1_ip_addr=42.120.74.105
eth1_mac_addr=00:8c:fa:5e:14:24
eth1_netmask=255.255.255.0
eth1_gateway=42.120.74.1
eth1_route="0.0.0.0/0 42.120.74.1"
dns_nameserver="7.7.7.7 8.8.8.8"
The following table describes the parameters.
Parameter Parameter description​
hostname The host name
password The password, which is Base64-encoded
eth0_ip_addr The IP address of the eth0 NIC
eth0_mac_addr The MAC address of the eth0 NIC
eth0_netmask The network mask of the eth0 NIC
eth0_gateway The default gateway of the eth0 NIC
eth0_route The eth0 intranet route list, in which routes are separated by semicolons (;) by default
eth1_ip_addr The IP address of the eth1 NIC
eth1_mac_addr The MAC address of the eth1 NIC
eth1_netmask The network mask of the eth1 NIC
eth1_gateway The default gateway of the eth1 NIC
eth1_route The eth1 internet route list, in which routes are separated by semicolons (;) by default
dns_nameserver The DNS address list, in which addresses are separated by spaces by default
For instances using VPCs
hostname=iZ23r29djmjZ
password=cXdlcjEyMzQK
eth0_ip_addr=10.171.254.123
eth0_mac_addr=00:8c:fa:5e:14:23
eth0_netmask=255.255.255.0
eth0_gateway=10.171.254.1
eth0_route="0.0.0.0/0 10.171.254.1"
dns_nameserver="7.7.7.7 8.8.8.8"
The following table describes the parameters.
Parameter Parameter description​
hostname The host name
password The password, which is Base64-encoded
eth0_ip_addr The IP address of the eth0 NIC
eth0_mac_addr The MAC address of the eth0 NIC
eth0_netmask The network mask of the eth0 NIC
eth0_gateway The default gateway of the eth0 NIC
eth0_route The eth0 intranet route list, in which routes are separated by semicolons (;) by default
dns_nameserver The DNS address list, in which addresses are separated by spaces by default

Script parsing considerations

In normal cases, when an instance is started for the first time, Alibaba Cloud automatically writes information about configuration items into the os.conf file in the aliyun_custom_image directory in the root directory of the first partition. To configure a customized Linux image, you must create a pre-defined parsing script in the image. Then, Alibaba Cloud reads configuration information about the instance from the os.conf file to complete instance configuration. The following conditions must be met for script parsing:

  • Automatic start: The parsing script should be automatically started. To do so, place the script in the /etc/init.d/ directory.

  • Configuration item value rules: As described in example of the os.conf file , instances using classic networks and those using VPCs differ in rules of the number of configuration items and values of some configuration items.

  • Configuration file read path: By default, names of the devices allocated for the first partition vary with types of the instances created for the customized Linux image, including I/O optimization instances and non-I/O optimization instances. Therefore, you are recommended to use uuid or label to indicate devices in the first partition. Because the user password is a Base64-encoded string, it therefore must be Base64-encoded in the script.

  • Network type: When using the parsing script to determine the network type, you can check whether there is eth1_route or other eth1-related configuration item. To do so, parse and process the instance accordingly after determining whether it uses a classic network or VPC.

    • Instances using VPCs are configured with Internet routes that are specified by the eth0_route parameter in the os.conf file.

    • Instances using classic networks are configured with Internet routes that are specified by the eth1_route parameter in the os.conf file, and intranet routes are specified by the eth0_route parameter.

  • Configuration optimization: Configurations in the os.conf file are executed only once during the instance life cycle. You are recommended to delete the os.conf file after the parsing script is successfully executed. The parsing script does not execute configurations in the os.conf file if it does not read any.

  • Customized image processing: When you create a customized image based on the customized Linux image, the script requiring automatic start is also included in the new image. Alibaba Cloud will write os.conf file configurations when the instance is started for the first time. Then, the parsing script immediately executes the configurations upon detection.

  • Configuration change processing: When instance configurations are changed through the Alibaba Cloud console or APIs, Alibaba Cloud writes related information into the os.conf file. Then, the parsing script executes the configurations again to issue the changes.

Parsing script example

The following uses a parsing script used for CentOS as an example. You can change the script content as needed. Make sure that the script has been successfully debugged in the image before you use the script.

#! /bin/bash

### BEGIN INIT INFO
# Provides:          os-conf
# Required-Start:    $local_fs $network $named $remote_fs
# Required-Stop:
# Should-Stop:
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: The initial os-conf job, config the system.
### END INIT INFO

first_partition_dir='/boot/'
os_conf_dir=${first_partition_dir}/aliyun_custom_image
os_conf_file=${os_conf_dir}/os.conf

load_os_conf() {
	if [[ -f $os_conf_file ]]; then
		. $os_conf_file
		return 0
	else
		return 1
	fi
}

cleanup() {
	# ensure $os_conf_file is deleted, to avoid repeating config system
	rm $os_conf_file >& /dev/null
	# ensure $os_conf_dir is exitst
	mkdir -p $os_conf_dir
}

config_password() {
	if [[ -n $password ]]; then
		password=$(echo $password | base64 -d)
		if [[ $? == 0 && -n $password ]]; then
			echo "root:$password" | chpasswd
		fi
	fi
}

config_hostname() {
	if [[ -n $hostname ]]; then
		sed -i "s/^HOSTNAME=. */HOSTNAME=$hostname/" /etc/sysconfig/network
		hostname $hostname
	fi
}

config_dns() {
	if [[ -n $dns_nameserver ]]; then
		dns_conf=/etc/resolv.conf
		sed -i '/^nameserver.*/d' $dns_conf
		for i in $dns_nameserver; do
			echo "nameserver $i" >> $dns_conf
		done
	fi
}

is_classic_network() {
	# vpc: eth0
	# classic: eth0 eth1
	grep -q 'eth1' $os_conf_file
}

config_network() {
	/etc/init.d/network stop
	config_interface eth0 ${eth0_ip_addr} ${eth0_netmask} ${eth0_mac_addr}
	config_route eth0 ${eth0_route}
	if is_classic_network ; then
		config_interface eth1 ${eth1_ip_addr} ${eth1_netmask} ${eth1_mac_addr}
		config_route eth1 ${eth1_route}
	fi
	/etc/init.d/network start
}

config_interface() {
	local interface=$1
	local ip=$2
	local netmask=$3
	local mac=$4
	inteface_cfg="/etc/sysconfig/network-scripts/ifcfg-${interface}"
	cat << EOF > $inteface_cfg
DEVICE=$interface
IPADDR=$ip
NETMASK=$netmask
HWADDR=$mac
ONBOOT=yes
BOOTPROTO=static
EOF
}

config_default_gateway() {
	local gateway=$1
	sed -i "s/^GATEWAY=. */GATEWAY=$gateway/" /etc/sysconfig/network
}

config_route() {
	local interface=$1
	local route=$2
	route_conf=/etc/sysconfig/network-scripts/route-${interface}
	> $route_conf
	echo $route | sed 's/;/\n/' | \
		while read line; do
			dst=$(echo $line | awk '{print $1}')
			gw=$(echo $line | awk '{print $2}')
			if ! grep -q "$dst" $route_conf 2> /dev/null; then
				echo "$dst via $gw dev $interface" >> $route_conf
			fi
			if [[ "$dst" == "0.0.0.0/0" ]]; then
				config_default_gateway $gw
			fi
		done
}

################## sysvinit service portal ####################

start() {
	if load_os_conf ; then
		config_password
		config_network
		config_hostname
		config_dns
		cleanup
		return 0
	else
		echo "not load $os_conf_file"
		return 0
	fi
}

RETVAL=0

case "$1" in
    start)
        start
        RETVAL=$?
    ;;
    *)
        echo "Usage: $0 {start}"
        RETVAL=3
    ;;
esac

exit $RETVAL