All Products
Search

This Product

    Elastic Compute Service:Check and fix images with sersi

    Document Center

    Elastic Compute Service:Check and fix images with sersi

    Last Updated:Aug 26, 2026

    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

    1. Download the sersi package.

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

    2. 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.

    1. Scan the image.

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

    2. 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-18.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]
CloudInitConfigPassword                                                                [OK]
SecurityCenterAgent                                                                    [OK]
SupportMocInstanceTypes                                                                [OK]
DiskUsage                                                                              [OK]
InodeUsage                                                                             [OK]
SystemFileAttribute                                                                    [OK]
CriticalUser                                                                           [OK]
QemuGuestAgent                                                                         [OK]
SshConfig                                                                              [OK]
Firewall                                                                               [OK]

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

Import Image Command Example (aliyun CLI)
------------------------------------------------------------
Based on the detected system information, you can use the
following command to import this image via Alibaba Cloud CLI:

aliyun ecs ImportImage \
  --RegionId <your-region-id> \
  --ImageName <your-image-name> \
  --Architecture x86_64    # [!] auto-detected, verify it matches your image \
  --OSType linux \
  --Platform 'Aliyun'  # [!] auto-detected, must match OS distribution \
  --BootMode BIOS    # [!] auto-detected, wrong value causes boot failure \
  --DiskDeviceMapping.1.OSSBucket <your-oss-bucket> \
  --DiskDeviceMapping.1.OSSObject '<your-oss-object-path>' \
  --DiskDeviceMapping.1.Format <RAW|VHD|QCOW2>

NOTE: Replace <...> placeholders with your actual values.
  - RegionId must match the OSS Bucket's region.
  - Format: RAW, VHD, or QCOW2 (matches your image file format).
------------------------------------------------------------

    3. Verify the image import parameters. The Import Image Command Example section at the end of the report generates a sample aliyun CLI command for importing the image, based on the detected system information. Parameters marked with [!] are auto-detected. Verify each one before importing, because values that do not match the actual image cause instances created from the image to fail to boot.

      • --Architecture: The system architecture of the image. Valid values: x86_64 and arm64.

      • --Platform: The operating system distribution of the image. It must match the system actually installed in the image. If the operating system of your image is a Platform that the image import parameters do not support, the check report recommends a suitable Platform. For Red Hat-based distributions such as openEuler and openCloudOS, we recommend that you set Platform to CentOS Stream.

      • --BootMode: The boot mode of the image. Valid values: BIOS and UEFI. A value that does not match the actual boot mode prevents the instance from booting.

      For the full description of each parameter, see Import a custom image.

    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.

    1. 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

    2. 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

    3. 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.

    Step 4: Verify the fix

    1. (Optional) Reboot the system. Some fixes (Nvme, Dhcp, Selinux) require a reboot.

    2. 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 / CloudInitConfigPassword

    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:

    1. In the Overview of check and fix items table, find the fix item sshd corresponding to SshConfig.

    2. Review:

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

    3. Execute:

      ./main.sh --target=image --run sshd