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

Scan and fix custom images with sersi before import to prevent boot failures and network issues caused by missing drivers or misconfigurations.

Important

The modifications made by sersi fix scripts are irreversible.

Supported operating systems

Supported 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 are not supported.

Procedure

Step 1: Download and decompress the tool

Download the sersi package.

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

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

Step 2: Check the image

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

Scan the image.
```
./main.sh --target=image --diagnostic
```

Analyze the results:

OK: Meets Alibaba Cloud image specifications.
FAILED (Must fix): Critical issue that may prevent boot or cause core functions (such as networking) to fail.
WARNING (Recommended fix): Configuration issue that does not affect boot but may make some features (such as Cloud Assistant or monitoring) unavailable or pose security risks.

See Overview of check and fix items for details on each item.

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

            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

Fix scripts make irreversible changes. Follow a "review, then execute" process.

The sersi tool cannot automatically fix DiskUsage, InodeUsage, CriticalUser, LibDirectory, and SupportMocInstanceTypes. Fix them manually per the Manual fix section.

Review:

Use --dry-run to generate and review the fix script without applying 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 --dry-run 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: Fixed successfully.
- NO_FOUND_RISK: No issue found.
- OK_Need_Reboot: Fixed, but requires a reboot to take effect.
- DRY_RUN: Issue found; fix script printed but not executed.
- FAILED: Fix failed. Perform a manual fix.

Manual fix

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

DiskUsage: Manually delete unnecessary files.
InodeUsage: Manually delete unnecessary files.
CriticalUser: Retain the root account.
LibDirectory: The /lib and /lib64 symbolic links must point to relative paths, not absolute paths.
SupportMocInstanceTypes: Typically caused by older, EOL OS versions. Upgrade to an actively maintained version.
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, Selinux) require a reboot.
Rerun the check command to ensure all items show OK.
```
./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. Alibaba Cloud ECS instances are KVM-based virtual machines and require 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. Some ECS instance types, such as ecs.g8i, ecs.g8a, ecs.g9i, and ecs.g9a, use NVMe protocol cloud disks and require the NVMe driver. NVMe offers faster speeds and higher bandwidth than traditional protocols (such as SCSI and virtio-blk).
`Fstab`	`fstab`	The system fails to boot.	Checks whether /etc/fstab is correctly configured. Incorrect entries, such as a non-existent mount device or wrong UUID, can prevent boot.
`Grub`	`grub`	The system fails to boot.	Checks whether the GRUB configuration is correct. Errors, such as specifying a boot partition by device name instead of UUID, prevent boot.
`Dhcp`	`dhcp`	The system network connection fails.	Checks that DHCP is enabled for network interfaces. Static addressing may cause network failures. Add `net.ifnames=0` to the GRUB kernel boot parameters to disable interface renaming and keep the interface name as `eth0`.
`Selinux`	`selinux`	The ECS instance fails to boot.	Checks whether SELinux is disabled.
`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. 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 User Data script.
`SshConfig`	`sshd`	SSH connection to the instance fails.	Checks whether the sshd configuration file (/etc/ssh/sshd_config) is correct. If the sshd configuration file is incorrect, the sshd service may fail to start, preventing SSH connections. To check: Run `sudo sshd -T` to display all configuration options. Run `sudo sshd -t` to validate the file. No output means valid.
`Firewall`	`firewall`	The system firewall may block access to the instance.	Checks whether the firewall service is enabled. Disable the system firewall and use security groups to manage inbound and outbound traffic.
`CloudAssistant`	`assist`	Cloud O&M are inconvenient.	Checks whether Cloud Assistant is installed. Cloud Assistant is a native ECS automation tool for operations and maintenance.
`SecurityCenterAgent`	`aegis`	Instance vulnerabilities cannot be identified without Security Center protection.	Checks whether the Security Center agent is installed. Required for Security Center to protect the server.
`QemuGuestAgent`	`qemuguestagent`	Instance features may not work correctly.	Checks whether `qemu-guest-agent` is installed. This software communicates with the host machine, which can interfere with ECS services and leave instance functionality incomplete.
`Diskusage`	Not supported	The system fails to boot.	Checks whether disk space usage is normal. Run `df -h` to check disk space usage and ensure sufficient space.
`Inodeusage`	Not supported	The system fails to boot.	Checks whether disk inode usage is normal. Run `df -i` to check inode usage.
`SystemFileAttribute`	`fileattribute`	The instance fails to boot or functions abnormally.	Checks whether critical system configuration files have correct file attributes.
`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 abnormal boot or prevent remote connections.
`LibDirectory`	Not supported	The system functions abnormally.	In Red Hat series Linux, /lib and /lib64 are typically symbolic links to /usr/lib and /usr/lib64. Do not modify these links.
`SupportMocinstanceTypes`	Not supported	Cannot use SHENLONG instance families like `ecs.g6` and `ecs.g7` .	Checks whether the image supports 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. See Instance family overview.

Fix command reference

Syntax for the automatic fix command:

./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 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 attempt. Prints the fix script without executing it.
`[--debug]`	No	Enables detailed log output for troubleshooting.
`[-y]`	No	Skips interactive prompts and auto-confirms all fix steps.

References

After validation, obtain the image file and import it as a custom image.

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 corresponding to SshConfig.
Review:

To fix a different item, replace sshd with the target fix item name.
```
./main.sh --target=image --run sshd --dry-run 
```
Execute:
```
./main.sh --target=image --run sshd
```