Migrate a Linux WorkSpace to a different operating system

You can migrate an existing Linux WorkSpace to a different Linux operating system bundle while preserving the user's home directory, files, and data. Migration replaces the root volume (operating system) with a new bundle while keeping the user volume (/home) intact. This is different from a rebuild, which refreshes the root volume with the same OS bundle.

The Migrate WorkSpace feature handles the entire process automatically, including file ownership correction and desktop environment cleanup when needed.

Supported migration paths

The following table shows the supported source and target operating systems for Linux WorkSpace migration.

Amazon Linux 2 is a valid migration source but is not a valid migration target. Amazon Linux 2 has reached end-of-life and new WorkSpaces cannot be created with AL2 bundles.

All migration paths between Ubuntu, RHEL, and Rocky Linux are supported in both directions. You can upgrade (for example, RHEL 8 → RHEL 9), downgrade (for example, Ubuntu 24.04 → Ubuntu 22.04), and migrate across distribution families (for example, Rocky 9 → Ubuntu 24.04 or RHEL 9 → Rocky 8). The only restriction is that you cannot migrate a WorkSpace to the same bundle it is already using.

Migrations from Amazon Linux 2 require automatic user ID ownership correction and desktop environment cleanup. Migrations between all other distributions (Ubuntu, RHEL, Rocky) do not require ownership correction because these distributions all use SSSD for Active Directory integration, which assigns stable user IDs.

Prerequisites

Before migrating a Linux WorkSpace, verify the following:

How to migrate a WorkSpace

Using the AWS Management Console

Using the AWS CLI

Use the migrate-workspace command to migrate a WorkSpace to a different bundle:

aws workspaces migrate-workspace \
    --source-workspace-id ws-1234567890abcdef0 \
    --bundle-id wsb-jttwgmx20 \
    --region us-east-1

To find available target bundle IDs:

aws workspaces describe-workspace-bundles \
    --query 'Bundles[?contains(Name, `Ubuntu`) || contains(Name, `Rocky`) || contains(Name, `RHEL`)].{Name:Name,BundleId:BundleId}' \
    --output table

Monitoring migration status

Migration typically takes 20–30 minutes. Monitor the WorkSpace status:

aws workspaces describe-workspaces \
    --workspace-ids ws-1234567890abcdef0 \
    --query 'Workspaces[0].State' \
    --output text

The WorkSpace transitions through the following states: AVAILABLE → PENDING → AVAILABLE (on success) or ERROR (on failure). If migration fails during provisioning, the control plane automatically restores the original WorkSpace.

Post-migration verification

After migration completes, verify the following:

Check WorkSpace status

Confirm the WorkSpace is in AVAILABLE state in the AWS Console or via the CLI.

Verify user login

Have the user log in to the WorkSpace and confirm the desktop loads correctly.

Check the migration log

For AL2 migrations, review the migration log for details on what was changed:

cat ~/workspace-migration-log-*/user-id-migration.txt

This log shows the old and new user IDs, the number of files changed in each phase, and timestamps.

Check Phase 2 status

To verify whether the background migration has completed:

# Check if the Phase 2 service is still running
systemctl is-active ws-migrate-phase2.service 2>/dev/null

# "inactive" or "not found" means Phase 2 has completed
# "activating" means Phase 2 is still running (Type=simple service)

What happens during migration

When you initiate a migration, the following steps occur:

The user's home directory is stored on a separate EBS volume that is preserved across the migration. All files in /home/username survive the transition, including documents, SSH keys, shell configuration, and application data.

Migrating from Amazon Linux 2

Migrations from Amazon Linux 2 involve additional steps that are handled automatically. This section explains what happens and why.

Why AL2 migrations are different

Amazon Linux 2 uses Winbind for Active Directory integration, while all newer Linux distributions (Ubuntu, RHEL, Rocky) use SSSD. These two systems assign different POSIX user IDs to the same Active Directory user:

After migration, all files in the user's home directory are owned by the old Winbind UID. The user cannot access their own files until ownership is corrected to match the new SSSD UID.

Additionally, Amazon Linux 2 uses the MATE desktop environment (GNOME 2), while newer distributions use GNOME 3.x. MATE configuration files conflict with GNOME 3.x and must be cleaned up to ensure a working desktop.

Two-phase ownership correction

To avoid provisioning timeouts, ownership correction is split into two phases.

Phase 1 (during provisioning)

Fixes ownership on desktop-critical files needed for immediate login:

Phase 1 completes quickly regardless of the total home directory size, ensuring that provisioning never fails due to large home directories.

Phase 2 (background, after reboot)

Fixes ownership on all remaining files:

Desktop environment cleanup

During migration from AL2, the following MATE desktop configuration files are moved to a backup directory inside the migration log (~/workspace-migration-log-YYYYMMDD/removed-configuration/):

These files are not deleted — they are moved to the backup directory and can be recovered if needed. After cleanup, the desktop loads with the default GNOME 3.x appearance.

SELinux context restoration

When the migration target is RHEL or Rocky Linux, SELinux security contexts are always restored on the entire user home directory (/home/username), regardless of the source operating system. This applies to all migration paths that target an SELinux-enabled distribution, including:

In all cases, context restoration ensures that files have the correct security labels for the target distribution's SELinux policy.

Context restoration runs in two phases, matching the ownership correction:

RFC 2307 home directory auto-correction

Active Directory supports RFC 2307 attributes (also known as "Unix Attributes"), which allow administrators to specify POSIX user properties including the home directory path (unixHomeDirectory). SSSD respects this attribute, while Winbind on AL2 ignored it and always used /home/username.

When migrating from AL2 to an SSSD-based distribution, if the AD user object has unixHomeDirectory set to a different path (for example, /home/CORP/jsmith), SSSD resolves the user's home directory to that AD-specified path. Since the user's actual data lives at /home/username from the AL2 era, the AD-specified path does not exist on the volume.

The migration system detects this situation automatically:

This correction is permanent — the override_homedir setting persists in sssd.conf across reboots and future SSSD restarts.

Enabling RFC 2307 home directory paths after migration

If the migration auto-corrected the RFC 2307 home directory path and you want SSSD to respect the AD unixHomeDirectory attribute going forward, you can reverse the override. This is an advanced configuration change that should only be performed if you understand the implications.

To restore RFC 2307 home directory paths:

Step 1: Determine the AD-specified home directory path

# Query the AD unixHomeDirectory attribute
ldapsearch -H ldap://your-dc.example.com -b "dc=example,dc=com" \
    "(sAMAccountName=jsmith)" unixHomeDirectory

Step 2: Move the user's data to the AD-specified path

sudo mkdir -p /home/CORP
sudo mv /home/jsmith /home/CORP/jsmith

Step 3: Remove the override_homedir setting from /etc/sssd/sssd.conf

sudo sed -i '/^override_homedir/d' /etc/sssd/sssd.conf

Step 4: Restart SSSD

sudo systemctl restart sssd

Step 5: Verify the home directory resolves correctly

getent passwd jsmith
# Should show /home/CORP/jsmith as the home directory

User notifications

The migration system uses two notification mechanisms to keep the user informed:

If the user is not connected (for example, an auto-stop WorkSpace that hasn't been accessed), Phase 2 runs silently without error.

Migrating between modern distributions

Migrations between Ubuntu, RHEL, and Rocky Linux distributions do not require user ID ownership correction. All of these distributions use SSSD for Active Directory integration, which assigns stable user IDs derived from the AD SID. The user's files retain correct ownership across the migration.

Common migration paths in this category include:

For migrations to RHEL or Rocky Linux targets, SELinux context restoration always runs to ensure files have the correct security labels for the target distribution's SELinux policy. This applies regardless of the source distribution. For files that already have correct labels, the restoration is a no-op.

What users keep and what changes

What is preserved

What changes

Auto-stop and always-on WorkSpaces

Auto-stop WorkSpaces

For WorkSpaces configured with auto-stop (hibernate after idle timeout):

Always-on WorkSpaces

For always-on WorkSpaces:

Known limitations

Troubleshooting

Migration fails during provisioning

If the migration fails and the WorkSpace returns to ERROR state, the control plane automatically attempts to restore the original WorkSpace. Check the provisioning logs:

# Connect to the WorkSpace (if accessible) and check the domain-join log
sudo cat /var/log/skylight/domain-join.log

Common causes:

User cannot log in after migration

Desktop appears broken or has wrong theme

This typically occurs when migrating from AL2 and some MATE configuration files were not cleaned up. To reset the desktop to defaults:

# Remove remaining desktop configuration
rm -rf ~/.config/dconf/user
rm -rf ~/.gconf

# Log out and log back in

Files have wrong ownership after migration

If files in the home directory are inaccessible after an AL2 migration, Phase 2 may still be running:

# Check Phase 2 status
systemctl is-active ws-migrate-phase2.service 2>/dev/null

# Check the migration log for progress
cat ~/workspace-migration-log-*/user-id-migration.txt

If Phase 2 has completed but some files still have incorrect ownership, you can manually fix them:

# Find files with the old UID and change ownership
sudo find /home/username -uid old-uid -exec chown username {} +
sudo find /home/username -gid old-gid -exec chgrp username {} +

Log file locations