Merge pull request #402 from KernelGhost/main

Documentation Improvements

.github/workflows/update.yaml → .github/workflows/update-submodule.nix

@@ -13,7 +13,13 @@ jobs:
 
       - name: Update module
         run: |
-          git submodule update --init --recursive --checkout -f
+          pushd WinApps-Launcher
+            branch=$(git rev-parse --abbrev-ref origin/HEAD | sed "s|origin/||")
+            git config remote.origin.fetch "+refs/heads/$branch:refs/remotes/origin/$branch"
+            git fetch --depth=1 origin "refs/heads/$branch"
+          popd
+
+          git submodule update --init --remote WinApps-Launcher
 
       - name: Commit and push
         uses: EndBug/add-and-commit@v9

README.md

@@ -1,5 +1,5 @@
 <p align="center"><img align="center" width="700" src="./icons/banner_dark.svg#gh-dark-mode-only"/></p>
-<p align="center"><img align="center" width="700" src="./icons/banner_dark.svg#gh-light-mode-only"/></p>
+<p align="center"><img align="center" width="700" src="./icons/banner_light.svg#gh-light-mode-only"/></p>
 <hr>
 
 Run Windows applications (including [Microsoft 365](https://www.microsoft365.com/) and [Adobe Creative Cloud](https://www.adobe.com/creativecloud.html)) on GNU/Linux with `KDE Plasma`, `GNOME` or `XFCE`, integrated seamlessly as if they were native to the OS.
@@ -288,7 +288,7 @@ If you already have a Windows VM or server you wish to use with WinApps, you wil
 Install the required dependencies.
   - Debian/Ubuntu:
       ```bash
-      sudo apt install -y dialog freerdp3-x11 iproute2 libnotify-bin netcat-openbsd
+      sudo apt install -y curl dialog freerdp3-x11 git iproute2 libnotify-bin netcat-openbsd
       ```
 
 > [!NOTE]
@@ -297,19 +297,19 @@ Install the required dependencies.
 
   - Fedora/RHEL:
       ```bash
-      sudo dnf install -y dialog freerdp iproute libnotify nmap-ncat
+      sudo dnf install -y curl dialog freerdp git iproute libnotify nmap-ncat
       ```
   - Arch Linux:
       ```bash
-      sudo pacman -Syu --needed -y dialog freerdp iproute2 libnotify gnu-netcat
+      sudo pacman -Syu --needed -y curl dialog freerdp git iproute2 libnotify gnu-netcat
       ```
   - OpenSUSE:
       ```bash
-      sudo zypper install -y dialog freerdp iproute2 libnotify netcat-openbsd
+      sudo zypper install -y curl dialog freerdp git iproute2 libnotify netcat-openbsd
       ```
   - Gentoo Linux:
       ```bash
-      sudo emerge --ask=n dev-util/dialog net-misc/freerdp:3 sys-apps/iproute2 x11-libs/libnotify net-analyzer/openbsd-netcat
+      sudo emerge --ask=n net-misc/curl dev-util/dialog net-misc/freerdp:3 dev-vcs/git sys-apps/iproute2 x11-libs/libnotify net-analyzer/openbsd-netcat
       ```
 
 > [!NOTE]
@@ -428,18 +428,12 @@ AUTOPAUSE_TIME="300"
 FREERDP_COMMAND=""
 ```
 
-> [!NOTE]
+> [!IMPORTANT]
 > `RDP_USER` and `RDP_PASS` must correspond to a complete Windows user account and password, such as those created during Windows setup or for a domain user. User/PIN combinations are not valid for RDP access.
 
-> [!NOTE]
+> [!IMPORTANT]
 > If you wish to use an alternative WinApps backend (other than `Docker`), uncomment and change `WAFLAVOR="docker"` to `WAFLAVOR="podman"` or `WAFLAVOR="libvirt"`.
 
-> [!NOTE]
-> If you encounter issues with tls certificate getting rejected, delete the existing `.pem` file with
-> `rm ~/.config/freerdp/server/127.0.0.1_3389.pem` and run
-> `xfreerdp3 /u:MyWindowsUser /p:MyWindowsPassword /v:127.0.0.1 /cert:tofu`
-> to set up Trust On First Authentication. Then retry the `setup.sh` script.
-
 #### Configuration Options Explained
 - If using a pre-existing Windows RDP server on your LAN, you must use `RDP_IP` to specify the location of the Windows server. You may also wish to configure a static IP address for this server.
 - If running a Windows VM using `libvirt` with NAT enabled, leave `RDP_IP` commented out and WinApps will auto-detect the local IP address for the VM.
@@ -450,13 +444,65 @@ FREERDP_COMMAND=""
 - If you enable `DEBUG`, a log will be created on each application start in `~/.local/share/winapps/winapps.log`.
 - If using a system on which the FreeRDP command is not `xfreerdp` or `xfreerdp3`, the correct command can be specified using `FREERDP_COMMAND`.
 
-### Step 4: Run the WinApps Installer
-Run the WinApps installer.
+### Step 4: Test FreeRDP
+1. Test establishing an RDP session by running the following command, replacing the `/u:`, `/p:`, and `/v:` values with the correct values specified in `~/.config/winapps/winapps.conf`.
+
+    ```bash
+    xfreerdp3 /u:"Your Windows Username" /p:"Your Windows Password" /v:192.168.122.2 /cert:tofu
+
+    # Or, if you installed FreeRDP using Flatpak
+    flatpak run --command=xfreerdp com.freerdp.FreeRDP /u:"Your Windows Username" /p:"Your Windows Password" /v:192.168.122.2 /cert:tofu
+    ```
+
+    - Please note that the correct `FreeRDP` command may vary depending on your system (e.g. `xfreerdp`, `xfreerdp3`, etc.).
+    - Ensure you use the correct IP address for your Windows instance in the above command.
+    - If prompted within the terminal window, choose to accept the certificate permanently.
+
+    If the Windows desktop appears in a `FreeRDP` window, the configuration was successful and the correct RDP TLS certificate was enrolled on the Linux host. Disconnect from the RDP session and skip the following debugging step.
+
+2. [DEBUGGING STEP] If an outdated or expired certificate is detected, the `FreeRDP` command will display output resembling the following. In this case, the old certificate will need to be removed and a new RDP TLS certificate installed.
+
+    ```
+    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+    @           WARNING: CERTIFICATE NAME MISMATCH!           @
+    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+    The hostname used for this connection (192.168.122.2:3389)
+    does not match the name given in the certificate:
+    Common Name (CN):
+            RDPWindows
+    A valid certificate for the wrong name should NOT be trusted!
+
+    The host key for 192.168.122.2:3389 has changed
+
+    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+    @    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
+    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+    IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
+    Someone could be eavesdropping on you right now (man-in-the-middle attack)!
+    It is also possible that a host key has just been changed.
+    The fingerprint for the host key sent by the remote host is 8e:b4:d2:8e:4e:14:e7:4e:82:9b:07:5b:e1:68:40:18:bc:db:5f:bc:29:0d:91:83:f9:17:f9:13:e6:51:dc:36
+    Please contact your system administrator.
+    Add correct host key in /home/rohanbarar/.config/freerdp/server/192.168.122.2_3389.pem to get rid of this message.
+    ```
+
+    If you experience the above error, delete any old or outdated RDP TLS certificates associated with Windows, as they can prevent `FreeRDP` from establishing a connection.
+
+    These certificates are located within `~/.config/freerdp/server/` and follow the naming format `<Windows-VM-IPv4-Address>_<RDP-Port>.pem` (e.g., `192.168.122.2_3389.pem`, `127.0.0.1_3389.pem`, etc.).
+
+    If you use FreeRDP for purposes other than WinApps, ensure you only remove certificates related to the relevant Windows VM. If no relevant certificates are found, no action is needed.
+
+    Following deletion, re-attempt establishing an RDP session.
+
+### Step 5: Run the WinApps Installer
+With Windows still powered on, run the WinApps installer.
+
 ```bash
 bash <(curl https://raw.githubusercontent.com/winapps-org/winapps/main/setup.sh)
 ```
 
-A list of supported additional arguments can be accessed by running `./setup.sh --help`.
+Once WinApps is installed, a list of additional arguments can be accessed by running `winapps-setup --help`.
 
 <img src="./demo/installer.gif" width=1000 alt="WinApps Installer Animation.">
 

packages/winapps-launcher/WinAppsLauncher.patch → packages/winapps-launcher/WinApps-Launcher.patch

@@ -1,5 +1,5 @@
---- a/WinAppsLauncher.sh
-+++ b/WinAppsLauncher.sh
+--- a/WinApps-Launcher.sh
++++ b/WinApps-Launcher.sh
 @@ -19,7 +19,7 @@ declare -rx EC_WIN_NOT_SPEC=6
  declare -rx EC_NO_WIN_FOUND=7
 

packages/winapps-launcher/default.nix

@@ -29,10 +29,10 @@ stdenv.mkDerivation rec {
     (callPackage ../winapps { })
   ];
 
-  patches = [ ./WinAppsLauncher.patch ];
+  patches = [ ./WinApps-Launcher.patch ];
 
   postPatch = ''
-    substituteAllInPlace WinAppsLauncher.sh
+    substituteAllInPlace WinApps-Launcher.sh
   '';
 
   installPhase = ''
@@ -41,7 +41,7 @@ stdenv.mkDerivation rec {
     mkdir -p $out
     cp -r ./Icons $out/Icons
 
-    install -m755 -D WinAppsLauncher.sh $out/bin/winapps-launcher
+    install -m755 -D WinApps-Launcher.sh $out/bin/winapps-launcher
     install -Dm444 -T Icons/AppIcon.svg $out/share/pixmaps/winapps.svg
 
     wrapProgram $out/bin/winapps-launcher \

packages/winapps/setup.patch

@@ -22,27 +22,6 @@ index b7d930d6..18000c65 100755
 
  # REMOTE DESKTOP CONFIGURATION
  readonly VM_NAME="RDPWindows"  # Name of the Windows VM (FOR 'libvirt' ONLY).
-@@ -130,13 +130,13 @@ function waTerminateScript() {
- # Role: Displays usage information for the script.
- function waUsage() {
-     echo -e "Usage:
--  ${COMMAND_TEXT}./setup.sh --user${CLEAR_TEXT}                                        # Install WinApps and selected applications in ${HOME}
--  ${COMMAND_TEXT}./setup.sh --system${CLEAR_TEXT}                                      # Install WinApps and selected applications in /usr
--  ${COMMAND_TEXT}./setup.sh --user --setupAllOfficiallySupportedApps${CLEAR_TEXT}      # Install WinApps and all officially supported applications in ${HOME}
--  ${COMMAND_TEXT}./setup.sh --system --setupAllOfficiallySupportedApps${CLEAR_TEXT}    # Install WinApps and all officially supported applications in /usr
--  ${COMMAND_TEXT}./setup.sh --user --uninstall${CLEAR_TEXT}                            # Uninstall everything in ${HOME}
--  ${COMMAND_TEXT}./setup.sh --system --uninstall${CLEAR_TEXT}                          # Uninstall everything in /usr
--  ${COMMAND_TEXT}./setup.sh --help${CLEAR_TEXT}                                        # Display this usage message."
-+  ${COMMAND_TEXT}winapps-setup --user${CLEAR_TEXT}                                        # Install WinApps and selected applications in ${HOME}
-+  ${COMMAND_TEXT}winapps-setup --system${CLEAR_TEXT}                                      # Install WinApps and selected applications in /usr
-+  ${COMMAND_TEXT}winapps-setup --user --setupAllOfficiallySupportedApps${CLEAR_TEXT}      # Install WinApps and all officially supported applications in ${HOME}
-+  ${COMMAND_TEXT}winapps-setup --system --setupAllOfficiallySupportedApps${CLEAR_TEXT}    # Install WinApps and all officially supported applications in /usr
-+  ${COMMAND_TEXT}winapps-setup --user --uninstall${CLEAR_TEXT}                            # Uninstall everything in ${HOME}
-+  ${COMMAND_TEXT}winapps-setup --system --uninstall${CLEAR_TEXT}                          # Uninstall everything in /usr
-+  ${COMMAND_TEXT}winapps-setup --help${CLEAR_TEXT}                                        # Display this usage message."
- }
-
- # Name: 'waGetSourceCode'
 @@ -155,13 +155,6 @@ function waGetSourceCode() {
          echo -e "${WARNING_TEXT}[WARNING]${CLEAR_TEXT} You might want to remove your old installation on '${SCRIPT_DIR_PATH}'."
      fi
@@ -80,24 +59,6 @@ index b7d930d6..18000c65 100755
  }
 
  # Name: 'waCheckInput'
-@@ -390,7 +370,7 @@ function waCheckExistingInstall() {
-
-         # Display the suggested action(s).
-         echo "--------------------------------------------------------------------------------"
--        echo -e "Please remove the existing WinApps installation using ${COMMAND_TEXT}./setup.sh --user --uninstall${CLEAR_TEXT}."
-+        echo -e "Please remove the existing WinApps installation using ${COMMAND_TEXT}winapps-setup --user --uninstall${CLEAR_TEXT}."
-         echo "--------------------------------------------------------------------------------"
-
-         # Terminate the script.
-@@ -410,7 +390,7 @@ function waCheckExistingInstall() {
-
-         # Display the suggested action(s).
-         echo "--------------------------------------------------------------------------------"
--        echo -e "Please remove the existing WinApps installation using ${COMMAND_TEXT}./setup.sh --system --uninstall${CLEAR_TEXT}."
-+        echo -e "Please remove the existing WinApps installation using ${COMMAND_TEXT}winapps-setup --system --uninstall${CLEAR_TEXT}."
-         echo "--------------------------------------------------------------------------------"
-
-         # Terminate the script.
 @@ -805,7 +785,7 @@ function waCheckGroupMembership() {
      # Identify groups the current user belongs to.
      USER_GROUPS=$(groups "$(whoami)")