There are times when a server becomes unreachable over SSH due to broken networking, a bad install, misconfiguration, a kernel upgrade, bad firewall rules, etc. When you can’t log into your server at all (you don't have the root password or the server won’t boot up) you can use our Rescue Mode, which loads a vanilla Alpine Linux image into your server's RAM.
If you DO have your server's root password and your SSH key, you should use our Serial Over SSH console.
Layer 3 Networking - For us to load the Rescue OS onto your server it must be reachable at an IP address. Therefore, your server must be in a Layer 3 or Hybrid networking mode. If your server is currently in a pure Layer 2 configuration you must convert it to a Layer 3 or Hybrid networking mode to use Rescue Mode.
SSH Keys - To access the server after it boots into the Rescue OS you must have a valid SSH key. The Rescue OS uses the SSH public keys that are associated with your server when you initially provisioned it.
Root Partition - Depending on the type of repair or recovery operations you need to do you'll need the location of the original operating system's root partition. The best way to find this information is before you need rescue mode, from the operating system itself. For example, in Ubuntu you can find the root partition with
Booting into Rescue Mode¶
To enter Rescue Mode, you can find Rescue Mode from your server's main Overview page. Click on Server Actions, and select Rescue OS from the dropdown.
This reboots the server, loads the Rescue OS Alpine Linux image into RAM, then boots the server into Alpine Linux. The public IPv4 address of the server stays the same.
Once the server has booted you can SSH as root using authorized SSH keys. If you had previously used SSH to connect to the server, you might get a warning that the host key has changed, and to remove the host key from your known hosts file on the local machine before you can connect.
When you have successfully SSHed into the server you will see the Rescue OS intro and command line prompt.
,------. ,--. ,--.
| .---' ,---. ,--.,--.`--',--,--, `--',--. ,--.
| `--, | .-. || || |,--.| \,--. \ `' /
| `---.' '-' |' '' '| || || || | / /. \
`------' `-| | `----' `--'`--''--'`--''--' '--'
OS Rescue Environment
Commit: dd4b2268 (main) BuildNo: unknown
Based on Alpine Linux 3.18.4
Use "apk" package manager for additional utilities.
See docs at http://wiki.alpinelinux.org
Mounting the Original Root Partition¶
To fix many problems, you need to mount the original OS's root partition. If you don't already know where the original OS's root partition is, you can try to guess. Often, it's
dev/sdc3. For some of our servers it might be in
xxx is the number of the
The examples on this page mount
mount -t ext4 /dev/sda3 /mnt
Once you have successfully mounted a partition,
cd to it.
ls to see the original OS's filesystem.
This example output is from Ubuntu 20.04.
bin home libx32 opt sbin tmp
boot lib lost+found proc snap usr
dev lib32 media root srv var
etc lib64 mnt run sys
If you have successfully accessed the root partition, you can repair it.
Common Use Cases and Repairs¶
Resetting the Root Password¶
In cases when you can normally SSH into your server and can’t use the SOS/OOB console because you have forgotten or haven’t saved the root password, you can reset it through Rescue Mode.
After mounting the root filesystem to
/mnt, we can use
chroot to load the mounted filesystem and directly use the
sudo passwd command to modify the existing root password.
chroot /mnt /bin/bash
If the server cannot boot into the original OS anymore and you need to recover any important files, you can use
scp from Rescue Mode to move them somewhere else.
So, if you have a demo folder located in a
/demo folder in your home directory, you can use
scp to save them to your local machine.
scp -r root@<server_ip_address>:/mnt/home/demo /User/Downloads
Resize or Add Partitions¶
By default, the boot drive will have a root partition that utilizes all the drive space. Some servers have additional unformatted drives but if you need to create multiple partitions in the same boot drive, you can go into Rescue Mode to shrink the root partition and create new ones.
The process for doing this can differ depending on the filesystem that you use but if using an OS with ext4 such as Ubuntu, you can use
gdisk to resize your filesystem/partition and create additional ones.
It's worth noting that the default cloud-init configuration file in our images has the
resizefs modules enabled which will resize your root partition back to its max drive size if you only shrink the partition but not create additional ones. If you would like to avoid this behavior, you can edit the cloud-init configuration file found at
/etc/cloud/cloud.cfg to remove the
-resizefs modules. Once you save the file, cloud-init should not attempt to resize the partition every time the OS boots.
Additional Packages for Alpine Linux¶
The Alpine Linux image used for Rescue Mode might be missing packages required for special operations. For example, to run
fsck you need to install the
apk add e2fsprogs
After successful installation, you can run
sda1 for example.
fsck.ext4 -f -y /dev/sda1
You might need other packages, like
zfs if you are formatting a partition with a filesystem other than
ext4. You can find all the available packages to install in the Alpine Linux package directory.
Returning to Your Original Operating System¶
To get back to the original OS, we can simply reboot the server.
From Alpine Linux:
To reboot Alpine Linux, use the
From the console:
To reboot your server from its Overview page, click on Server Actions, and select Reboot from the dropdown.
Once the server has finished rebooting from either process, it will boot back into your original operating system.