> ## Documentation Index
> Fetch the complete documentation index at: https://help.freakhosting.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Use Rescue Mode for Troubleshooting

> Boot your FREAKHOSTING VPS into Rescue Mode to troubleshoot boot failures, fix misconfigurations, and recover data from a minimal Linux rescue environment.

## Your Server's Emergency Recovery Drive

Imagine your laptop will not boot. What do you do? You grab a USB recovery drive, boot from it, and fix things from the outside. Rescue Mode works exactly the same way for your VPS. It boots your server from a completely separate, minimal operating system — one that lives independently from your server's main disk. Your actual disk just sits there, unmounted and untouched, waiting for you to mount it, inspect it, and repair whatever went wrong.

This means Rescue Mode works even when your server's operating system is completely destroyed. Corrupted bootloader? Broken kernel? Filesystem so damaged it will not mount? None of that matters — the rescue system boots from its own image and gives you a clean environment to work from.

<CardGroup cols={2}>
  <Card title="Difficulty" icon="gauge-high">
    Advanced
  </Card>

  <Card title="Time" icon="clock">
    10-30 Minutes
  </Card>
</CardGroup>

***

## When You Need Rescue Mode

<CardGroup cols={2}>
  <Card title="Server Will Not Boot" icon="power-off">
    The most common reason to use Rescue Mode. Your server is stuck in a boot loop, showing kernel panics, GRUB errors, or just a blank screen. Rescue Mode lets you boot independently, mount the disk, and fix whatever is broken.
  </Card>

  <Card title="Broken Configuration Files" icon="file-pen">
    A typo in `/etc/fstab` can prevent your server from ever booting again. A bad network config means no SSH access. A misconfigured SSH daemon means you are locked out. Rescue Mode lets you edit these files from the outside and fix them.
  </Card>

  <Card title="Filesystem Corruption" icon="hard-drive">
    If your disk has filesystem errors (maybe from a sudden power loss or a failed update), you need to run repair tools on an unmounted filesystem. Rescue Mode gives you that — your disk is not mounted, so you can safely run `fsck` to check and repair it.
  </Card>

  <Card title="Data Recovery Before Rebuild" icon="database">
    Sometimes the best option is to rebuild your server from scratch. But first, you need to grab important files — configuration backups, database dumps, website files. Rescue Mode lets you mount the old disk and copy everything you need before wiping it.
  </Card>
</CardGroup>

***

## Entering Rescue Mode

<Steps>
  <Step title="Navigate to Your Server">
    Log into the VPS Control Panel at [cloud.freakhosting.com](https://cloud.freakhosting.com). Click on **Servers** in the top navigation bar, then click **Manage** next to the server you need to troubleshoot.
  </Step>

  <Step title="Open the Options Tab">
    Click on the **Options** tab in the server management navigation.
  </Step>

  <Step title="Select the Rescue Sub-Tab">
    Click on the **Rescue** sub-tab. You will see the rescue mode description explaining that it boots a minimal operating system independent of the server's main disk.
  </Step>

  <Step title="Choose a Rescue System">
    Select a rescue system from the dropdown. The available option is **Linux (Debian Live) Rescue v1**, which provides a full Debian-based recovery environment with all the standard repair tools pre-installed (fsck, mount, nano, chroot, and more).
  </Step>

  <Step title="Create the Rescue Session">
    Click the blue **Create Rescue Session** button. The system will automatically:

    * Shut down your server
    * Boot it from the rescue image (not your main disk)
    * Provide you with temporary login credentials for the rescue environment

    Save the credentials that are displayed — you will need them to log in.
  </Step>

  <Step title="Connect to the Rescue Environment">
    Connect to your server using SSH with the temporary credentials provided. If SSH is not available (for example, if network issues are part of the problem), enable [VNC access](/portals/vps-panel/how-to-enable-and-use-vnc-console-access) and log in through the web console instead. You now have full root access to the rescue system.
  </Step>
</Steps>

<Warning>
  The rescue environment is temporary. Any files you create or software you install inside the rescue system itself (not on your mounted disk) will be lost when you exit Rescue Mode. Make your repairs on the mounted disk, not in the rescue system.
</Warning>

***

## Essential Rescue Mode Commands

Before diving into specific scenarios, here are the foundational commands you will use in almost every rescue session:

### Finding and Mounting Your Server's Disk

Your server's main disk is not mounted automatically in Rescue Mode — that is the whole point. You need to find it and mount it yourself:

```bash theme={null}
# List all available disks and partitions
lsblk

# You will see something like:
# NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
# vda      254:0    0   50G  0 disk
# ├─vda1   254:1    0   49G  0 part
# └─vda2   254:2    0    1G  0 part

# Mount the main partition
mount /dev/vda1 /mnt

# Verify it worked — you should see your server's files
ls /mnt
# bin  boot  dev  etc  home  lib  media  mnt  opt  proc  root  run  sbin  srv  sys  tmp  usr  var
```

<Tip>
  Your main partition is almost always `/dev/vda1` or `/dev/sda1`. If you see multiple partitions, the largest one is typically your root filesystem. Use `lsblk -f` to see filesystem types and labels for more clarity.
</Tip>

### Running Filesystem Repairs

If you suspect disk corruption (common after unexpected shutdowns or failed updates):

```bash theme={null}
# IMPORTANT: The partition must NOT be mounted for fsck to work safely
# If you already mounted it, unmount first: umount /mnt

# Check and repair the filesystem (-y automatically answers "yes" to repair prompts)
fsck -y /dev/vda1

# For ext4 filesystems specifically
e2fsck -fy /dev/vda1
```

***

## Real-World Rescue Scenarios

### Scenario 1: Fixing a Broken /etc/fstab

A bad entry in `/etc/fstab` is one of the most common reasons a Linux server refuses to boot. Maybe you added a mount point with the wrong UUID, or referenced a disk that no longer exists. Here is how to fix it:

```bash theme={null}
# Mount your server's disk
mount /dev/vda1 /mnt

# Look at the current fstab
cat /mnt/etc/fstab

# Edit the file and fix or comment out the broken entry
nano /mnt/etc/fstab

# To comment out a problematic line, add a # at the beginning:
# # /dev/sdb1  /data  ext4  defaults  0  2

# Save and exit (Ctrl+O, Enter, Ctrl+X in nano)

# Unmount cleanly
umount /mnt
```

After exiting Rescue Mode, your server should boot normally with the corrected fstab.

### Scenario 2: Recovering Files Before a Rebuild

Your server is beyond repair and you have decided to rebuild from scratch. But you need your data first:

```bash theme={null}
# Mount your server's disk
mount /dev/vda1 /mnt

# Browse and identify what you need
ls /mnt/home/
ls /mnt/var/www/
ls /mnt/etc/

# Option A: Copy files to a remote server via SCP
scp -r /mnt/var/www/html user@backup-server:/backups/

# Option B: Create a compressed archive and transfer it
tar czf /tmp/backup.tar.gz -C /mnt/var/www html
scp /tmp/backup.tar.gz user@backup-server:/backups/

# Option C: Copy database files
cp /mnt/var/lib/mysql /tmp/mysql-backup -r
scp -r /tmp/mysql-backup user@backup-server:/backups/

# Unmount when done
umount /mnt
```

### Scenario 3: Resetting the Root Password Manually

If the control panel password reset is not working (QEMU Guest Agent not installed), you can reset the password from Rescue Mode:

```bash theme={null}
# Mount your server's disk
mount /dev/vda1 /mnt

# Chroot into your server's filesystem
# This makes the rescue system "pretend" it is your server's OS
mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys
chroot /mnt

# Now you are "inside" your server's OS — change the password
passwd root
# Enter and confirm your new password

# Exit the chroot
exit

# Clean up mounts
umount /mnt/sys
umount /mnt/proc
umount /mnt/dev
umount /mnt
```

### Scenario 4: Fixing a Broken SSH Configuration

You edited `sshd_config` and now SSH will not start:

```bash theme={null}
# Mount your server's disk
mount /dev/vda1 /mnt

# Check the SSH config for syntax errors
# Common mistakes: typos, duplicate directives, setting PermitRootLogin to "no" without another user
cat /mnt/etc/ssh/sshd_config

# Fix the configuration
nano /mnt/etc/ssh/sshd_config

# If you are not sure what is wrong, you can restore the default config:
# cp /mnt/etc/ssh/sshd_config /mnt/etc/ssh/sshd_config.broken
# apt-get download openssh-server  (to get a fresh default config)

# Unmount
umount /mnt
```

### Scenario 5: Repairing the GRUB Bootloader

If GRUB is broken and your server will not boot past the bootloader:

```bash theme={null}
# Mount your server's disk and set up chroot
mount /dev/vda1 /mnt
mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys
chroot /mnt

# Reinstall GRUB (for BIOS/MBR systems)
grub-install /dev/vda
update-grub

# For UEFI systems, you may also need to mount the EFI partition first:
# mount /dev/vda15 /boot/efi  (partition number may vary)
# grub-install --target=x86_64-efi /dev/vda
# update-grub

# Exit chroot and clean up
exit
umount /mnt/sys
umount /mnt/proc
umount /mnt/dev
umount /mnt
```

***

## Exiting Rescue Mode

When you have finished your repairs:

<Steps>
  <Step title="Unmount Everything">
    Make sure you unmount all partitions you mounted during the rescue session. Leaving them mounted can cause data corruption:

    ```bash theme={null}
    umount /mnt
    ```

    If you used chroot, unmount the bind mounts first (`/mnt/sys`, `/mnt/proc`, `/mnt/dev`) before unmounting `/mnt`.
  </Step>

  <Step title="Return to the Rescue Tab">
    Go back to the server's **Options** > **Rescue** tab in the control panel.
  </Step>

  <Step title="End the Rescue Session">
    Click the button to disable or end the rescue session. Your server will restart and boot from its normal primary disk with your repairs applied.
  </Step>
</Steps>

Alternatively, you can restart the server from the **Power Controls** on the Overview page. Restarting will automatically exit Rescue Mode and boot from the primary disk.

***

<AccordionGroup>
  <Accordion title="Will Rescue Mode affect my data?">
    No. Rescue Mode boots from a completely separate image and does not touch your server's main disk at all. Your data remains exactly as it was unless you explicitly mount the disk and make changes yourself. Think of it like booting a laptop from a USB drive — the hard drive is just sitting there, inactive.
  </Accordion>

  <Accordion title="Can I use Rescue Mode if my server will not start at all?">
    Yes, that is the primary use case. Since Rescue Mode boots from an independent image provided by the hypervisor, it works even when your server's operating system is completely destroyed, the bootloader is missing, or the filesystem is corrupted beyond automatic repair.
  </Accordion>

  <Accordion title="How do I find the correct disk to mount?">
    Run `lsblk` to see all available disks and partitions. Your main disk is typically `/dev/vda` (virtio) or `/dev/sda` (SCSI), with the primary partition being `/dev/vda1` or `/dev/sda1`. You can also run `lsblk -f` to see filesystem types and labels, or `fdisk -l` for detailed partition information.
  </Accordion>

  <Accordion title="Is there a time limit on Rescue Mode sessions?">
    There is no strict time limit, but rescue sessions are meant to be temporary. Complete your troubleshooting, make the necessary repairs, and then exit Rescue Mode to return to normal operation. Do not run production workloads in the rescue environment.
  </Accordion>

  <Accordion title="Can I install software in the rescue environment?">
    Yes, the Debian Live rescue environment includes a package manager. You can install additional tools with `apt update && apt install <package>` if needed. However, remember that anything installed in the rescue environment itself is temporary and will be lost when you exit. To install software permanently, chroot into your mounted disk first.
  </Accordion>

  <Accordion title="What if I cannot connect to the rescue environment via SSH?">
    If SSH to the rescue environment is not working, enable [VNC console access](/portals/vps-panel/how-to-enable-and-use-vnc-console-access) from the **Options** > **VNC** tab. VNC connects through the hypervisor and does not depend on network configuration inside the rescue system.
  </Accordion>
</AccordionGroup>

***

<Note>
  ### Need Extra Help?

  If you encounter any issues, our support team is ready to assist:

  * **Live Chat:** Quick assistance via our website.
  * **Support Ticket:** [Open a Ticket](https://freakhosting.com/clientarea/submitticket.php)
  * **Discord:** [Join our Community](https://discord.gg/freakhosting)
  * **Email:** [support@freakhosting.com](mailto:support@freakhosting.com)
</Note>

<Tip>
  ### Save on Your Hosting

  Ready to get a new server? Use code **KB20** at checkout for **20% off** your first month!
</Tip>

***

<div align="center">
  **Last Updated:** March 2026 | **VPS Support:** Rescue Mode simplified.
</div>