Moving a Guest Using Automated Offline Migration

6.18.1 Moving a Guest Using Automated Offline Migration

You can use the Oracle Exadata Deployment Assistant (OEDA) Command Line Utility (OEDACLI) to migrate an Oracle Linux KVM guest to another KVM host.

During the automated migration process, the guest is shut down, moved to the new KVM host, and then restarted. Because the guest shuts down, this method is also known as offline migration.

The following requirements apply to automated offline guest migration using OEDACLI:

The Exadata system must use 2-socket Oracle Exadata system hardware with RoCE Network Fabric (X8M-2 or later).
The Exadata system must use Oracle Exadata System Software release 25.1.0 or later.
You must have an OEDA-generated Engineered System XML configuration file (es.xml) that accurately reflects the current state of the Exadata system.
The Exadata system must be configured to use Exascale storage to host the guest image files.
The environment must be configured with SSH equivalency, so that the OS user and the server running OEDACLI can perform actions as the root user on both the source and target KVM hosts.
The source and target KVM hosts must reside in the same Exadata system configuration and have the same network visibility.
The source and target KVM hosts must have access to the same Oracle Exadata storage servers.
The source and target KVM hosts must not have any outstanding work from a previous Exadata Live Update.
The target KVM host must use Oracle Exadata System Software packages that are the same version as, or newer than, those on the source KVM host.
The target KVM host must have sufficient free CPU and memory resources to accommodate the guest.
- It is possible to over-commit virtual CPUs such that the total number of virtual CPUs assigned to all guests exceeds the number of physical CPUs on the system. Over-committing CPUs can be done only when the competing workloads for over-subscribed resources are well understood and the concurrent demand does not exceed physical capacity.
- It is not possible to over-commit memory.
The guest being migrated must not have any outstanding work from a previous Exadata Live Update operation that could be applied when the guest restarts during the migration process. Either clear all outstanding work before migration, or reconfigure the guest so that no outstanding work occurs during the migration process.

See About Exadata Live Update and Patchmgr Syntax for Database Servers.
The guest name must not already be in use on the target KVM host.

To perform an automated guest migration using OEDACLI:

Start OEDACLI and load the Engineered System XML configuration file (es.xml).
For example:
```
# ./oedacli
oedacli> LOAD FILE name=exa01.xml
```
Use the MIGRATE GUEST command to specify the migration parameters.
The essential command syntax is:
```
oedacli> MIGRATE GUEST HOSTNAME=guest_name MODE={OFFLINE|OFFLINEFORCE} SRCHOST=source_host TGTHOST=target_host
```
In the command:
- HOSTNAME=guest_name: Specifies the hostname of the guest being migrated.
- MODE={OFFLINE|OFFLINEFORCE}: Specifies the migration mode:
  - MODE=OFFLINE: Performs an automated migration process where the guest is gracefully shut down, moved to the target KVM host, and then restarted.
    
    Use this option in most situations to gracefully migrate a working guest.
  - MODE=OFFLINEFORCE: Performs a forced migration process without gracefully shutting down the guest.
    
    Use this option only in situations where the guest or source KVM host are not accessible. For example, to resurrect a guest from a failed KVM host.
- SRCHOST=source_host: Specifies the name of the source KVM host, where the guest currently resides.
- TGTHOST=target_host: Specifies the name of the target KVM host, where the guest will reside after the migration completes.
For example, the following command specifies the parameters for an automated migration process where the guest named exa01vm01.example.com is being gracefully moved from exa01adm02.example.com to exa01adm06.example.com.
```
oedacli> MIGRATE GUEST HOSTNAME=exa01vm01.example.com MODE=OFFLINE SRCHOST=exa01adm02.example.com TGTHOST=exa01adm06.example.com
```
Save and merge the actions defined by the MIGRATE GUEST command.
```
oedacli> SAVE ACTION
oedacli> MERGE ACTIONS
...
Merging MIGRATE GUEST
Action Validated and Merged OK
```
Examine the output from the MERGE command and proceed only if the action validated and merged OK.
Save a copy of the Engineered System XML configuration file (es.xml).

Saving the file at this point persists the XML configuration with the migration information marked in a pre-deployed state. You can save the file in this state using a distinctive file name to keep track of your changes.
```
oedacli> SAVE FILE NAME=exa01.migration-merged.xml
File : exa01.migration-merged.xml saved OK
```

Deploy the actions defined by the MIGRATE GUEST command.

oedacli> DEPLOY ACTIONS

The DEPLOY ACTIONS command instructs OEDACLI to perform the migration. This is time when the guest is actually moved to the target KVM host.

The migration process is performed using a series of well-defined steps. The following list shows the order of the migration steps for an offline migration.

STOP_GUEST
CREATE_BRIDGES
DETACH_INTERFACES
DETACH_VOLUMES
ATTACH_VOLUMES
MIGRATE_GUEST
ATTACH_INTERFACES
STARTUP_GUEST

The output in the OEDACLI session shows various status messages and also reports when each step is completed. This enables you to monitor the migration process.

The following shows example output from a typical migration session.

oedacli> DEPLOY ACTIONS
Deploying Action ID : 28 migrate guest hostname=exa01vm01.example.com mode=offline srchost=exa01adm02.example.com tgthost=exa01adm06.example.com
Deploying MIGRATE GUEST
Migrate Guest
Starting Guest Migration : exa01vm01.example.com
Stopping Guest exa01vm01.example.com on KVM host exa01adm02.example.com
Waiting for node : exa01vm01.example.com to be stopped
exa01vm01.example.com is down
exa01vm01.example.com is Down
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step STOP_GUEST completed successfully...
Detaching Network Interfaces for Guest : exa01vm01.example.com on KVM host exa01adm02.example.com
VF POOLS in use in kvmHost exa01adm02.example.com. No need to detach re* interfaces
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step DETACH_INTERFACES completed successfully...
Detaching Exascale Volumes for Guest : exa01vm01.example.com on KVM host exa01adm02.example.com
Unmounting Guest Configuration Files volume /dev/exc/exa01vm01_cfg_82abd35b3cb04643848b556c31e8903f for guest exa01vm01.example.com on kvmhost exa01adm02.example.com.
Removing Guest Configuration Volume entry /dev/exc/exa01vm01_cfg_82abd35b3cb04643848b556c31e8903f for guest exa01vm01.example.com from fstab on kvmhost exa01adm02.example.com.
Removing Guest Configuration Files directory /EXAVMIMAGES/GuestImages/exa01vm01.example.com for guest exa01vm01.example.com on kvmhost exa01adm02.example.com.
Detaching EDV Volume exa01vm01_sys from KVM host exa01adm02.example.com
Detaching EDV Volume exa01vm01_cfg from KVM host exa01adm02.example.com
Detaching EDV Volume exa01vm01_gih01 from KVM host exa01adm02.example.com
Detaching EDV Volume exa01vm01_dbh01 from KVM host exa01adm02.example.com
Detaching EDV Volume exa01vm01_u01 from KVM host exa01adm02.example.com
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step DETACH_VOLUMES completed successfully...
Attaching Exascale volumes for Guest : exa01vm01.example.com on KVM host exa01adm06.example.com
Attaching EDV Volume exa01vm01_sys using device exa01vm01_sys_95d9f89aeacf4e7f8997972b2e1354ff to host exa01adm06.example.com
Attaching EDV Volume exa01vm01_cfg using device exa01vm01_cfg_82abd35b3cb04643848b556c31e8903f to host exa01adm06.example.com
Attaching EDV Volume exa01vm01_gih01 using device exa01vm01_gih01_5ea0689d6e4f4eedbde29fcf3f9f618d to host exa01adm06.example.com
Attaching EDV Volume exa01vm01_dbh01 using device exa01vm01_dbh01_95370e3d9cfe49639c8943a659137265 to host exa01adm06.example.com
Attaching EDV Volume exa01vm01_u01 using device exa01vm01_u01_0b66086a58474595a3d2f00b1bd7bb63 to host exa01adm06.example.com
Mounting Guest Configuration Files volume /dev/exc/exa01vm01_cfg_82abd35b3cb04643848b556c31e8903f for guest exa01vm01.example.com on kvmhost exa01adm06.example.com.
Adding Guest Configuration Volume entry /dev/exc/exa01vm01_cfg_82abd35b3cb04643848b556c31e8903f for guest exa01vm01.example.com to fstab on kvmhost exa01adm06.example.com.
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step ATTACH_VOLUMES completed successfully...
Creating Network Bridge for Guest : exa01vm01.example.com on KVM host exa01adm06.example.com
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step CREATE_BRIDGES completed successfully...
Migrating Guest exa01vm01.example.com from KVM host exa01adm02.example.com to  KVM host exa01adm06.example.com
Enabling autostart for guest exa01vm01.example.com on kvm host exa01adm06.example.com
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step MIGRATE_GUEST completed successfully...
Removing Network Bridges for Guest : exa01vm01.example.com on KVM host exa01adm02.example.com
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step REMOVE_BRIDGES completed successfully...
Skipping NAT bridge removal since this is not a cloud deployment...
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step REMOVE_NAT_BRIDGE_SRC completed successfully...
Skipping NAT bridge creation since this is not a cloud deployment...
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step CREATE_NAT_BRIDGE_TGT completed successfully...
Attaching Network Interfaces for Guest : exa01vm01.example.com on KVM host exa01adm06.example.com
VF POOLS in use in kvmHost exa01adm06.example.com. No need to attach re* interfaces. Proceeding with other post-mgration tasks.
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step ATTACH_INTERFACES completed successfully...
Starting Guest exa01vm01.example.com on KVM host exa01adm06.example.com
Waiting for node : exa01vm01.example.com to be ready
Migrate guest exa01vm01.example.com from exa01adm02.example.com to exa01adm06.example.com. Step STARTUP_GUEST completed successfully...
Done...
Done [Elapsed = 193346 mS [3.0 minutes] Wed Jul 30 16:14:59 PDT 2025]]

If the migration process does not complete for any reason, examine the OEDACLI output to determine the cause. After resolving the issue, you can complete the migration by performing the remaining steps, one at a time, remembering to start with the step that previously failed.

To perform a single step, specify the MIGRATE GUEST command with a WHERE clause to identify the step name. Then save, merge, and deploy the action. For example:

oedacli> MIGRATE GUEST HOSTNAME=exa01vm01.example.com MODE=OFFLINE SRCHOST=exa01adm02.example.com TGTHOST=exa01adm06.example.com WHERE STEPNAME=STARTUP_GUEST
oedacli> SAVE ACTION
oedacli> MERGE ACTIONS
oedacli> DEPLOY ACTIONS

Save the Engineered System XML configuration file (es.xml).

Saving the XML configuration file at this point persists the configuration change and ensures that the file reflects the system configuration following the completion of the migration. You can save the file using a distinctive file name to keep track of your changes.
```
oedacli> SAVE FILE NAME=exa01.migration-deployed.xml
File : exa01.migration-deployed.xml saved OK
```

Related Topics

MIGRATE GUEST

Parent topic: Moving a Guest to a Different KVM Host