From e07224dec71a0d6832a8fa59cd9457485bbf5b7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Wed, 23 Jun 2021 14:47:09 +0200 Subject: [PATCH 1/4] GuiVM: add documentation --- user/advanced-topics/guivm.md | 134 ++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 user/advanced-topics/guivm.md diff --git a/user/advanced-topics/guivm.md b/user/advanced-topics/guivm.md new file mode 100644 index 00000000..2f71fbc2 --- /dev/null +++ b/user/advanced-topics/guivm.md @@ -0,0 +1,134 @@ +--- +lang: en +layout: doc +permalink: /doc/guivm-configuration/ +ref: 184 +title: GuiVM Configuration +--- + +## Gui domain + +In this section, we describe how to setup `GuiVM` in several case as described in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/). In all the cases, the base underlying TemplateVM used is `Fedora` with `XFCE` flavor to match current desktop choice in `dom0`. That can be adapted very easily for other desktops and templates. By default, the configured `GuiVM` is a management qube with global admin permissions `rwx` but can be adjusted to `ro` (see [Introducing the Qubes Admin API](https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/)) in pillar data of the corresponding `GuiVM` to setup. Please note that each `GuiVM` has no `NetVM`. + +> Note: The setup is done using `SaltStack` formulas with the `qubesctl` tool. When executing it, apply step can take time because it needs to download latest Fedora XFCE TemplateVM and install desktop dependencies. + + +### Hybrid GuiVM `sys-gui` + +Here, we describe how to setup `sys-gui` that we call *hybrid mode* or referenced as a *compromised solution* in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/#the-compromise-solution). + +[![sys-gui](/attachment/posts/guivm-hybrid.png)](/attachment/posts/guivm-hybrid.png) + +In `dom0`, enable the formula for `sys-gui` with pillar data: + +```bash +sudo qubesctl top.enable qvm.sys-gui +sudo qubesctl top.enable qvm.sys-gui pillar=True +``` + +then, execute it: + +```bash +sudo qubesctl --all state.highstate +``` + +You can now disable the `sys-gui` formula: +```bash +sudo qubesctl top.disable qvm.sys-gui +``` + +At this point, you need to shutdown all your running qubes as the `default_guivm` qubes global property has been set to `sys-gui`. In order to use `sys-gui` as GuiVM, you need to logout and select `lightdm` session to *Gui Domain (sys-gui)*. Once logged, you are running `sys-gui` as fullscreen window and you can perform any operation as if you would be in `dom0` desktop. + +> Note: In order to go back to `dom0` desktop, you need to logout and then, select `lightdm` session to *Session Xfce*. + +### GPU GuiVM `sys-gui-gpu` + +Here, we describe how to setup `sys-gui-gpu` which is a `GuiVM` with *GPU passthrough* in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/#gpu-passthrough-the-perfect-world-desktop-solution). + +[![sys-gui-gpu](/attachment/posts/guivm-gpu.png)](/attachment/posts/guivm-gpu.png) + +In `dom0`, enable the formula for `sys-gui-gpu` with pillar data: + +```bash +sudo qubesctl top.enable qvm.sys-gui-gpu +sudo qubesctl top.enable qvm.sys-gui-gpu pillar=True +``` + +then, execute it: + +```bash +sudo qubesctl --all state.highstate +``` + +You can now disable the `sys-gui-gpu` formula: + +```bash +sudo qubesctl top.disable qvm.sys-gui-gpu +``` + +At this point, you need to reboot your Qubes OS machine in order to boot into `sys-gui-gpu`. + +> None: For some platforms, it can be sufficient to shutdown all the running qubes and starting `sys-gui-gpu`. Unfortunately, it has been observed that detaching and attaching some GPU cards from `dom0` to `sys-gui-gpu` can freeze computer. We encourage reboot to prevent any data loss. + +Once, `lightdm` is started, you can log as `user` where `user` refers to the first `dom0` user in `qubes` group and with corresponding `dom0` password. + +### VNC GuiVM `sys-gui-vnc` + +Here, we describe how to setup `sys-gui-vnc` that we call a *remote* `GuiVM` or referenced as *with a virtual server* in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/#virtual-server-the-perfect-remote-solution). + +[![sys-gui-vnc](/attachment/posts/guivm-vnc.png)](/attachment/posts/guivm-vnc.png) + +In `dom0`, enable the formula for `sys-gui-vnc` with pillar data: + +```bash +sudo qubesctl top.enable qvm.sys-gui-vnc +sudo qubesctl top.enable qvm.sys-gui-vnc pillar=True +``` + +then, execute it: + +```bash +sudo qubesctl --all state.highstate +``` + +You can now disable the `sys-gui-vnc` formula: + +```bash +sudo qubesctl top.disable qvm.sys-gui-vnc +``` + +At this point, you need to shutdown all your running qubes as the `default_guivm` qubes global property has been set to `sys-gui-vnc`. Then, you can start `sys-gui-vnc`: + +```bash +qvm-start sys-gui-vnc +``` + +A VNC server session is running on `localhost:5900` in `sys-gui-vnc`. In order to reach the `VNC` server, we encourage to not connect `sys-gui-vnc` to a `NetVM` but rather to use another qube for remote access, say `sys-remote`. First, you need to bind port 5900 of `sys-gui-vnc` into a `sys-remote` local port (you may want to use another port than 5900 to reach `sys-remote` from the outside). For that, use `qubes.ConnectTCP` RPC service (see [Firewall](/doc/firewall). Then, you can use any `VNC` client to connect to you `sys-remote` on the chosen local port (5900 if you kept the default one). For the first connection, you will reach `lightdm` for which you can log as `user` where `user` refers to the first `dom0` user in `qubes` group and with corresponding `dom0` password. + +> Note: `lightdm` session remains logged even if you disconnect your `VNC` client. Ensure to lock or log out before disconnecting your `VNC` client session. + +### Troobleshooting + +#### Delete GuiVM + +The following commands have to be run in `dom0`. + +> Note: For the case of `sys-gui-gpu`, you need to prevent Qubes OS autostart of any qube to reach `dom0`. For that, you need to boot Qubes OS with [`qubes.skip_autostart`](/doc/skip-qubes-autostart/) GRUB parameter. + +Set `default_guivm` as `dom0`: + +```bash +qubes-prefs default_guivm dom0 +``` + +and for every selected qubes not using default value for `guivm` property, for example with a qube `personal`: + +```bash +qvm-prefs personal guivm dom0 +``` + +You are now able to delete the GuiVM, for example `sys-gui-gpu`: + +```bash +qvm-remove -y sys-gui-gpu +``` From bb84bcef90c496acae41ec59712873e8ac72bebe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Thu, 29 Jul 2021 15:57:26 +0200 Subject: [PATCH 2/4] GuiVM: second pass on documentation Add @marmarek's suggestions --- user/advanced-topics/guivm.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/user/advanced-topics/guivm.md b/user/advanced-topics/guivm.md index 2f71fbc2..9f5ea605 100644 --- a/user/advanced-topics/guivm.md +++ b/user/advanced-topics/guivm.md @@ -8,14 +8,14 @@ title: GuiVM Configuration ## Gui domain -In this section, we describe how to setup `GuiVM` in several case as described in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/). In all the cases, the base underlying TemplateVM used is `Fedora` with `XFCE` flavor to match current desktop choice in `dom0`. That can be adapted very easily for other desktops and templates. By default, the configured `GuiVM` is a management qube with global admin permissions `rwx` but can be adjusted to `ro` (see [Introducing the Qubes Admin API](https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/)) in pillar data of the corresponding `GuiVM` to setup. Please note that each `GuiVM` has no `NetVM`. +In this section, we describe how to setup `GuiVM` in several case as described in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/). In all the cases, the base underlying TemplateVM used is `Fedora` with `XFCE` flavor to match current desktop choice in `dom0`. That can be adapted very easily for other desktops and templates. By default, the configured `GuiVM` is a management qube with global admin permissions `rwx` but can be adjusted to `ro` (see [Introducing the Qubes Admin API](https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/)) in pillar data of the corresponding `GuiVM` to setup. For example, pillar data for `sys-gui` located at `/srv/pillar/base/qvm/sys-gui.sls`. Please note that each `GuiVM` has no `NetVM`. > Note: The setup is done using `SaltStack` formulas with the `qubesctl` tool. When executing it, apply step can take time because it needs to download latest Fedora XFCE TemplateVM and install desktop dependencies. ### Hybrid GuiVM `sys-gui` -Here, we describe how to setup `sys-gui` that we call *hybrid mode* or referenced as a *compromised solution* in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/#the-compromise-solution). +Here, we describe how to setup `sys-gui` that we call *hybrid mode* or referenced as a *compromise solution* in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/#the-compromise-solution). [![sys-gui](/attachment/posts/guivm-hybrid.png)](/attachment/posts/guivm-hybrid.png) @@ -37,7 +37,7 @@ You can now disable the `sys-gui` formula: sudo qubesctl top.disable qvm.sys-gui ``` -At this point, you need to shutdown all your running qubes as the `default_guivm` qubes global property has been set to `sys-gui`. In order to use `sys-gui` as GuiVM, you need to logout and select `lightdm` session to *Gui Domain (sys-gui)*. Once logged, you are running `sys-gui` as fullscreen window and you can perform any operation as if you would be in `dom0` desktop. +At this point, you need to shutdown all your running qubes as the `default_guivm` qubes global property has been set to `sys-gui`. In order to use `sys-gui` as GuiVM, you need to logout and, in the top right corner, select `lightdm` session type to *Gui Domain (sys-gui)*. Once logged, you are running `sys-gui` as fullscreen window and you can perform any operation as if you would be in `dom0` desktop. > Note: In order to go back to `dom0` desktop, you need to logout and then, select `lightdm` session to *Session Xfce*. @@ -66,11 +66,21 @@ You can now disable the `sys-gui-gpu` formula: sudo qubesctl top.disable qvm.sys-gui-gpu ``` +One more step is needed: attaching the actual GPU to `sys-gui-gpu`. This can be done either manually via `qvm-pci` (remember to enable permissive option), or via: + +```bash +sudo qubesctl state.sls qvm.sys-gui-gpu-attach-gpu. +``` + +The latter option assumes Intel graphics card (it has hardcoded PCI address). If you don't have Intel graphics card, please use the former method with `qvm-pci` (see [How to use PCI devices](/doc/how-to-use-pci-devices/)). + +> Note: Some platforms can have multiple GPU. For example on laptops, it is usual to have HDMI or DISPLAY port linked to the secondary GPU (generally called _discrete GPU_). In such case, you have to also attach the secondary GPU to `sys-gui-gpu` with permission option. + At this point, you need to reboot your Qubes OS machine in order to boot into `sys-gui-gpu`. -> None: For some platforms, it can be sufficient to shutdown all the running qubes and starting `sys-gui-gpu`. Unfortunately, it has been observed that detaching and attaching some GPU cards from `dom0` to `sys-gui-gpu` can freeze computer. We encourage reboot to prevent any data loss. +> Note: For some platforms, it can be sufficient to shutdown all the running qubes and starting `sys-gui-gpu`. Unfortunately, it has been observed that detaching and attaching some GPU cards from `dom0` to `sys-gui-gpu` can freeze computer. We encourage reboot to prevent any data loss. -Once, `lightdm` is started, you can log as `user` where `user` refers to the first `dom0` user in `qubes` group and with corresponding `dom0` password. +Once, `lightdm` is started, you can log as `user` where `user` refers to the first `dom0` user in `qubes` group and with corresponding `dom0` password. A better approach for handling password is currently discussed in [QubesOS/qubes-issues#6740](https://github.com/QubesOS/qubes-issues/issues/6740). ### VNC GuiVM `sys-gui-vnc` @@ -107,8 +117,15 @@ A VNC server session is running on `localhost:5900` in `sys-gui-vnc`. In order t > Note: `lightdm` session remains logged even if you disconnect your `VNC` client. Ensure to lock or log out before disconnecting your `VNC` client session. +> **WARNING**: This setup raises multiple security issues: 1) Anyone who can reach the `VNC` server, can take over the control of the Qubes OS machine, 2) A second client can connect even if a connection is already active and potentially get disconnected, 3) You can get disconnected by some unrelated network issues. Generally, if this `VNC` server is exposed to open network, it must be protected with some other (cryptographic) layer like `VPN`. The setup as is, is useful only for purely testing machine. + + ### Troobleshooting +#### Application menu lacks qubes entries in a fresh GuiVM + +See [QubesOS/qubes-issues#5804](https://github.com/QubesOS/qubes-issues/issues/5804) + #### Delete GuiVM The following commands have to be run in `dom0`. @@ -132,3 +149,7 @@ You are now able to delete the GuiVM, for example `sys-gui-gpu`: ```bash qvm-remove -y sys-gui-gpu ``` + +#### General issue + +For any general GuiVM issue, please take a loot at existing issues `QubesOS/qubes-issues` under [C: gui-domain](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+gui-domain%22) label. From 4b0ced18d7433835d5590136d2a036a19c25ff1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Thu, 29 Jul 2021 21:40:28 +0200 Subject: [PATCH 3/4] GuiVM: fix typo in a note From @tlaurion's suggestion --- user/advanced-topics/guivm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/advanced-topics/guivm.md b/user/advanced-topics/guivm.md index 9f5ea605..03e168ba 100644 --- a/user/advanced-topics/guivm.md +++ b/user/advanced-topics/guivm.md @@ -74,7 +74,7 @@ sudo qubesctl state.sls qvm.sys-gui-gpu-attach-gpu. The latter option assumes Intel graphics card (it has hardcoded PCI address). If you don't have Intel graphics card, please use the former method with `qvm-pci` (see [How to use PCI devices](/doc/how-to-use-pci-devices/)). -> Note: Some platforms can have multiple GPU. For example on laptops, it is usual to have HDMI or DISPLAY port linked to the secondary GPU (generally called _discrete GPU_). In such case, you have to also attach the secondary GPU to `sys-gui-gpu` with permission option. +> Note: Some platforms can have multiple GPU. For example on laptops, it is usual to have HDMI or DISPLAY port linked to the secondary GPU (generally called _discrete GPU_). In such case, you have to also attach the secondary GPU to `sys-gui-gpu` with permissive option. At this point, you need to reboot your Qubes OS machine in order to boot into `sys-gui-gpu`. From 777e1bccbbf05e3248077478c77829f7a1221f0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Sun, 26 Dec 2021 22:34:28 +0100 Subject: [PATCH 4/4] guivm: use relative links --- user/advanced-topics/guivm.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/user/advanced-topics/guivm.md b/user/advanced-topics/guivm.md index 03e168ba..f4eedc18 100644 --- a/user/advanced-topics/guivm.md +++ b/user/advanced-topics/guivm.md @@ -8,14 +8,14 @@ title: GuiVM Configuration ## Gui domain -In this section, we describe how to setup `GuiVM` in several case as described in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/). In all the cases, the base underlying TemplateVM used is `Fedora` with `XFCE` flavor to match current desktop choice in `dom0`. That can be adapted very easily for other desktops and templates. By default, the configured `GuiVM` is a management qube with global admin permissions `rwx` but can be adjusted to `ro` (see [Introducing the Qubes Admin API](https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/)) in pillar data of the corresponding `GuiVM` to setup. For example, pillar data for `sys-gui` located at `/srv/pillar/base/qvm/sys-gui.sls`. Please note that each `GuiVM` has no `NetVM`. +In this section, we describe how to setup `GuiVM` in several case as described in [GUI Domain](/news/2020/03/18/gui-domain/). In all the cases, the base underlying TemplateVM used is `Fedora` with `XFCE` flavor to match current desktop choice in `dom0`. That can be adapted very easily for other desktops and templates. By default, the configured `GuiVM` is a management qube with global admin permissions `rwx` but can be adjusted to `ro` (see [Introducing the Qubes Admin API](/news/2017/06/27/qubes-admin-api/)) in pillar data of the corresponding `GuiVM` to setup. For example, pillar data for `sys-gui` located at `/srv/pillar/base/qvm/sys-gui.sls`. Please note that each `GuiVM` has no `NetVM`. > Note: The setup is done using `SaltStack` formulas with the `qubesctl` tool. When executing it, apply step can take time because it needs to download latest Fedora XFCE TemplateVM and install desktop dependencies. ### Hybrid GuiVM `sys-gui` -Here, we describe how to setup `sys-gui` that we call *hybrid mode* or referenced as a *compromise solution* in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/#the-compromise-solution). +Here, we describe how to setup `sys-gui` that we call *hybrid mode* or referenced as a *compromise solution* in [GUI Domain](/news/2020/03/18/gui-domain/#the-compromise-solution). [![sys-gui](/attachment/posts/guivm-hybrid.png)](/attachment/posts/guivm-hybrid.png) @@ -43,7 +43,7 @@ At this point, you need to shutdown all your running qubes as the `default_guivm ### GPU GuiVM `sys-gui-gpu` -Here, we describe how to setup `sys-gui-gpu` which is a `GuiVM` with *GPU passthrough* in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/#gpu-passthrough-the-perfect-world-desktop-solution). +Here, we describe how to setup `sys-gui-gpu` which is a `GuiVM` with *GPU passthrough* in [GUI Domain](/news/2020/03/18/gui-domain/#gpu-passthrough-the-perfect-world-desktop-solution). [![sys-gui-gpu](/attachment/posts/guivm-gpu.png)](/attachment/posts/guivm-gpu.png) @@ -84,7 +84,7 @@ Once, `lightdm` is started, you can log as `user` where `user` refers to the fir ### VNC GuiVM `sys-gui-vnc` -Here, we describe how to setup `sys-gui-vnc` that we call a *remote* `GuiVM` or referenced as *with a virtual server* in [GUI Domain](https://www.qubes-os.org/news/2020/03/18/gui-domain/#virtual-server-the-perfect-remote-solution). +Here, we describe how to setup `sys-gui-vnc` that we call a *remote* `GuiVM` or referenced as *with a virtual server* in [GUI Domain](/news/2020/03/18/gui-domain/#virtual-server-the-perfect-remote-solution). [![sys-gui-vnc](/attachment/posts/guivm-vnc.png)](/attachment/posts/guivm-vnc.png)