Check whether an image meets the specifications and automatically repair the image - Elastic Compute Service

Before you import a custom image to Alibaba Cloud Elastic Compute Service (ECS), we recommend that you use the image compliance tool named sersi to check whether the image meets import conditions and automatically repair the image if exceptions exist in the image. This ensures image quality and helps you deploy a full-featured and highly compatible ECS instance in Alibaba Cloud. This topic describes how to use the sersi tool to check and repair images.

sersi tool

The sersi tool provided by Alibaba Cloud is used to check and repair images. The sersi tool automatically completes the following tasks during image check and repair:

Scans the operating system configurations and service configurations in an image and outputs a check report. The check report describes the image operating system and detailed exceptions.
Generates a repair script based on the detected exceptions and executes the repair script to repair the image.

Limits

The sersi tool does not support the FreeBSD, Fedora CoreOS, and Windows Server operating systems.

Procedure

Step 1: Check an image

Log on to the virtual machine (VM) on which an image is created as the root user.
Run the following commands in sequence to download and decompress the sersi tool package:
```
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/imagecheck/sersi.tar.gz
tar -xf sersi.tar.gz
```
If your VM can access the Internet, you can download the sersi tool package from a browser.

Run the following command to run the sersi tool:

./main.sh  --target=image  --diagnostic

The sersi tool checks the items in the following table.

Check items

Check item	Priority	Description	Impact of incompliance
Virtio	High	Check whether the virtio driver is installed in the image. ECS instances are VMs that are built based on the Kernel-based Virtual Machine (KVM) architecture, and require that the virtio driver be installed in the image.	An ECS instance startup exception occurs.
NVMe	High	Check whether the Non-Volatile Memory Express (NVMe) driver is installed in the image. Specific ECS instance types, such as ecs.g7se, use NVMe disks and require that the NVMe driver be installed in the image. NVMe delivers faster response speed and higher bandwidth than traditional driver protocols, such as Small Computer System Interface (SCSI) and virtio-blk. We recommend that you install the NVMe driver in the image to support specific instance types. For more information, see NVMe protocol.	Instance types that use NVMe disks, such as ecs.g7se, cannot be used.
Fstab	High	Check configurations in the /etc/fstab file. Incorrect configurations in the /etc/fstab file, such as configurations of nonexistent devices and incorrect universally unique identifiers (UUIDs), cause system startup exceptions.	The operating system cannot start as expected.
GRUB	High	Check the GRand Unified Bootloader (GRUB) configuration file. GRUB is a tool used to load and boot the kernel and is an important configuration item of operating systems. Incorrect configurations lead to system startup exceptions. We recommend that you check the GRUB configuration file in the operating system. For example, check the GRUB configuration file to ensure that device names are not used to specify boot partitions. Example: root=/dev/sda1. Device names may vary based on the environment. We recommend that you use UUIDs instead to specify boot partitions.	An operating system startup exception occurs.
DHCP	High	Check whether Dynamic Host Configuration Protocol (DHCP) is configured in the network configuration file of the image. We recommend that you configure DHCP for network devices to assign dynamic IP addresses to instances. If a static IP address is configured in the image, network configuration exceptions may occur and the instances that use the image cannot start. We also recommend that you add the `net.ifnames` parameter as a kernel startup parameter in the GRUB configuration file and set the parameter to 0 to prevent network interfaces from being renamed in the kernel. This way, the network interface controller (NIC) remains named eth0.	A network error occurs.
SELinux	Medium	Check whether Security-enhanced Linux (SELinux) is disabled in the image. We recommend that you disable SELinux.	An ECS instance startup exception occurs.
OnlineResizeFS	High	Check whether file systems in the image can be extended online. For example, the size of the virtual disk space in your image is 10 GB, and you create an instance that has a 100-GB system disk from the image and install components, such as cloud-init and growpart, on the instance. The root partition and file systems are automatically extended to the size of the system disk (100 GB) when the instance is initialized. For more information, see Extend the partitions and file systems of disks on a Linux instance.	The root partition of an ECS instance cannot be extended.
CloudInit	High	Check whether cloud-init is installed in the image. cloud-init initializes system configurations on instance startup and executes user data scripts. The system configurations include the Network Time Protocol (NTP) settings, software repositories, hostnames, and SSH key pairs.	Specific system initialization configurations are missing.
DiskUsage	High	Check the usage of disk space in the image. You can run the `df -h` command to check the usage of your disk space and ensure that sufficient disk space is available.	An operating system startup exception occurs.
InodeUsage	High	Check the index node (inode) usage of disks in the image. You can run the `df -i` command to check the inode usage of disks.	An operating system startup exception occurs.
SystemFileAttribute	High	Check whether the attributes of critical configuration files are correct.	An instance startup exception or a feature exception occurs.
CriticalUser	High	Check whether a critical user, such as root, exists in the operating system. The absence of critical users leads to system startup exceptions and instance feature exceptions. For example, you cannot use the username and password to connect to an instance.	An instance startup exception or a feature exception occurs.
QemuGuestAgent	Medium	Check whether Quick EMUlator (QEMU) guest agent (qemu-guest-agent) is installed in the operating system. The QEMU guest agent runs on VMs to interact with hosts. If the QEMU guest agent is installed, specific services that are required by ECS are unavailable, and the instance is not full-featured.	An exception occurs on a specific instance feature.
SshConfig	High	Check whether the sshd configuration file contains errors. In most cases, the sshd configuration file is /etc/ssh/sshd_config. If the sshd configuration file contains errors, the sshd service cannot start and SSH connections to ECS instances that use the image cannot be established. You must check the correctness and validity of the sshd configuration file. You can run the following commands: Run the `sudo sshd -T` command to view all sshd configuration options. Run the `sudo sshd -t` command to verify the validity of the sshd configuration file. If the sshd configuration file is valid, no information is returned.	An SSH connection to an ECS instance that uses the image cannot be established.
Firewall	Medium	Check whether the firewall service is enabled. We recommend that you disable the firewall service in the operating system and use ECS security groups to manage inbound and outbound traffic of instances. For information about security groups, see Overview.	The system firewall service may cause an instance access failure.
LibDirectory	High	In Red Hat operating systems, /lib and /lib64 are symbolic links that point to /usr/lib and /usr/lib64. Do not modify these links. Otherwise, system exceptions may occur.	The operating system cannot run as expected.
SupportMocInstanceTypes	High	Check whether the image supports instance types that are based on the SHENLONG architecture. The latest Alibaba Cloud ECS instance families are based on the SHENLONG architecture, such as ecs.g6 and ecs.g7. If the operating system version and kernel version of the image are too earlier, exceptions may occur when the image is started on a SHENLONG architecture-based ECS instance. For more information, see Overview of instance families.	The SHENLONG architecture-based ECS instance families, such as ecs.g6 and ecs.g7, cannot be used.
CloudAssistant	Medium	Check whether Cloud Assistant Agent is installed in the image. Cloud Assistant is a native automated O&M tool that is developed for ECS. We recommend that you install Cloud Assistant Agent in the image for efficient O&M of ECS. For more information, see Overview.	Cloud-based O&M efficiency is adversely affected.
SecurityCenterAgent	Medium	Check whether the Security Center agent is installed in the image. An instance can be protected by Security Center only after the Security Center agent is installed on the instance.	Vulnerabilities in an instance that uses the image cannot be identified, and the instance runs without Security Center protection.

After the sersi tool completes the check, the check result similar to the following one is returned.

Sample check result

------------------------------------------------------------

            OS: Alibaba Cloud Linux 3   Kernel: 5.10.134-16.3.al8.x86_64 
            Arch: x86_64       RTC-Mode: utc       Boot-Mode: UEFI
        
------------------------------------------------------------
Image Check Result
Virtio                                                                                 [OK]
Nvme                                                                                   [OK]
Fstab                                                                                  [OK]
Grub                                                                                   [OK]
Dhcp                                                                                   [OK]
Selinux                                                                                [OK]
OnlineResizeFS                                                                         [OK]
CloudAssistant                                                                         [OK]
CloudInit                                                                              [OK]
SecurityCenterAgent                                                                    [OK]
SupportMocInstanceTypes                                                                [OK]
DiskUsage                                                                              [OK]
InodeUsage                                                                             [OK]
SystemFileAttribute                                                                    [OK]
CriticalUser                                                                           [OK]
QemuGuestAgent                                                                         [OK]
SshConfig                                                                              [OK]
Firewall                                                                               [OK]

         Total case Count                18
            Successes:                   18
            Failures:                    0
            Warnings:                    0
        
------------------------------------------------------------

The sersi tool delivers check results, such as OK, FAILED or WARNING, according to the priority of check items.

OK: All check items comply with the requirements.
FAILED: Check items do not meet the requirements. The ECS instances created from the custom image may fail to start or encounter network exceptions. We recommend that you follow Step 2: Repair the image to repair the error items before you import the image.
WARNING: Check items do not meet the requirements. The ECS instances created from the custom image run without Security Center protection, and automated O&M by Cloud Assistant is unavailable for the ECS instances. We recommend that you follow Step 2: Repair the image to repair the error items to improve O&M efficiency before you import the image.

Step 2: Repair the image

Run the following command to automatically repair the image:

./main.sh --target=image --run <case> [--debug] [--dry-run] [-y]

The following table describes the parameters used in the preceding command. Configure the parameters based on your business requirements.

Parameter	Required	Description
`run <case>`	Yes	The check items that need to be repaired. Supported check items include `cloudinit`, `virtio`, `nvme`, `fstab`, `grub`, `dhcp`, `selinux`, `growpart`, `aegis`, `assist`, `firewall`, `sshd`, `fileattribute`, and `qemuguestagent`. Specify the check items based on your business requirements. Check all items and repair the items that have exceptions. Example: `./main.sh --target=image --run all`. Check and repair a specific item. For example, to check whether cloud-init is installed in the image, run the `./main.sh --target=image --run cloudinit` command. Check and repair multiple items. Separate the check items with spaces. Example: `./main.sh --target=image --run cloudinit virtio assist`.
`[--debug]`	No	Specify this parameter to print debugging messages.
`[--dry-run]`	No	If you specify this parameter, the sersi tool prints the repair script and does not run the repair script. If you do not specify this parameter, the sersi tool runs the repair script and does not print the repair script.
`[-y]`	No	If you specify this parameter, the sersi tool runs the repair script without prompting you to confirm the operation. If you do not specify this parameter, the sersi tool prompts you to confirm whether to run the repair script. You can enter `y` to proceed.

Important

The sersi tool cannot roll back the repair script. After the repair script is run, the changes to the operating system cannot be revoked. We strongly recommend that you take note of the following operations:

Before the repair script is run, specify the [--dry-run] parameter to view the repair script without running the repair script. You can view or debug the repair script saved in the cache directory. After you verify that the script is correct, run the repair script without specifying the [--dry-run] parameter.
When you use the sersi tool to run the repair script, do not specify the -y parameter. This way, you can confirm whether to run the repair script, which prevents accidental changes or data loss caused by the repair script.

Sample repair commands

Note

You can manually repair check items that cannot be automatically repaired by using the sersi tool.

Check item	Automatic repair method	Command for automatic repair	Manual repair method
Virtio	The tool adds the virtio driver configurations to the dracut configuration file, which regenerates the initrd file that contains the virtio driver configurations.	`./main.sh --target=image --run virtio --debug --dry-run`	Install the virtio driver.
Nvme	The tool adds the NVMe driver configurations to the dracut configuration file, which regenerates the initrd file that contains the NVMe driver configurations. At the same time, the timeout parameter of the `nvme` or `nvme_core` kernel module is added to the GRUB configuration file to improve the reliability of NVMe I/O processing. Important You must manually restart the system for the changed configurations to take effect.	`./main.sh --target=image --run nvme --debug`	How do I install the NVMe driver for a custom image?
Fstab	The tool comments out abnormal mount entries in the /etc/fstab file.	`./main.sh --target=image --run fstab --debug`	For information about how to configure the /etc/fstab file, see Configure UUIDs in the fstab file to automatically mount data disks.
Grub	The tool corrects the `rootdevice` value in the GRUB configuration file.	`./main.sh --target=image --run grub --debug`	None.
Dhcp	The tool configures the network service configuration file. In the configuration file, the NIC name is eth0, and the `dhcp` parameter is set to true. At the same time, the tool can add the kernel startup parameter `biosdevname=0 net.ifnames=0` to the GRUB configuration file and make sure that the NIC name is eth0. Important You must manually restart the system for the changed configurations to take effect.	`./main.sh --target=image --run dhcp --debug`	None.
Selinux	The tool changes the mode to `disabled` in the `/etc/selinux/config` configuration file. The tool adds the kernel startup parameter `selinux=0` to disable SElinux in the GRUB configuration file. Important You must manually restart the system for the changed configurations to take effect.	`./main.sh --target=image --run selinux --debug`	For information about how to disable SELinux, see Enable or disable SELinux.
OnlineResizeFS	The tool configures a growpart script to support root partition extension.	`./main.sh --target=image --run growpart --debug`	Install cloud-init. Install the growpart utility. For information about how to install growpart, see the What do I do if the root partition of the system disk is not automatically extended after I resize the disk when I create an instance? section in the Install cloud-init topic.
CloudInit	The tool configures a temporary software repository, installs the cloud-init software package by using the package manager, and then sets the data source to Alibaba Cloud in the cloud-init configuration file.	`./main.sh --target=image --run cloudinit --debug`	Install cloud-init.
DiskUsage	The check item cannot be automatically repaired. You can only manually repair the check item.	N/A	Manually delete unnecessary files.
InodeUsage	The check item cannot be automatically repaired. You can only manually repair the check item.	N/A	Manually delete unnecessary files.
SystemFileAttribute	The check item can be automatically repaired. The tool deletes the detected exception attributes for files.	`./main.sh --target=image --run fileattribute --debug`	Do not run the `chattr` command to lock files such as /etc/shadow.
CriticalUser	The check item cannot be automatically repaired. You can only manually repair the check item.	N/A	Retain the root account.
QemuGuestAgent	The check item can be automatically repaired. The tool uninstalls the QEMU guest agent (qemu-guest-agent).	`./main.sh --target=image --run qemuguestagent --debug`	Uninstall the QEMU guest agent (qemu-guest-agent).
SshConfig	The check item can be automatically repaired. The tool enables SSH password authentication and root user logon.	`./main.sh --target=image --run sshd --debug`	Check the sshd configuration file.
Firewall	The check item can be automatically repaired. The tool disables the firewall service.	`./main.sh --target=image --run firewalld --debug`	Disable the system firewall service.
LibDirectory	The check item cannot be automatically repaired. You can only manually repair the check item.	N/A	Modify the paths to which the /lib and /lib64 symbolic links point from absolute paths to relative paths.
SupportMocInstanceTypes	The check item cannot be automatically repaired. You can only manually repair the check item.	N/A	In most cases, operating system versions that do not support SHENLONG architecture-based instance types are earlier versions that reached end of life (EOL) and are no longer supported. We recommend that you upgrade the operating system versions at the earliest opportunity and use operating system versions that are supported and updated by distributors.
CloudAssistant	The check item can be automatically repaired. The tool installs Cloud Assistant Agent.	`./main.sh --target=image --run assist --debug`	Install Cloud Assistant Agent.
SecurityCenterAgent	The check item can be automatically repaired. The tool installs the Alibaba Cloud Security Center agent.	`./main.sh --target=image --run aegis --debug`	Install the Security Center agent.

Sample repair results

2024-07-19 17:20:54,480 root [INFO]: sersi run finished, print summary report
2024-07-19 17:20:54,480 root [INFO]: casename: cloudinit                            NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: virtio                               OK
2024-07-19 17:20:54,480 root [INFO]: casename: nvme                                 OK_Need_Reboot
2024-07-19 17:20:54,480 root [INFO]: casename: fstab                                NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: grub                                 NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: dhcp                                 NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: selinux                              NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: growpart                             NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: aegis                                NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: assist                               DRY_RUN
2024-07-19 17:20:54,480 root [INFO]: casename: firewall                             NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: sshd                                 NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: systemfileattribute                  NO_FOUND_RISK
2024-07-19 17:20:54,480 root [INFO]: casename: qemu_guest_agent                     FAILED

After the repair is completed, the tool returns the following sample repair results:

OK: The check item is repaired.
NO_FOUND_RISK: No exception is found for the check item in the image.
OK_Need_Reboot: The check item is repaired, and the system must be restarted.
DRY_RUN: The tool detects an exception for the item. The tool works in dry-run mode to print the repair script, but does not run the repair script.
FAILED: The check item cannot be repaired.

References

You can obtain an image file and import the image file to Alibaba Cloud after the image passes image check. For information about how to obtain an image file, see Obtain a Linux image file.
When you import an image to Alibaba Cloud, you can use the image check feature to check whether the image is properly configured and use CloudOps Orchestration Service (OOS) to repair the image. For more information, see Import custom images and Overview of the image check feature.