Debian VM Setup with Hyper-V

Welcome to the first article of the series Nerdanel’s Toolbox! In this article, I will share my experience of building a Debian 12 virtual machine using Hyper-V on Windows 11. First, we will learn about Hyper-V. After understanding the requirements for the guest OS, we will build the virtual machine. Finally, we will set up an "Enhanced Session" for the VM to use features like a shared clipboard and folder.

Let’s dive in! :)

What is Hyper-V?

According to Microsoft Learn:

Hyper-V is Microsoft's hardware virtualization product. It lets you create and run a software version of a computer, called a virtual machine. Each virtual machine acts like a complete computer, running an operating system and programs. When you need computing resources, virtual machines give you more flexibility, help save time and money and are a more efficient way to use hardware than just running one operating system on physical hardware.

Hyper-V runs each virtual machine in its own isolated space, which means you can run more than one virtual machine on the same hardware at the same time. You might want to do this to avoid problems such as a crash affecting the other workloads, or to give different people, groups, or services access to different systems.

Essentially, it's a tool for creating and managing multiple workspaces on a single Windows host. While it can be set up to manage systems used by different people or groups, an individual with a PC or laptop can use it to create separate, isolated spaces for testing operating systems and software, or for setting up specialized work environments like production or test environments.

Hyper-V is a type-1 or native hypervisor, meaning it runs directly on the physical hardware. This provides a more efficient experience compared to type-2 or hosted hypervisors, which run on top of the host operating system instead of directly on the hardware. Below is a flowchart of its architecture:

+------------------------------------------------+
|                Physical Hardware               |
| (CPU, Memory, Storage, Network Interface, etc.)|
+------------------------------------------------+
                     ▲
                     │
+------------------------------------------------+
|       Windows Operating System (Host OS)       |
|   (Hyper-V runs as a role within Windows OS)   |
+------------------------------------------------+
                     ▲
                     │
+------------------------------------------------+
|                 Hyper-V Layer                  |
| (Virtualization platform managing resources,   |
| isolation, and VM creation)                    |
+------------------------------------------------+
         ▲                    ▲                ▲
         │                    │                │
+-----------------+  +-----------------+  +-----------------+
| Virtual Machine |  | Virtual Machine |  | Virtual Machine |
|       (VM 1)    |  |       (VM 2)    |  |       (VM 3)    |
| OS + Apps       |  | OS + Apps       |  | OS + Apps       |
+-----------------+  +-----------------+  +-----------------+

Compare it with Virtualbox’s architecture below, a type-2 (hosted) hypervisor:

+------------------------------------------------+
|                Physical Hardware               |
| (CPU, Memory, Storage, Network Interface, etc.)|
+------------------------------------------------+
                     ▲
                     │
+------------------------------------------------+
|   Host Operating System (Windows, Linux, macOS)|
| (VirtualBox runs as an application on the host)|
+------------------------------------------------+
                     ▲
                     │
+------------------------------------------------+
|           VirtualBox Application Layer         |
| (Manages virtualization, allocates resources,  |
| and facilitates VM creation and operation)     |
+------------------------------------------------+
         ▲                    ▲                ▲
         │                    │                │
+-----------------+  +-----------------+  +-----------------+
| Virtual Machine |  | Virtual Machine |  | Virtual Machine |
|       (VM 1)    |  |       (VM 2)    |  |       (VM 3)    |
| OS + Apps       |  | OS + Apps       |  | OS + Apps       |
+-----------------+  +-----------------+  +-----------------+

For more information on Hypervisors, refer to page 22 of Robert P. Goldberg’s thesis “Architectural Principles for Virtual Computer Systems”.

CAUTION! Native hypervisors prevent type-2 virtual machines from running. If you have any virtual machine running on the top of a hosted hypervisor, clone it properly to prevent data loss. Make sure the cloned VM works on another system before installing Hyper-V.

Setting the Stage: What You’ll Need Before You Begin

Windows 11 Pro/Enterprise,
A 64-bit processor with Second-Level Address Translation (SLAT),
A minimum of 4GB RAM. 8GB is recommended,
BIOS/UEFI level virtualization support.

Remark: Hyper-V also supports Windows 10 Pro/Enterprise. The process is more or less the same.

See here for verifying hardware requirements.

Building the Virtual Playground: Hyper-V Manager Setup

Although we can install Hyper-V through command-line (see here and here), I recommend taking the GUI route for a safer installation, since native hypervisors have lower-level access to the hardware compared to type-2. We enable its role in Windows’ settings and then let Windows do the rest (image from here).

Press win + R and type “Control Panel” in the textbox.
Go to “Programs > Programs and Features”.
Select “Turn windows features on or off”.
Select Hyper-V and then press OK.

Wait until the installation is complete and you’re prompted to restart.

The Heart of the Matter: Bringing Debian to Life

Professional, production-oriented virtualization requires intermediate to advanced knowledge of Networking. In that case, refer to this guide for a start. For experimental or personal use, the default switch should suffice.

Download an appropriate image of Debian, preferably 12 (bookworm).
Open Hyper-V Manager.
On the left pane, select your server (which your PC’s name).
From the Actions pane, select New \> Virtual Machine.
Select Next in the New Virtual Machine Wizard.
Specify the name and the location of your virtual machine. The default location is C:\ProgramData\Microsoft\Windows\Hyper-V\. Unless you have little space, devote a whole partition to your virtual machine. Select Next to open Specify Generation.
Set the generation to Generation 2. A G2 VM has better support for shared environments. Select Next to open Assign Memory.
Choose for the memory to be dynamic. Set the assigned memory to 4GB, Minimum to 2GB and Maximum to 8GB. Select Next to open Configure Networking.
Open the drop-down menu and choose Default Switch. This action lets the VM connect to the host directly. Select Next to open Connect Virtual Hard Disk.
Select Create a Virtual Hard Disk (VHD). The default location of the hard disk is C:\ProgramData\Microsoft\Windows\Virtual Hard Disks\ but it is recommended to set it to a custom location in a VM-devoted partition of the physical hard disk. The VHDs are by default dynamic, so you can set its size to the minimum Debian requires and then extend it should you need more space. When done, select Next to open Installation Options.
Choose Install Operating System From a Bootable CD/DVD-ROM. Select Browse and choose the Debian image. Select Next.
Verify the options via the summary provided in this step. Select Finish.
Right-click on the virtual machine and select Settings. Go to Security, uncheck Secure Boot and select OK. Double click on the virtual machine to open a session and select start in the middle of the black screen to proceed with the installation of the OS.

For better performance, install hyperv-daemons on your Debian guest OS:

sudo apt update && sudo apt-get upgrade
sudo apt-get install hyperv-daemons

Polishing the Gem: Enhanced Session, Configuring Shared Environments Using xrdp

We wish to copy and paste from our VM to host and vice versa (shared clipboard). We also wish to setup a shared folder for easier file access between the host and the guest.

Enable enhanced session mode in Hyper-V:
1. On your windows host, open Hyper-V Manager.
2. In the action pane, select Hyper-V Settings.
3. Under the Server section, select Enhanced Session Mode Policy. Check the box Allow enhanced session mode.
4. Under the User section, select Enhanced Session Mode. Check the box Use enhanced session mode.

Run the following commands to install and configure xrdp:

 # update your system
 sudo apt update && sudo apt upgrade

 # install xrdp
 sudo apt-get install xrdp xorgxrdp xrdp-sesman

 # enable and start xrdp service
 sudo systemctl enable xrdp
 sudo systemctl start xrdp

 # configure your desktop environment - the following works for gnome.
 echo "gnome-session" > ./xsession

Save the following code to the file install.sh, make it executable and run it (source):

 # Configure the installed XRDP ini files.
 # use vsock transport.
 sed -i_orig -e 's/port=3389/port=vsock:\/\/-1:3389/g' /etc/xrdp/xrdp.ini
 # use rdp security.
 sed -i_orig -e 's/security_layer=negotiate/security_layer=rdp/g' /etc/xrdp/xrdp.ini
 # remove encryption validation.
 sed -i_orig -e 's/crypt_level=high/crypt_level=none/g' /etc/xrdp/xrdp.ini
 # disable bitmap compression since its local its much faster
 sed -i_orig -e 's/bitmap_compression=true/bitmap_compression=false/g' /etc/xrdp/xrdp.ini

 # Add script to setup the ubuntu session properly
 if [ ! -e /etc/xrdp/startdebian.sh ]; then
 cat >> /etc/xrdp/startdebian.sh << EOF
 #!/bin/sh
 # If you not using GNOME, remove GNOME_SHELL_SESSION_MODE.
 export GNOME_SHELL_SESSION_MODE=debian
 # Change the XDG_CURRENT_DESKTOP with your default DE/WM
 export XDG_CURRENT_DESKTOP=debian:GNOME
 exec /etc/xrdp/startwm.sh
 EOF
 chmod a+x /etc/xrdp/startdebian.sh
 fi

 # use the script to setup the ubuntu session
 sed -i_orig -e 's/startwm/startdebian/g' /etc/xrdp/sesman.ini

 # rename the redirected drives to 'shared-drives'
 sed -i -e 's/FuseMountName=thinclient_drives/FuseMountName=shared-drives/g' /etc/xrdp/sesman.ini

 # Changed the allowed_users
 sed -i_orig -e 's/allowed_users=console/allowed_users=anybody/g' /etc/X11/Xwrapper.config

 # Blacklist the vmw module
 if [ ! -e /etc/modprobe.d/blacklist-vmw_vsock_vmci_transport.conf ]; then
   echo "blacklist vmw_vsock_vmci_transport" >
     /etc/modprobe.d/blacklist-vmw_vsock_vmci_transport.conf
 fi

 #Ensure hv_sock gets loaded
 if [ ! -e /etc/modules-load.d/hv_sock.conf ]; then
   echo "hv_sock" > /etc/modules-load.d/hv_sock.conf
 fi

 # Configure the policy xrdp session
 cat > /etc/polkit-1/localauthority/50-local.d/45-allow-colord.pkla <<EOF
 [Allow Colord all Users]
 Identity=unix-user:*
 Action=org.freedesktop.color-manager.create-device;org.freedesktop.color-manager.create-profile;org.freedesktop.color-manager.delete-device;org.freedesktop.color-manager.delete-profile;org.freedesktop.color-manager.modify-device;org.freedesktop.color-manager.modify-profile
 ResultAny=no
 ResultInactive=no
 ResultActive=yes
 EOF

 # reconfigure the service
 systemctl daemon-reload
 systemctl start xrdp

 #
 # End XRDP
 ###############################################################################

 echo "Install is complete."
 echo "Please turn off your VM Machine and execute 'Set-VM \"Debian\" 
        -EnhancedSessionTransportType HvSocket' in PowerShell Admin and turn on again your VM Machine"

Install CIFS and samba:

 sudo apt update
 sudo apt install samba-client cifs-utils

On your host, go to the Properties of the folder you want to share with your guest. Under the sharing tab, select Advanced Sharing enable sharing and set permissions.
Create a mount point on your guest:
```
 sudo mkdir /mnt/shared
```
Check your host’s default switch IP by typing ipconfig in Powershell. Your host’s name is on the left pane, under Hyper-V Manager. Then open /etc/hosts and add the following line to it:
```
 <your-host-default-switch-ip> <hostname>
```
Create a file to store your credentials:
```
 sudo nano /etc/samba/credentials
```

Add your Windows credentials and save the file:

 username=your_username
 password=your_password

Restrict the access to the credentials to root:
```
sudo chmod 600 /etc/samba/credentials
```
Add the following line to /etc/fstab for automatic mounting:
```
//HOSTNAME/SharedFolder /mnt/shared cifs credentials=/root/.smbcredentials,iocharset=utf8,security=ntlmssp 0 0
```
Replace HOSTNAME with your host’s name and SharedFolder with your shared folder’s name.

Keep It Running: Tackling Issues Regarding Hyper-V’s Enhanced Session

Two main issues with this approach are the malfunctioning of the mounting the shared folder, and the restrictions one might experience with the new session.

CAUTION: Prior to troubleshooting, create a checkpoint via Hyper-V Manager.

In case the session malfunctions, try either one or a combination of the following solutions:
- Change security=ntlmssp to security=ntlm in /etc/fstab
- Give the credentials directly to cifs: change credentials=/root/.smbcredentials to username=your_username,password=your_password in /etc/fstab
- Change credentials=/root/.smbcredentials to credentials=/etc/samba/credentials

Preferably, don’t save the session settings (e.g. resolution). The session may get stuck with a “establishing session/video connection failed” error.

In case you experience issues with the keyring not being unlocked (try either one of them):
- Consult this issue for color-related and other authentication failure issues.
- Consult this issue if the above solution doesn’t work.

Conclusion

In this article, we learned how to setup a Debian guest on Hyper-V and configured a shared clipboard and folder. This method is tested by myself but I’m not responsible should any loss or damage happens. Please create a checkpoint before any sensitive changes to avoid data loss. Configure the basics before installing any other tools. Study any foreign concept thoroughly before following related instructions.

Happy virtualizing and don’t hesitate to reach out via comments! :)

Building a Debian Virtual Machine Using Hyper-V

Table of contents