Recovery
From Whonix
Recovery Mode[edit]
If an error occurs that prevents Whonix ™ from booting, it is possible to try and boot Whonix ™ in recovery mode to fix the problem. It is advisable to learn how to use recovery mode while everything is still functional in case of future issues.
- After powering on a Non-Qubes-Whonix VM, you will see the virtual BIOS for a second, then the grub boot menu. The grub boot menu is easily identified by the first line of text which begins with
GNU GRUB
. - Use the arrow keys to navigate and select
Advanced Options for Whonix GNU/Linux
. - Press
Enter
. - Choose the second option which at the end displays
(recovery mode)
. - Press
Enter
. - Somewhere in the output, a message similar to the following will appear (it might be entangled with other debug output):
Give root password for maintenance (Or press control + d to continue):
- Enter the root password.
- While typing, no asterisk symbols (
*
) will appear; the password must be typed "blind". [1] - Press
Enter
. - The default keyboard layout will be
en-US
. To change this setting, see: Keyboard Layout. - Enter
exit
to continue booting orpoweroff
orreboot
.
TODO: Explore whether networking is possible and how to transfer files out of the VM.
Virtual Consoles[edit]
An easier and more lightweight solution as alternative to recovery mode might be virtual consoles. If the graphical user interface is no longer starting, login to a virtual console might still be possible.
Prerequisite knowledge: Virtual Consoles. Try to login in a virtual console in a functional VM (virtual machine) as an exercise. If that works, try login to virtual console in the broken VM.
Unlock User Account: Excessive Wrong Password Entry Attempts[edit]
See: Unlock User Account: Excessive Wrong Password Entry Attempts.
Chroot[edit]
If an error occurs that prevents Whonix ™ from booting, it is possible to chroot [archive] into Whonix ™ from a live CD to fix the problem.
A disk image must be downloaded for this purpose -- Debian Live images [archive] or Archiso [archive] are useful options for this procedure.
Virtualbox[edit]
In Virtualbox, navigate to the VM storage settings. At the second controller, click the optical disk icon and add the disk image.
In the Motherboard settings, move the Optical disk component to the top of the boot order, press OK
and start the VM.
KVM[edit]
In virt-manager, click on the VM, click the settings icon at the top and click "Add Hardware". In "Storage", change the device type to "CDROM device" and add the disk image. Click "Finish" and at the boot options setting, move the CDROM to the top of the boot order.
Qubes-Whonix[edit]
This procedure is undocumented.
Booting into the Live CD[edit]
After booting into the Live CD, follow these steps.
1. List the available drives and partitions.
fdisk -l
2. Mount the partition.
mount /dev/sda1 /mnt
Replace "/dev/sda1" with the drive partition name.
3. Chroot into the partition.
chroot /mnt /bin/bash
4. Optional: If the PATH variable is incorrect, it can be fixed with the following command.
source /etc/profile
Serial Console[edit]
VirtualBox[edit]
Preparation[edit]
Host Preparation[edit]
Install socat
on the host operating system. The following steps apply to Linux distributions.
Install socat
.
1. Update the package lists.
sudo apt-get update
2. Upgrade the system.
sudo apt-get dist-upgrade
3. Install the socat
package.
Using apt-get
command line parameter --no-install-recommends
is in most cases optional.
sudo apt-get install --no-install-recommends socat
The procedure of installing socat
is complete.
Windows and macOS hosts are currently undocumented, but should also work in theory.
VM Preparation[edit]
Inside the Whonix ™ virtual machine where you want to enable the serial console, install the serial-console-enable
package.
Install serial-console-enable
.
1. Update the package lists.
sudo apt-get update
2. Upgrade the system.
sudo apt-get dist-upgrade
3. Install the serial-console-enable
package.
Using apt-get
command line parameter --no-install-recommends
is in most cases optional.
sudo apt-get install --no-install-recommends serial-console-enable
The procedure of installing serial-console-enable
is complete.
(Installed by default would be nice but it is not installed by default due to issue. TODO: add reference)
Read Only Serial Console[edit]
This option is very useful for capturing diagnostic output from a virtual machine. It allows a log of everything written to the kernel console to be obtained -- all console output is written to a plain text file from boot until shutdown. The logfile persists after VM shutdown, but is overwritten after the VM is shutdown and powered on again.
1. Enable the serial ports option.
Whonix-Workstation VM settings
→ Serial Ports
→ Tick enable
Configure the following settings:
- Port Number:
COM1
(default) - Port Mode:
Raw File
- Path/Address:
/home/user/vbox-raw-file
2. View the file with a text editor.
Any text editor can be used for this purpose. For example to view the file with mousepad, run.
mousepad /home/user/vbox-raw-file
3. Optional: View the file as it is being appended to from a terminal emulator.
The logfile is also compatible with other standard linux utlitites such as tail
. To view it as it is being written, run.
tail -f /home/user/vbox-raw-file
4. Retain the file contents.
After VM shutdown it may be useful to retain its contents by copying the vbox-raw-file
elsewhere to make it a persistent log file. If this is desirable, run.
cp /home/user/vbox-raw-file /home/user/vbox-console-log
Interactive Serial Console[edit]
This procedure does not yet work during the grub boot menu.
1. Enable serial ports on the host.
Whonix-Workstation VM settings
→ Serial Ports
→ Tick enable
Configure the following settings:
- Port Number:
COM1
(default) - Port Mode:
Host Pipe
- Option: uncheck
Connect to existing pipe/socket
- Path/Address:
/home/user/vbox-socket-file
2. Connect to the relevant unix domain socket file.
On the host, run the following socat command to connect to the unix domain socket file which is connected to the operating system running inside the virtual machine. [4]
socat - UNIX-CONNECT:/home/user/vbox-socket-file
Depending on when the above command is run, nothing might appear. The reason is an interactive serial console will only show messages once connected to the serial console; old messages cannot be viewed that way. If the above command is run during early boot, then verbose messages will appear during boot. However, if you press Enter
that should result in the virtual console asking for authentication.
3. Log in to the Whonix ™ session.
Press Enter
. The following prompt will appear.
host login:
Do not enter your host login username! Enter your Whonix user login name, which is most likely user
. Press Enter
. The following prompt will appear.
Password:
Enter the password for that user account; see Default Passwords. Press Enter
.
Warning: the password will not be hidden by asterisk ("*
") symbols. In other words, the password will be written in cleartext and could be read by anyone looking over your shoulder.
Also note that root logins are not possible by default.
Forum Discussion[edit]
https://forums.whonix.org/t/serial-console-in-virtualbox/8021 [archive]
KVM[edit]
See KVM, serial console.
Footnotes[edit]
- ↑ See also: Whonix Default Passwords.
- ↑
If an error like the following appears.
Failed to open a session for the virtual machine Whonix-Gateway-XFCE_15.0.0.4.9.
NamedPipe#0 failed to connect to local socket /home/user/vbox-socket-file (VERR_FILE_NOT_FOUND).
Result Code: NS_ERROR_FAILURE (0x80004005) Component: ConsoleWrap Interface: IConsole {872da645-4a9b-1727-bee2-5585105b9eed}
Then you must uncheck
Connect to existing pipe/socket
. - ↑
vboxmanage modifyvm Whonix-Gateway-XFCE --uart1 0x3F8 4 --uartmode1=server /home/user/vbox-socket-file-gw
vboxmanage modifyvm Whonix-Workstation-XFCE --uart1 0x3F8 4 --uartmode1=server /home/user/vbox-socket-file-ws
- ↑
socat - UNIX-CONNECT:/home/user/vbox-socket-file-gw
socat - UNIX-CONNECT:/home/user/vbox-socket-file-ws
Whonix ™ is Supported by Evolution Host DDoS Protected VPS. Stay private and get your VPS with Bitcoin or Monero.
Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki
Interested in becoming an author for the Whonix ™ News Blog or writing about anonymity, privacy and security? Please get in touch!
This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation. Policy of Whonix Website and Whonix Chat and Policy On Nonfreedom Software applies.
Copyright (C) 2012 - 2020 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)
Whonix ™ is a derivative of and not affiliated with Debian [archive]. Debian is a registered trademark [archive] owned by Software in the Public Interest, Inc [archive].
Whonix ™ is produced independently from the Tor® [archive] anonymity software and carries no guarantee from The Tor Project [archive] about quality, suitability or anything else.
By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint, Contact.