Overview
Assist with Huawei Cloud SMS (Server Migration Service) host migration operations. Main steps are as follows:
-
High-risk operation prohibition list — Keep in mind operations that absolutely must not be performed during migration
-
Pre-migration checks — Network connectivity, source resource levels, disk/OS compatibility
-
API migration process — Complete hcloud CLI + SMS API process
-
Post-migration startup repair — If the source uses UEFI, use helper ecs to replace the kernel with BIOS, network configuration, password injection
-
Post-migration verification — Consistency comparison between target and source
-
Common errors and fixes — Practical pitfalls (SMS.0515/SMS.0007/SMS.6562 etc.) If an error occurs during migration, first refer to
references/MIGRATION_REFERENCE.mderror catalog, and solutions
Core principles
Without modifying any source information, safely copy the source data as-is to the target.
- Source protection first — Source is strictly read-only; any addition, deletion, or modification is prohibited
- Data integrity — All source data is completely copied to the target
- Create target strictly according to input — No deviation or changes allowed
- Source business unchanged — The source business state remains unchanged during migration
- Naming rules mandatory — All newly created target ECS must be named according to
{hostname}_{MMDD}naming
Most critical risk point: source protection
During migration, the source must be strictly read-only. Any addition, deletion, or modification operation will lead to fatal consequences.
- Prohibited: database writes, file upload/modification/deletion, log clearing/addition, configuration changes, application restart, software installation, user addition/modification, permission changes, disk partition adjustment
- Consequences: source business paralysis + migration failure + target data inconsistency + unrecoverable
- Agent must: regularly check source disk/database/log size; if any change is found, immediately stop migration, roll back, and notify the user
1. Prohibited high-risk operations
Level 1: Data loss or migration failure (absolutely prohibited)
Source protection
| No. | Prohibited operation |
|---|---|
| 01 | During migration, on the sourceany addition, deletion, or modification |
| 02 | During migration, sourcedisk adjustment |
| 03 | Shut down source SMS-Agent |
| 04 | Shut down source IO monitoring |
| 05 | After cutovernew data on source |
Target protection
| No. | Prohibited operation |
|---|---|
| 06 | Targetswitch operating system |
| 07 | Targetreinstall system |
| 08 | Targetdisk operations |
| 09 | When not completedsystem reinstall/switch |
| 10 | Before cutovernew data on target |
Other key operations
| No. | Prohibited operation |
|---|---|
| 11 | When not completedDelete migration task |
| 12 | Creating/new EIPs is prohibited(at any stage); when an EIP is needed,the user manually creates it in the console, and you only use existing EIPs.Exception: in the post-migration repair process, the temporary EIP for creating a helper ECS is allowed to be created by the Agent, and must be released immediately after the repair is complete |
| 12a | Network typeNon-EIP(VPN/dedicated line) casesCreating new EIPs is prohibited, and attaching/binding an EIP to the destination ECS is prohibited; in the template,passing any --template.publicip.* parameter is prohibited; after migration,you must check for and release EIPs automatically created by SMS |
| 13 | Adding, deleting, or modifying the Huawei Cloud AK/SK recorded on the host you are on is prohibited |
Level 2: Migration issues or additional costs
| No. | Prohibited operations |
|---|---|
| 14 | Starting migration with CPU usage ≥ 80% |
| 15 | Starting migration with available memory ≤ 256MB |
| 16 | More than 23 disks |
| 17 | Linux disk > 16TB |
| 18 | Migrating more than 200 at the same time |
| 19 | More than 1000 per user |
| 20 | BitLocker-encrypted Windows |
| 21 | AD domain controller/multi-node database |
| 22 | RAID disk array |
| 23 | Nested LVM system |
| 24 | LVM thin volume |
| 25 | Security group open to 0.0.0.0/0 |
| 26 | Security group open to non-essential ports |
| 27 | Usinga private imageinstead of a public image |
| 28 | Destination specifications < source (downsizing) |
Level 3: Note
| No. | Notes |
|---|---|
| 29 | OS/application License may become invalid (SID/MAC changes) |
| 30 | NIC configuration may need manual adjustment |
| 31 | GPU servers need drivers reinstalled |
| 32 | Shared file systems will not be migrated |
| 33 | Unmounted/uninitialized disks will not be migrated |
| 34 | Temporary disks are automatically deleted after migration is complete |
II. Pre-migration checks
1. 迁移前检查 → python3 scripts/pre_migration_check.py --input migration_hosts.json
III. SMS Agent installation
### 源端安装。如果以下目录里已有SMS Agent, 跳过安装步骤，请勿重复安装。
cd /root/SMS-Agent && bash ./startup.sh
### 交互输入：y / y / <AK> / <SK> / sms_domain / 0
If this is the first installation, enter the sms_domain string in step 5; on restart, enter y to confirm. Entering it incorrectly will cause an infinite loop.
For the detailed interaction sequence, non-interactive installation, and verification methods, see references/MIGRATION_REFERENCE.md Section A.
IV. SMS API migration process
4.1 Process overview
1. 解析 'migration_hosts.json' → 源端信息 vs 目的端信息
2. 查询目的端资源（VPC/子网/安全组/规格/镜像）
3. 创建模板（CreateTemplate）— 含 target_password
4. 创建任务（CreateTask）— 三个关键参数！
5. 启动（UpdateTaskStatus --operation=start）
6. 轮询（ShowTask）→ MIGRATE_SUCCESS
7. （跳过）割接（--operation=cutover）— 不允许割接或者删除源端主机。任务停留在割接前这一步，直到用户手动启动割接
8. 迁移后启动修复（第七节）— 如果主机无法启动，进行修复
9. 迁移后校验
If the task is deleted, the migration Template must be recreated before the next task is rebuilt
Input data strictness: the destination must be created according to the 'migration_hosts' JSON; modification or guessing is prohibited. If in doubt,ask the user first。
4.2 Network types and EIP rules
| Excel network type | Template configuration | EIP rules |
|---|---|---|
| VPN/dedicated line | Private network,do not pass any --template.publicip.* parameter in the template |
Creating new EIPs is prohibited, and attaching EIPs is prohibited(12a); after migration, check for and release EIPs automatically created by SMS |
| EIP | Public network, configure public eip | Query existing EIP attachments;creating new ones is prohibited(12), and the user was not notified to create one manually |
⚠️ VPN/Dedicated Line network type EIP rules (mandatory; violation is non-compliance)
When
migration_hoststhe network type is VPN/Dedicated Line :
- When creating a template (CreateTemplate), it is prohibited to pass in
--template.publicip.type/--template.publicip.bandwidth_sizeor any other publicip parameter — the SMS service will automatically create an EIP based on this and bind it to the destination ECS, violating the security requirement that public network access is not allowed for the VPN network type- After migration is complete (after MIGRATE_SUCCESS), you must check whether each destination ECS has a floating IP bound to it — even if the template is not configured with publicip, SMS may still automatically create an EIP for intermediate transfer in cross-cloud migration scenarios
- If a destination ECS is found to have a floating IP, it must be unbound and released immediately：
# 解绑 EIP hcloud EIP DisassociatePublicips --cli-region=<region> --publicip_id=<eip_id> # 释放 EIP hcloud EIP DeletePublicip --cli-region=<region> --publicip_id=<eip_id>- This rule applies to the entire migration lifecycle: template creation, task execution, post-migration remediation, and cleanup phases; if an EIP is found in a VPN scenario at any phase, it must be cleaned up
- Root cause: hosts with the VPN/Dedicated Line network type communicate with the internal network over the private network; a public EIP exposes the attack surface and violates network security isolation requirements
4.3 Create a template (CreateTemplate) — key required parameters
| Parameter | Error code when missing |
|---|---|
| vpc.id + vpc.cidr | SMS.0007 |
| nics.1.id + name + cidr | SMS.6102 |
| security_groups.1.id + name | SMS.6102 |
| image_id (consistent with the source OS, public image) | SMS.0007 vols_map |
| publicip.type + bandwidth_size（Only for EIP scenarios; prohibited in VPN/Dedicated Line scenarios) | SMS.6562 |
| is_template=true | The template is cascade-deleted |
| target_password | See the explanation below |
target_password the truth: this parameter sets the password when SMS creates the intermediate ECS. However, after the full-disk migration is complete, the source disk's /etc/shadow will overwrite the intermediate ECS's password — the password on the final migrated disk is the source's, not target_password the value set. Therefore, the password must be reset in the post-migration remediation script (see remediation item 6 in Section 7).
For the complete command, see references/MIGRATION_REFERENCE.md Section C.3.
4.4 Create a task (CreateTask) — all three key parameters are indispensable
| Parameter | Purpose | Consequence if omitted |
|---|---|---|
--syncing=false |
Skip incremental synchronization | 80% report vols_map NoneType |
--use_public_ip=false |
Private network connection Agent | 80% report exception 22 |
--target_server.disks.1.disk_id=<src_disk_id> |
Disk mapping | vols_map None |
Disk information source:hcloud SMS ShowServer the returned disks.
Naming of newly created destination ECS：--target_server.name={hostname}_{MMDD}(see the naming rules below).
All ECSs created through the SMS API or the remediation process use the naming format:
{hostname}_{MMDD}
| Example | Description |
|---|---|
server-01_0824 |
server-01 created on 2026-08-24 |
server-02_0824 |
server-02 created on 2026-08-24 |
Rules:
{hostname}= the destination hostname in Excel/JSON (e.g.,server-01）- Timestamp = the
date +%m%d - Auxiliary ECSs also carry a timestamp：
helper_{MMDD} - Prohibitedto use
ecs-boot-fix、helper-ecsand other names without a timestamp - Filenames uploaded to OBS carry a more detailed timestamp {YYYYMMDD_HHMMSS}
- SMS task names may omit the timestamp; simply name the task after the source hostname
For the complete command, see references/MIGRATION_REFERENCE.md Section C.4.
4.5 Task Status Transitions
READY → RUNNING → MIGRATE_FAIL / SYNCING / CUTOVER_READY
子任务：CREATE_CLOUD_SERVER → SSL_CONFIG → ATTACH_AGENT_IMAGE → FORMAT_DISK_LINUX_FILE → MIGRATE_LINUX_FILE
V. Post-Migration Verification
- No write operations on the source: Compare df -h, database/log sizes, and mtime before and after migration
- Destination specifications match (CPU/memory/disk) / OS version matches / network connectivity / application startup
- VPN/dedicated line scenario: destination ECS has no floating IP(see EIP rules in Section 4.2)
For detailed verification commands, see
references/MIGRATION_REFERENCE.mdSection D.
VI. Common Errors Quick Reference
| Error | One-line fix |
|---|---|
| SMS.0515 | Extract complete disk information from ShowServer and pass it to CreateTask |
| SMS.0007 vpc | Rebuild the template (vpc.id + vpc.cidr) |
| SMS.0007 vols_map | Specify in the template a public image matching the source OS |
| SMS.6562 | Add publicip.type=5_bgp to the template (EIP scenario only; for VPN scenario see Section 4.2) |
| SMS.6102 | Complete the name/cidr for nics/security_groups |
| Source error | kill Agent, restart startup.sh (restart input sequence) |
For the complete error catalog, see
references/MIGRATION_REFERENCE.mdSection E.
VII. Post-Migration Startup Repair
MIGRATE_SUCCESS does not mean the ECS is usable. After migrating AWS Ubuntu to Huawei Cloud, you typically encounter 5 overlapping issues：
| # | Issue | Root cause | Consequence if not fixed |
|---|---|---|---|
| 1 | The source uses UEFI, Huawei Cloud only supports BIOS, ECS boot does not match | AWS uses UEFI, Huawei Cloud ECS uses BIOS | ECS completely fails to boot |
| 2 | AWS kernel is incompatible | The source kernel (e.g., vmlinuz-7.0.0-1010-aws) does not boot on Huawei Cloud virtual hardware |
Halts upon booting to the kernel, no logs |
| 3 | Residual network configuration | netplan is configured with AWS static IP + NIC name ens5; cloud-init uses DataSourceEc2Local | NIC has no IP, SSH unreachable |
| 4 | root password is not the expected value | Full-disk migration preserves the source /etc/shadow，target_password is overwritten |
Unable to log in |
| 5 | grub.d overwrites kernel parameters | 50-cloudimg-settings.cfg overwrites GRUB_CMDLINE_LINUX_DEFAULT，net.ifnames=0 is lost |
NIC name is incorrect |
Indicators
ECS ACTIVE + ARP has MAC + ping fails + SSH timeout → repair needed
Repair process (9 steps)
| Step | Operation |
|---|---|
| 1 | Stop the destination ECS (HARD) |
| 2 | Detach the system disk (NovaDetachVolume) |
| 3 | Create an auxiliary ECS (same VPC), named helper_{MMDD}, restart once after creation to make the password take effect |
| 4 | Attach the migrated disk to the auxiliary ECS (/dev/vdb) |
| 5 | Run the repair script(see the 9 repair items below) |
| 6 | Detach the disk → attach it back to the destination /dev/vda → start the ECS |
| 7 | Verify: ping + SSH + ip addr show |
| 8 | If still unreachable: Check the serial console output to distinguish GRUB errors vs kernel panic |
| 9 | After confirming login is possible, set the root password to the user's expected value |
Repair script core (Step 5) — 9 repair items
On the auxiliary ECS, chroot into the migration disk and execute:
| # | Repair item | Specific operation |
|---|---|---|
| 1 | Install BIOS GRUB | Create bios_grub partition + grub-install --target=i386-pc /dev/vdb |
| 2 | Replace AWS kernel | Copy from auxiliary ECS vmlinuz-*generic + initrd.img-*generic + /lib/modules/*generic to migration disk; update grub |
| 3 | Repair netplan | Write eth0: {dhcp4: true}; add net.ifnames=0 kernel parameter |
| 4 | Create 99-net-ifnames.cfg | In /etc/default/grub.d/ create a high-priority file to prevent 50-cloudimg-settings.cfg from overriding |
| 5 | Disable cloud-init network configuration | Disable DataSourceEc2Local; set datasource_list: [None] or directly disable cloud-init |
| 6 | Set root password | `echo 'root:<expected_password>' |
| 7 | Update grub | update-grub(Note: only update grub.cfg, do not reinstall the bootloader) |
| 8 | Rebuild initramfs | update-initramfs -u -k all |
| 9 | Enable SSH password login | PasswordAuthentication yes + PermitRootLogin yes in sshd_config |
For the complete script, see
references/MIGRATION_REFERENCE.mdSection G.
Secure Boot considerations
Huawei Cloud ECS may have Secure Boot enabled (Ubuntu 24.04 image). In this case:
grub-installgeneratesunsigned EFI binary, Secure Boot will reject it → silent halt- Solution: install the
grub-efi-amd64-signedpackage (DNS must be available inside chroot), or disable Secure Boot through the Huawei Cloud console - BIOS mode (i386-pc) is not affected by Secure Boot; prefer using BIOS GRUB
Root causes of repair items
| Repair item | Consequence if not repaired |
|---|---|
| BIOS GRUB | ECS cannot boot (a disk written with UEFI boot does not work on a BIOS ECS) |
| Replace AWS kernel | ECS halts as soon as it boots to the kernel, with no serial output |
| netplan DHCP | NIC has no IP |
| 99-net-ifnames.cfg | net.ifnames=0 is overridden by 50-cloudimg, NIC name is incorrect |
| Disable cloud-init network | cloud-init overrides netplan with AWS DataSource |
| Set root password | Full-disk migration preserves the source password, and the user cannot log in with the expected password |
| SSH password login | Only key login is available, and the user cannot log in with a password |
Eight, Cleanup strategy after migration is complete
Do not delete the SMS migration tasks and templates on the Huawei Cloud console.
| Resource | After migration is complete |
|---|---|
| Auxiliary ECS | Can be deleted |
| Destination EIP (VPN/direct connection scenario) | Must be unbound and released — SMS may create it automatically, and it must be cleaned up after migration (see Section 4.2) |
| Source SMS Agent | Can be uninstalled; before uninstalling, ask the user whether to uninstall. If the user answers no, keep the SMS Agent |
| SMS migration task | Do not delete |
| SMS template | Do not delete |
Nine, Complete migration process quick reference
1. 安装 SMS Agent（源端）
└─ startup.sh：y / y / AK / SK / sms_domain / 0
2. 获取源端信息
└─ ListServers → source_server_id
└─ ShowServer → disk_id, disk_size, pv_uuid, pv_size
3. 创建模板（CreateTemplate）
└─ 必填：vpc.id + cidr + nics + security_groups + image_id + publicip + is_template + target_password
└─ target_password 全盘迁移后会被源盘覆盖，需在修复脚本中重设
4. 创建任务（CreateTask）— 三个关键参数！
└─ --syncing=false / --use_public_ip=false / --disks.1.disk_id=<src_disk_id>
└─ ECS 命名：{hostname}_{MMDD}
5. 启动任务（UpdateTaskStatus --operation=start）
6. 轮询状态（ShowTask）→ MIGRATE_SUCCESS
7. 如果主机无法ping通，迁移后修复（第七节）
└─ BIOS GRUB + 替换内核 + netplan(DHCP) + 99-net-ifnames.cfg + 禁用cloud-init + 设密码 + SSH
8. 清理（第八节）
└─ 删辅助 ECS
└─ 不删 SMS 任务和模板
└─ VPN/专线场景：检查并释放目的端 ECS 的 EIP（见 4.2 节）
9. 检查目的端ECS是否根据ECS命名规则进行命名，如果不是，重新根据命名规则修改目的端ECS名称
X. Prerequisites
- Python 3.6+ / hcloud CLI configured with AK/SK and region
- Pre-migration check requires access to the source network / post-migration verification requires access to the destination network
- Destination VPC/subnet/security group information is obtained from the Excel sheet
- Any questions must first be asked to the user; create the migration task only after confirmation
File Structure
sms-migration-assistant/
├── SKILL.md ← 本文件（流程概览 + 禁止操作 + 关键参数）
├── references/
│ └── MIGRATION_REFERENCE.md ← 详细命令、脚本、错误目录、格式规范
├── scripts/
│ ├── pre_migration_check.py ← 迁移前检查
│ └── post_migration_check.py ← 迁移后校验
input: migration_hosts.json Source hostname: server-01 Source host private IP: 172.196.0.134 Source system disk size: 8GB Source data disk size: 0 (if it is 0, or this input is absent, no additional data disk needs to be created) Port number: 22 Username: ubuntu Key file name: server-01key.pem Source region id: ap-southeast-1 Source region name: Singapore Source OS: ubuntu Network type: VPN Destination hostname: server-01-{timestamp} Destination system disk size: 40GB (the destination system disk must be at least the same as or larger than the source system disk) Destination data disk size: 0 Destination region id: ap-southeast-3 Destination VPC name: vpc-agent-84346077 Destination subnet name: subnet-migration Destination subnet CIDR: 192.168.3.0/24 Migrate to an existing host?: No
migration template: Name: AgentMigration Region/Project: ap-southeast-3 Migration Method: File-level Network: Private Target Server: create new Start Target Upon Launch: Yes
server template: Template Name: AgentTemplate Region/Project: ap-southeast-3 AZ: AZ1 Disk: General purpose SSD VPC: vpc-agent-84346077 Subnet: subnet-migration Security group: sg-agent-84346077