Check and fix images with the sersi tool - Elastic Compute Service

Importing a misconfigured custom image (such as missing drivers or improper network settings) may cause the Elastic Compute Server (ECS) instance boot failures or network issues. Use Alibaba Cloud's sersi tool to scan, evaluate, and automatically fix your image before import to improve deployment success rate.

Important

The modifications made by sersi's fix scripts are irreversible.

Supported operating systems

This tool supports mainstream operating systems (OS) families:

Red Hat series: Alibaba Cloud Linux, Anolis, Red Hat, CentOS, CentOS Stream, Fedora, AlmaLinux, Rocky Linux, openEuler, and OpenCloudOS.
Debian series: Debian, Ubuntu, Kylin, and UOS.
SUSE series: SUSE and openSUSE.

FreeBSD, Fedora CoreOS, and Windows Server systems are not supported.

Procedure

Step 1: Download and decompress the tool

Download the sersi tool package.

wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/imagecheck/sersi.tar.gz

Extract the tool package.
```
tar -xf sersi.tar.gz
```

Step 2: Check the image

Run the check command to generate a health report for your image.

Scan the image for all check items.
```
./main.sh --target=image --diagnostic
```

Analyze the results. The command outputs a formatted report.

OK: The item meets Alibaba Cloud image specifications.
FAILED (Must fix): The item has a critical issue that may prevent the instance from booting or cause core functions (such as networking) to fail.
WARNING (Recommended fix): The item has a configuration issue. While it does not affect instance boot, it may cause some advanced features (such as Cloud Assistant or monitoring) unavailable or pose security risks.

For a detailed description of the check items, see Overview of check and fix items.

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

            OS: Alibaba Cloud Linux 3   Kernel: 5.10.134-16.1.al8.x86_64 
            Arch: x86_64       RTC-Mode: utc       Boot-Mode: Legacy
        
------------------------------------------------------------
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
        
------------------------------------------------------------

Step 3: Fix the image

Automatic fix

The fix scripts make irreversible changes. Follow a safe "review, then execute" process.

The sersi tool does not automatically fix the DiskUsage, InodeUsage, CriticalUser, LibDirectory, and SupportMocInstanceTypes items. Fix them manually by following the instructions in the Manual fix section.

Review:
Use --dry-run parameter to generate and review the fix script without making any changes.
To fix a single item, see How do I fix a single check item?
```
# Repair all issues
./main.sh --target=image --run all --dry-run 
```

Execute:

After confirming the script is safe, remove the --dry-run parameter to apply the fix.

# Interactive repair: Confirmation is requested before each repair step is executed.
./main.sh --target=image --run all

Analyze the fix results:
- OK: The item was fixed successfully.
- NO_FOUND_RISK: No issue was found for this item in the image.
- OK_Need_Reboot: The fix is complete, but a system reboot is required for the changes to take effect.
- DRY_RUN: The tool, run in dry-run mode, found an issue and printed the fix script without executing it.
- FAILED: The fix failed. You need to perform a Manual fix.

Manual fix

For items that cannot be fixed automatically or automatic fix fails, follow these manual instructions.

DiskUsage: Manually delete unnecessary files.
InodeUsage: Manually delete unnecessary files.
CriticalUser: Retain the root account.
LibDirectory: The /lib and /lib64 symbolic links must not point to absolute paths. Change them to point to relative paths.
SupportMocInstanceTypes: Systems that do not support SHENLONG instance types are typically older, end-of-life (EOL) versions that are no longer maintained. Upgrade to an OS version that is actively maintained by the vendor.
Virtio: Install the virtio driver.
Nvme: Install the NVMe driver.
Fstab: Correctly configure /etc/fstab.
Dhcp: Configure the network as DHCP in a Linux image.
Selinux: Enable or disable SELinux.
OnlineResizeFS: Install cloud-init and the growpart tool.
Cloudinit: Install cloud-init.
SshConfig: Check the sshd configuration file.
Firewall: Disable the system firewall service.
CloudAssistant: Install the Cloud Assistant Agent.
SecurityCenterAgent: Install the Security Center agent.
QemuGuestAgent: Manually uninstall qemu-guest-agent.
SystemFileAttribute: Do not use the chattr command to lock critical files like /etc/shadow.

Step 4: Verify the fix

(Optional) Reboot the system. Some fixes (Nvme, Dhcp, and Selinux) require a system reboot to take effect.
Run the check command again to ensure all items have an OK status.
```
./main.sh --target=image --diagnostic
```

Overview of check and fix items

Check item (Case Name)	Repair item	Impact	Description
`Virtio`	`virtio`	The ECS instance fails to boot.	Checks whether the virtio driver is installed in the image. Alibaba Cloud ECS instances are KVM-based virtual machines (VMs) and rely on the virtio driver for virtual disks.
`Nvme`	`nvme`	Cannot use instance types that require NVMe protocol-based cloud disks, such as `ecs.g7se`	Checks whether the NVMe driver is installed in the image. Some ECS instance types, such as `ecs.g7se` , use NVMe protocol cloud disks and require the image to include the NVMe driver. NVMe offers faster speeds and higher transfer bandwidth than traditional driver protocols (such as SCSI and virtio-blk). Install the NVMe driver in your image to support these instance types.
`Fstab`	`fstab`	The system fails to boot.	Checks whether the /etc/fstab configuration is correct. An incorrect configuration, such as a non-existent mount device or an incorrect device UUID, can cause the system to fail to boot.
`Grub`	`grub`	The system fails to boot.	Checks whether the GRUB configuration file is correct. A configuration error, such as specifying a boot partition by device name instead of UUID, will prevent the system from booting.
`Dhcp`	`dhcp`	The system network connection fails.	Checks that DHCP is enabled for network interfaces. Static addressing may lead to failed network configuration and connection problems. Add `net.ifnames=0` to the GRUB kernel boot parameters to turn off interface renaming and keep the interface name as `eth0`.
`Selinux`	`selinux`	The ECS instance fails to boot.	Checks whether SELinux is disabled. Disable SELinux.
`OnlineResizeFS`	`growpart`	The root partition of the instance cannot be resized.	Checks that the image can auto-grow the root partition and filesystem at first boot (via cloud-init or growpart). For instance, a 10 GB image can be expanded to fill a 100 GB system disk. For more information, see Extend partitions and file systems (Linux).
`Cloudinit`	`cloudinit`	System initialization configurations are missing.	Checks that cloud-init is installed. cloud-init configures NTP, package repos, hostname, and SSH key pairs at boot, and runs the instance's User Data script.
`SshConfig`	`sshd`	SSH connection to the instance fails.	Checks whether the sshd service configuration file (typically /etc/ssh/sshd_config) is correct. If the sshd configuration file is incorrect, the sshd service may fail to start, which in turn can cause SSH connections to the ECS instance to fail. To check the file: Run `sudo sshd -T` to display all configuration options. Run `sudo sshd -t` to validate the configuration file. If the file is valid, no output is returned.
`Firewall`	`firewall`	The system firewall may block access to the instance.	Checks whether the firewall service is enabled. Disable the system's firewall service and use ECS security groups to centrally manage inbound and outbound traffic for your cloud instances.
`CloudAssistant`	`assist`	Cloud O&M are inconvenient.	Checks whether Cloud Assistant is installed in the image. Cloud Assistant is a native automation tool built for ECS that allows for efficient operations and maintenance. Install the Cloud Assistant service in your image.
`SecurityCenterAgent`	`aegis`	Vulnerabilities in the instance cannot be identified without protection from Security Center.	Checks whether the Security Center agent is installed. The agent must be installed for the server to be protected by Security Center.
`QemuGuestAgent`	`qemuguestagent`	Instance features may not work correctly.	Checks whether `qemu-guest-agent` is installed. This software runs on the VM and communicates with the host machine, which can make some ECS services unavailable and leave instance functionality incomplete.
`Diskusage`	Not supported	The system fails to boot.	Checks whether the disk space usage is normal. You can run the `df -h` command to check disk space usage and ensure there is sufficient space.
`Inodeusage`	Not supported	The system fails to boot.	Checks whether the disk inode usage is normal. You can run the `df -i` command to check disk inode usage.
`SystemFileAttribute`	`fileattribute`	The instance fails to boot or functions abnormally.	Checks whether the file attributes of critical system configuration files are correct.
`Criticaluser`	Not supported	The instance fails to boot or functions abnormally.	Checks whether critical users (such as root) exist. A missing critical user can cause the system to boot abnormally or prevent remote connections to the instance.
`LibDirectory`	Not supported	The system functions abnormally.	In Red Hat series Linux systems, /lib and /lib64 are typically symbolic links that point to /usr/lib and /usr/lib64. Do not modify these links, as doing so may cause system issues.
`SupportMocinstanceTypes`	Not supported	Cannot use SHENLONG instance families like `ecs.g6` and `ecs.g7` .	Checks whether the image supports Alibaba Cloud ECS SHENLONG instance types. The latest ECS instances, such as `ecs.g6` and `ecs.g7` , are typically SHENLONG instance types. If the image's OS and kernel versions are too old, they may fail to boot on these instance types. For more information, see Overview of instance families.

Detailed description of fix commands

The command to automatically fix an image is as follows:

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

Parameter	Required	Description
`run <case>`	Yes	The fix item to run. Supported fix items: `cloudinit`, `virtio`, `nvme`, `fstab`, `grub`, `dhcp`, `selinux`, `growpart`, `aegis`, `assist`, `firewall`, `sshd`, `fileattribute`, and `qemuguestagent`. For the mapping between check items and fix items, see Overview of Check and Fix Items. Use `all` to fix all supported items. Separate multiple items with spaces.
`[--dry-run]`	No	Recommended for the first fix attempt. Prints the fix script without executing it.
`[--debug]`	No	Enables detailed log output for troubleshooting.
`[-y]`	No	Automatically confirms all fix steps and skips interactive prompts.

FAQ

Why is an issue still present after I applied the fix for `nvme`, `selinux` or `dhcp`?

These three fixes require a reboot to apply. After applying them, reboot the VM and rerun the tool to verify the result.

How do I fix a single check item?

To fix a single item, such as SshConfig:

In the Overview of check and fix items table, find the fix item sshd that corresponds to the SshConfig check item.
Review:
To fix a different item, replace sshd with the corresponding fix item name.
```
./main.sh --target=image --run sshd --dry-run 
```
Execute:
```
./main.sh --target=image --run sshd
```

Elastic Compute Service:Check and fix images with the sersi tool

Supported operating systems

Procedure

Step 1: Download and decompress the tool

Step 2: Check the image

Step 3: Fix the image

Automatic fix

Manual fix

Step 4: Verify the fix

Overview of check and fix items

Detailed description of fix commands

Related documents

FAQ

Why is an issue still present after I applied the fix for `nvme`, `selinux` or `dhcp`?

How do I fix a single check item?

Supported operating systems

Procedure

Step 1: Download and decompress the tool

Step 2: Check the image

Step 3: Fix the image

Automatic fix

Manual fix

Step 4: Verify the fix

Overview of check and fix items

Detailed description of fix commands

Related documents

FAQ

Why is an issue still present after I applied the fix for nvme, selinux or dhcp?

How do I fix a single check item?

Why is an issue still present after I applied the fix for `nvme`, `selinux` or `dhcp`?