Skip to main content

​
Overview

Rescue mode boots an instance from a clean rescue image, attaching the original root disk as a secondary block device. This provides access to a functional environment from which you can repair the original OS — reset credentials, fix a corrupted filesystem, restore a misconfigured /etc/fstab, or retrieve critical files.
Prerequisites
  • An instance that is failing to boot or is inaccessible
  • A rescue image available in the Xloud Image Service (or use the platform default)
  • member or admin role in the project
  • CLI users: Xloud CLI configured and credentials sourced

​
When to Use Rescue Mode

If SSH keys were accidentally removed, the SSH daemon is misconfigured, or sshd fails to start, rescue mode provides an alternate path in. Mount the original disk inside rescue, restore ~/.ssh/authorized_keys or fix /etc/ssh/sshd_config, then exit rescue to resume normal operation.
Boot failures caused by a corrupted filesystem, a bad kernel, or a misconfigured bootloader can be diagnosed and repaired from the rescue environment. Run fsck, restore a previous kernel entry, or reinstall the bootloader.
An incorrect entry in /etc/fstab (wrong UUID, missing nofail flag on optional mounts) will cause the OS to hang at boot. Mount the original disk in rescue mode, correct the /etc/fstab entry, and exit rescue.
If an instance is otherwise healthy but cannot be accessed (e.g., broken network configuration), rescue mode lets you mount the original disk and copy critical files out before rebuilding.

​
Enter Rescue Mode

Initiate rescue

Navigate to Project → Compute → Instances. In the instance row, open the Actions dropdown and select Rescue Instance.

Select a rescue image (optional)

In the Rescue Instance dialog:
FieldDescription
Rescue ImageSelect a specific rescue image, or leave blank to use the platform default
Click Rescue Instance.
Use a rescue image that matches the guest OS architecture (x86_64) and is a minimal distribution (e.g., Ubuntu Server minimal, Alpine Linux). Avoid using desktop or full-featured images as rescue images.

Connect to the rescue environment

Once the instance enters Rescue status, connect via SSH using the rescue image’s default credentials or the injected key pair.The original root disk is attached as a secondary device (typically /dev/vdb). Mount it to access the original filesystem:
Mount the original root partition inside rescue
sudo mount /dev/vdb1 /mnt
For a chroot environment to run tools against the original OS:
Chroot into the original OS
for d in dev dev/pts proc sys run; do
  sudo mount --bind /$d /mnt/$d
done
sudo chroot /mnt

Perform recovery tasks

Common recovery operations inside the chroot:
Reset a user password
passwd ubuntu
Fix fstab — edit with a text editor
nano /etc/fstab
Check and repair the filesystem
fsck -y /dev/vdb1

Exit rescue and reboot normally

After completing repairs, return to the Dashboard. In the instance Actions dropdown, select Unrescue Instance.
The instance reboots from the original root disk and returns to Active status. Verify normal SSH or console access.

​
Important Behaviors

The rescue image is booted as the primary disk. The original root disk is attached as a secondary device (/dev/vdb or similar) and is not automatically mounted. Always identify the correct device before mounting — running lsblk inside the rescue environment shows all attached block devices.
Ephemeral disks attached to the instance are not preserved during rescue mode. Only the persistent root volume (or image-backed root disk on supported configurations) is attached as the secondary device. Do not rely on ephemeral storage for data you intend to access during rescue.
If the rescue image uses a different default user (e.g., ubuntu, centos, ec2-user), check the image documentation for the correct username. The injected key pair is valid regardless of the default user name.

​
Next Steps

Reboot an Instance

Use a soft or hard reboot for non-critical issues before escalating to rescue mode

Launch an Instance

Create a new instance from a snapshot if the original cannot be repaired

Block Device Mapping

Understand how storage volumes are attached and managed during instance operations

Compute User Guide

Overview of all compute operations and instance lifecycle management