marcel/winapps
1
0
Fork 0
mirror of https://github.com/winapps-org/winapps.git synced 2025-09-19 07:49:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #663 from KernelGhost/main

Browse Source 
Improve libvirt documentation and install script
This commit is contained in:
Oskar Manhart
2025-08-28 13:39:15 +02:00
committed by GitHub
parent fc9d558288 63e94e277f
commit def1d60326
10 changed files with 204 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
README.md
View File

@@ -20,19 +20,19 @@ WinApps works by:
- Microsoft Office links (e.g. ms-word://) from the host system are automatically opened in the Windows subsystem. (Note: You may need to use a [User Agent Switcher](https://github.com/ray-lothian/UserAgent-Switcher/) browser extension and set the User-Agent to Windows, as the Office webapps typically hide the "Open in Desktop App" option for Linux users.)
## Supported Applications
**WinApps supports <u>*ALL*</u> Windows applications.**
**WinApps supports <u>*ALL*</u> Windows applications.** Support does not, however, extend to kernel-level anti-cheat systems (e.g. Riot Vanguard).
Universal application support is achieved by:
1. Scanning Windows for any officially supported applications (list below).
1. Scanning Windows for any community tested applications (list below).
2. Scanning Windows for any other `.exe` files listed within the Windows Registry.
Officially supported applications benefit from high-resolution icons and pre-populated MIME types. This enables file managers to determine which Windows applications should open files based on file extensions. Icons for other detected applications are pulled from `.exe` files.
Community tested applications benefit from high-resolution icons and pre-populated MIME types. This enables file managers to determine which Windows applications should open files based on file extensions. Icons for other detected applications are pulled from `.exe` files.
Contributing to the list of supported applications is encouraged through submission of pull requests! Please help us grow the WinApps community.
*Please note that the provided list of officially supported applications is community-driven. As such, some applications may not be tested and verified by the WinApps team.*
*Please note that the provided list of community tested applications is community-driven. As such, some applications may not be tested and verified by the WinApps team.*
### Officially Supported Applications
### Community Tested Applications
<table cellpadding="10" cellspacing="0" border="0">
<tr>
<!-- Adobe Acrobat Pro -->
@@ -565,7 +565,7 @@ Adding your own applications with custom icons and MIME types to the installer i
1. Modify the name and variables to reflect the appropriate/desired values for your application.
2. Replace `icon.svg` with an SVG for your application (ensuring the icon is appropriately licensed).
3. Remove and reinstall WinApps.
4. Submit a pull request to add your application to WinApps as an officially supported application once you have tested and verified your configuration (optional, but encouraged).
4. Submit a pull request to add your application to WinApps as a community tested application once you have tested and verified your configuration (optional, but encouraged).
## Running Applications Manually
WinApps offers a manual mode for running applications that were not configured by the WinApps installer. This is completed with the `manual` flag. Executables that are in the Windows PATH do not require full path definition.

254
docs/libvirt.md
View File

@@ -1,6 +1,8 @@
# Creating a `libvirt` Windows VM
## Understanding The Virtualisation Stack
This method of configuring a Windows virtual machine for use with WinApps is significantly more involved than utilising `Docker` or `Podman`. Nevertheless, expert users may prefer this method due to its greater flexibility and wider range of customisation options.
This method of configuring a Windows virtual machine for use with WinApps is significantly more involved than utilising `Docker` or `Podman`. Nevertheless, expert users may prefer this method due to its greater flexibility and wider range of customisation options (e.g. GPU passthrough).
<details>
<summary><strong>Understanding The Virtualisation Stack</strong></summary>
Before beginning, it is important to have a basic understanding of the various components involved in this particular method.
@@ -15,6 +17,8 @@ Together, these components form a powerful and flexible virtualization stack, wi
<img src="./libvirt_images/Virtualisation_Stack.svg" width="500px"/>
</p>
</details>
## Prerequisites
1. Ensure your CPU supports hardware virtualisation extensions by [reading this article](https://wiki.archlinux.org/title/KVM).
@@ -146,8 +150,93 @@ Together, these components form a powerful and flexible virtualization stack, wi
<img src="./libvirt_images/08.png" width="700px"/>
</p>
10. (Optional) Assign specific physical CPU cores to the virtual machine. This can improve performance by reducing context switching and ensuring that the virtual machine's workload consistently uses the same cores, leading to better CPU cache utilisation.
1. Run `lscpu -e` to determine which L1, L2 and L3 caches are associated with which CPU cores.
10. Navigate to the `XML` tab, and edit the `<clock>` section to disable all timers except for the hypervclock, thereby drastically reducing idle CPU usage. Once changed, click `Apply`.
```xml
<clock offset='localtime'>
<timer name='rtc' present='no' tickpolicy='catchup'/>
<timer name='pit' present='no' tickpolicy='delay'/>
<timer name='hpet' present='no'/>
<timer name='kvmclock' present='no'/>
<timer name='hypervclock' present='yes'/>
</clock>
```
<p align="center">
<img src="./libvirt_images/09.png" width="700px"/>
</p>
11. Enable Hyper-V enlightenments by adding the following to the `<hyperv>` section. Once changed, click `Apply`.
```xml
<hyperv>
<relaxed state='on'/>
<vapic state='on'/>
<spinlocks state='on' retries='8191'/>
<vpindex state='on'/>
<synic state='on'/>
<stimer state='on'>
<direct state='on'/>
</stimer>
<reset state='on'/>
<frequencies state='on'/>
<reenlightenment state='on'/>
<tlbflush state='on'/>
<ipi state='on'/>
</hyperv>
```
> [!NOTE]
> Hyper-V enlightenments make Windows (and other Hyper-V guests) think they are running on top of a Hyper-V compatible hypervisor. This enables use of Hyper-V specific features, allowing `KVM` to implement paravirtualised interfaces for improved virtual machine performance.
12. Add the following XML snippet within the `<devices>` section to enable the GNU/Linux host to communicate with Windows using `QEMU Guest Agent`.
```xml
<channel type='unix'>
<source mode='bind'/>
<target type='virtio' name='org.qemu.guest_agent.0'/>
<address type='virtio-serial' controller='0' bus='0' port='2'/>
</channel>
```
13. In the 'Memory' section, set the `Current allocation` to the minimum amount of memory you want the virtual machine to use, with a recommended value of `1024MB`.
<p align="center">
<img src="./libvirt_images/10.png" width="500px"/>
</p>
14. (Optional) Under `Boot Options`, enable `Start virtual machine on host boot up`.
<p align="center">
<img src="./libvirt_images/11.png" width="500px"/>
</p>
15. Navigate to 'SATA Disk 1' and set the `Disk bus` type to `VirtIO`. This allows disk access to be paravirtualised, improving virtual machine performance.
<p align="center">
<img src="./libvirt_images/12.png" width="500px"/>
</p>
16. Navigate to 'NIC' and set the `Device model` type to `virtio` to enable paravirtualised networking.
<p align="center">
<img src="./libvirt_images/13.png" width="500px"/>
</p>
17. Click the `Add Hardware` button in the lower left, and choose `Storage`. For `Device type`, select `CDROM device` and choose the VirtIO driver `.ISO` you downloaded earlier. Click `Finish` to add the new CD-ROM device.
> [!IMPORTANT]
> If you skip this step, the Windows installer will fail to recognise and list the virtual hard drive you created earlier.
<p align="center">
<img src="./libvirt_images/14.png" width="500px"/>
</p>
<details>
<summary><strong>(Optional) Assign Specific Physical CPU Cores</strong></summary>
Assigning specific physical CPU cores to the virtual machine can improve performance by reducing context switching and ensuring that the virtual machine's workload consistently uses the same cores, leading to better CPU cache utilisation. This is an optional step.
1. Run `lscpu -e` to determine which L1, L2 and L3 caches are associated with which CPU cores.
Example 1 (Intel 11th Gen Core i7-1185G7):
```
@@ -191,7 +280,7 @@ Together, these components form a powerful and flexible virtualization stack, wi
- C<sub>4</sub> = T<sub>8</sub>+T<sub>9</sub> &rarr; L1<sub>4</sub>+L2<sub>4</sub>+L3<sub>1</sub>
- C<sub>5</sub> = T<sub>10</sub>+T<sub>11</sub> &rarr; L1<sub>5</sub>+L2<sub>5</sub>+L3<sub>1</sub>
2. Select which CPU cores to 'pin'. You should aim to select a combination of CPU cores that minimises sharing of caches between Windows and GNU/Linux.
2. Select which CPU cores to 'pin'. You should aim to select a combination of CPU cores that minimises sharing of caches between Windows and GNU/Linux.
Example 1:
- CPU cores share the same singular L3 cache, so this cannot be optimised.
@@ -215,7 +304,7 @@ Together, these components form a powerful and flexible virtualization stack, wi
- T<sub>0</sub>+T<sub>1</sub>+T<sub>2</sub>+T<sub>3</sub>+T<sub>4</sub>+T<sub>5</sub>
- T<sub>6</sub>+T<sub>7</sub>+T<sub>8</sub>+T<sub>9</sub>+T<sub>10</sub>+T<sub>11</sub>
3. Prepare and add/modify the following to the `<vcpu>`, `<cputune>` and `<cpu>` sections, adjusting the values to match your selected threads.
3. Prepare and add/modify the following to the `<vcpu>`, `<cputune>` and `<cpu>` sections, adjusting the values to match your selected threads.
Example 1: The following selects 'T<sub>2</sub>+T<sub>6</sub>+T<sub>3</sub>+T<sub>7</sub>'.
@@ -252,95 +341,11 @@ Together, these components form a powerful and flexible virtualization stack, wi
> [!NOTE]
> More information on configuring CPU pinning can be found in [this excellent guide](https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#CPU_pinning).
11. Navigate to the `XML` tab, and edit the `<clock>` section to disable all timers except for the hypervclock, thereby drastically reducing idle CPU usage. Once changed, click `Apply`.
```xml
<clock offset='localtime'>
<timer name='rtc' present='no' tickpolicy='catchup'/>
<timer name='pit' present='no' tickpolicy='delay'/>
<timer name='hpet' present='no'/>
<timer name='kvmclock' present='no'/>
<timer name='hypervclock' present='yes'/>
</clock>
```
</details>
<p align="center">
<img src="./libvirt_images/09.png" width="700px"/>
</p>
12. Enable Hyper-V enlightenments by adding the following to the `<hyperv>` section. Once changed, click `Apply`.
```xml
<hyperv>
<relaxed state='on'/>
<vapic state='on'/>
<spinlocks state='on' retries='8191'/>
<vpindex state='on'/>
<synic state='on'/>
<stimer state='on'>
<direct state='on'/>
</stimer>
<reset state='on'/>
<frequencies state='on'/>
<reenlightenment state='on'/>
<tlbflush state='on'/>
<ipi state='on'/>
</hyperv>
```
> [!NOTE]
> Hyper-V enlightenments make Windows (and other Hyper-V guests) think they are running on top of a Hyper-V compatible hypervisor. This enables use of Hyper-V specific features, allowing `KVM` to implement paravirtualised interfaces for improved virtual machine performance.
13. Add the following XML snippet within the `<devices>` section to enable the GNU/Linux host to communicate with Windows using `QEMU Guest Agent`.
```xml
<channel type='unix'>
<source mode='bind'/>
<target type='virtio' name='org.qemu.guest_agent.0'/>
<address type='virtio-serial' controller='0' bus='0' port='2'/>
</channel>
```
14. In the 'Memory' section, set the `Current allocation` to the minimum amount of memory you want the virtual machine to use, with a recommended value of `1024MB`.
<p align="center">
<img src="./libvirt_images/10.png" width="500px"/>
</p>
15. (Optional) Under `Boot Options`, enable `Start virtual machine on host boot up`.
<p align="center">
<img src="./libvirt_images/11.png" width="500px"/>
</p>
16. Navigate to 'SATA Disk 1' and set the `Disk bus` type to `VirtIO`. This allows disk access to be paravirtualised, improving virtual machine performance.
<p align="center">
<img src="./libvirt_images/12.png" width="500px"/>
</p>
17. Navigate to 'NIC' and set the `Device model` type to `virtio` to enable paravirtualised networking.
<p align="center">
<img src="./libvirt_images/13.png" width="500px"/>
</p>
18. Click the `Add Hardware` button in the lower left, and choose `Storage`. For `Device type`, select `CDROM device` and choose the VirtIO driver `.ISO` you downloaded earlier. Click `Finish` to add the new CD-ROM device.
> [!IMPORTANT]
> If you skip this step, the Windows installer will fail to recognise and list the virtual hard drive you created earlier.
<p align="center">
<img src="./libvirt_images/14.png" width="500px"/>
</p>
19. Click `Begin Installation` in the top left.
<p align="center">
<img src="./libvirt_images/15.png" width="700px"/>
</p>
### Example `.XML` File
Below is an example `.XML` file that describes a Windows 11 virtual machine.
<details>
<summary><strong>Example .XML File</strong></summary>
```xml
<domain type="kvm">
@@ -563,14 +568,21 @@ Below is an example `.XML` file that describes a Windows 11 virtual machine.
</domain>
```
</details>
## Install Windows
Install Windows as you would on any other machine.
Click `Begin Installation` in the top left.
<p align="center">
<img src="./libvirt_images/15.png" width="700px"/>
</p>
<p align="center">
<img src="./libvirt_images/16.png" width="700px"/>
</p>
Once you get to the point of selecting the location for installation, you will see there are no disks available. This is because the `VirtIO driver` needs to be specified manually.
1. Select `Load driver`.
<p align="center">
@@ -615,19 +627,17 @@ Following the above, choose to "Continue with limited setup".
</p>
## Final Configuration Steps
Open `File Explorer` and navigate to the drive where the `VirtIO` driver `.ISO` is mounted. Run `virtio-win-gt-x64.exe` to launch the `VirtIO` driver installer.
Open `File Explorer` and navigate to the drive where the "virtio-win" `.iso` is mounted. Run `virtio-win-guest-tools.exe` to install all necessary drivers as well as `QEMU Guest Agent`. Leave everything as default and click `Next` through the installer.
<p align="center">
<img src="./libvirt_images/24.png" width="700px"/>
</p>
Leave everything as default and click `Next` through the installer. This will install all required device drivers as well as the 'Memory Ballooning' service.
<p align="center">
<img src="./libvirt_images/25.png" width="700px"/>
</p>
Next, install the `QEMU Guest Agent` within Windows. This agent allows the GNU/Linux host to request a graceful shutdown of the Windows system. To do this, either run `virtio-win-guest-tools.exe` or `guest-agent\qemu-ga-x86_64.msi`. You can confirm the guest agent was successfully installed by running `Get-Service QEMU-GA` within a PowerShell window. The output should resemble:
Confirm `QEMU Guest Agent` was successfully installed by running `Get-Service QEMU-GA` within a PowerShell window. The output should resemble:
```
Status Name DisplayName
@@ -654,7 +664,7 @@ You can then test whether the host GNU/Linux system can communicate with Windows
}
```
Next, you will need to make some registry changes to enable RDP Applications to run on the system. Start by downloading the [RDPApps.reg](../oem/RDPApps.reg) file, right-clicking on the `Raw` button, and clicking on `Save target as`. Repeat the same thing for the [install.bat](../oem/install.bat) and the [NetProfileCleanup.ps1](../oem/NetProfileCleanup.ps1). **Do not download the Container.reg.**
Next, you will need to make some registry changes to enable RDP Applications to run on the system. Start by downloading the [RDPApps.reg](../oem/RDPApps.reg) file, right-clicking on the `Raw` button, and clicking on `Save target as`. Repeat the same thing for the [install.bat](../oem/install.bat) and the [NetProfileCleanup.ps1](../oem/NetProfileCleanup.ps1). **Do not download 'Container.reg'** - this file is only required for users using docker or podman.
<p align="center">
<img src="./libvirt_images/26.png" width="700px"/>
@@ -666,33 +676,11 @@ Once you have downloaded all three files, right-click the install.bat and select
<img src="./libvirt_images/27.png" width="700px"/>
</p>
Rename the Windows virtual machine so that WinApps can locate it by navigating to the start menu and typing `About` to bring up the `About your PC` settings.
Once this is complete, restart the Windows virtual machine.
<p align="center">
<img src="./libvirt_images/28.png" width="700px"/>
</p>
<details>
<summary><strong>(Optional) Configuring a Fallback Shared Folder</strong></summary>
Scroll down and click on `Rename this PC`.
<p align="center">
<img src="./libvirt_images/29.png" width="700px"/>
</p>
Rename the PC to `RDPWindows`, but **DO NOT** restart the virtual machine.
<p align="center">
<img src="./libvirt_images/30.png" width="700px"/>
</p>
Scroll down to `Remote Desktop`, and enable `Enable Remote Desktop`.
<p align="center">
<img src="./libvirt_images/31.png" width="700px"/>
</p>
At this point, you will need to restart the Windows virtual machine.
## (Optional) Configuring a Fallback Shared Folder
When connecting to Windows through FreeRDP, your home folder will be shared automatically. However, this sharing setup does not apply when using Windows via virt-manager. To configure a fallback shared folder, follow these steps:
1. Navigate to "Virtual Hardware Details", then "Memory" and then check the box for "Enable shared memory".
@@ -709,7 +697,11 @@ When connecting to Windows through FreeRDP, your home folder will be shared auto
5. Reboot Windows.
## (Optional) Configuring a Static IP Address
</details>
<details>
<summary><strong>(Optional) Configuring a Static IP Address</strong></summary>
1. Identify the Windows MAC address.
```bash
virsh dumpxml "RDPWindows" | grep "mac address"
@@ -744,12 +736,18 @@ When connecting to Windows through FreeRDP, your home folder will be shared auto
5. Reboot Windows.
</details>
<details>
<summary><strong>(Optional) Installing Spice Guest Tools</strong></summary>
You may also wish to install [Spice Guest Tools](https://www.spice-space.org/download/windows/spice-guest-tools/spice-guest-tools-latest.exe) inside the virtual machine, which enables features like auto-desktop resize and cut-and-paste when accessing the virtual machine through `virt-manager`. Since WinApps uses RDP, however, this is unnecessary if you don't plan to access the virtual machine via `virt-manager`.
</details>
## Installing Windows Software and Configuring WinApps
You may now proceed to install other applications like 'Microsoft 365', 'Adobe Creative Cloud' or any other applications you would like to use through WinApps.
> [!NOTE]
> You may also wish to install [Spice Guest Tools](https://www.spice-space.org/download/windows/spice-guest-tools/spice-guest-tools-latest.exe) inside the virtual machine, which enables features like auto-desktop resize and cut-and-paste when accessing the virtual machine through `virt-manager`. Since WinApps uses RDP, however, this is unnecessary if you don't plan to access the virtual machine via `virt-manager`.
> [!IMPORTANT]
> Ensure `WAFLAVOR` is set to `"libvirt"` in your `~/.config/winapps/winapps.conf` to prevent WinApps looking for a `Docker` installation instead.

BIN
docs/libvirt_images/24.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 199 KiB

After

Width:  |  Height:  |  Size: 236 KiB

BIN
docs/libvirt_images/25.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 225 KiB

After

Width:  |  Height:  |  Size: 61 KiB

BIN
docs/libvirt_images/28.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 178 KiB

BIN
docs/libvirt_images/29.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 171 KiB

BIN
docs/libvirt_images/30.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 157 KiB

BIN
docs/libvirt_images/31.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 160 KiB

12
oem/RDPApps.reg
View File

@@ -1,5 +1,17 @@
Windows Registry Editor Version 5.00
; Enable Remote Desktop
; NOTE: The relevant firewall rule must be added separately with either:
; Enable-NetFirewallRule -DisplayGroup "Remote Desktop"
; or
; netsh advfirewall firewall set rule group="remote desktop" new enable=Yes
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server]
"fDenyTSConnections"=dword:00000000
; Require Network Level Authentication (NLA) for Remote Desktop
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server\WinStations\RDP-Tcp]
"UserAuthentication"=dword:00000001
; Disable RemoteApp allowlist so all applications can be used in Remote Desktop sessions
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Terminal Server\TSAppAllowList]
"fDisabledAllowList"=dword:00000001

49
oem/install.bat
View File

@@ -1,33 +1,50 @@
@echo off
title WinApps Setup Wizard
REM Check for administrative privileges
:: Check for administrative privileges
fltmc >nul 2>&1 || (
echo [INFO] Script not running as administrator. Attempting to relaunch with elevation...
powershell -Command "Start-Process '%~f0' -Verb runAs"
exit /b 0
exit /b
)
REM Confirm the user wants to proceed with setup
echo ============================================
echo WinApps Setup Wizard
echo ============================================
echo.
echo Press any key to continue or close this window to cancel...
pause >nul
echo.
echo [INFO] Starting setup...
REM Apply RDP and system configuration tweaks
:: Apply RDP and system configuration tweaks
echo [INFO] Importing "RDPApps.reg"...
reg import "%~dp0RDPApps.reg" >nul 2>&1
if %ERRORLEVEL% equ 0 (
if exist "%~dp0RDPApps.reg" (
reg import "%~dp0RDPApps.reg" >nul 2>&1
if %ERRORLEVEL% equ 0 (
echo [SUCCESS] Imported "RDPApps.reg".
) else (
) else (
echo [ERROR] Failed to import "RDPApps.reg".
)
) else (
echo [ERROR] "RDPApps.reg" not found. Skipping...
)
REM Configure the system clock to use UTC instead of local time
:: Allow Remote Desktop connections through the firewall
echo [INFO] Allowing Remote Desktop connections through the firewall...
powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass ^
-Command "if (Get-Command Enable-NetFirewallRule -ErrorAction SilentlyContinue) { try { Enable-NetFirewallRule -DisplayGroup 'Remote Desktop' -ErrorAction Stop; exit 0 } catch { exit 1 } } else { exit 2 }" >nul 2>&1
if %ERRORLEVEL% equ 0 (
echo [SUCCESS] Firewall changes applied successfully.
) else (
:: Fallback to using 'netsh' to make the firewall modification
netsh advfirewall firewall set rule group="remote desktop" new enable=Yes >nul 2>&1
if %ERRORLEVEL% equ 0 (
echo [SUCCESS] Firewall changes applied successfully.
) else (
echo [ERROR] Failed to apply firewall changes.
echo Please manually enable Remote Desktop via 'Settings ► System ► Remote Desktop'.
)
)
:: Configure the system clock to use UTC instead of local time
if exist "%~dp0Container.reg" (
echo [INFO] Importing "Container.reg"...
reg import "%~dp0Container.reg" >nul 2>&1
@@ -40,15 +57,15 @@ if exist "%~dp0Container.reg" (
echo [WARNING] "Container.reg" not found. Skipping...
)
REM Create a startup task to clean up stale network profiles
:: Create a startup task to clean up stale network profiles
echo [INFO] Creating network profile cleanup task...
REM Initialise values required to create the startup task
:: Initialise values required to create the startup task
set "scriptpath=%windir%\NetProfileCleanup.ps1"
set "taskname=WinApps_NetworkProfileCleanup"
set "command=powershell.exe -ExecutionPolicy Bypass -File ""%scriptpath%"""
REM Copy the script to the Windows directory
:: Copy the script to the Windows directory
copy /Y "%~dp0NetProfileCleanup.ps1" "%scriptpath%" >nul
if %ERRORLEVEL% neq 0 (
echo [ERROR] Failed to copy "NetProfileCleanup.ps1" to "%windir%".
@@ -60,7 +77,3 @@ if %ERRORLEVEL% neq 0 (
echo [ERROR] Failed to create scheduled task "%taskname%".
)
)
echo.
echo Press any key to exit...
pause >nul