How to install/use sys-gui (collecting all related information)

User Support General
1

First, if you don’t know what sys-gui is, you need to read this first: Qubes Architecture Next Steps: The GUI Domain | Qubes OS

Objective of this document:
Currently (2021-10-01) the best documentation for on how to install/use sys-gui appears to be here. When 4.1 is formally released this information should be all that’s needed.

However, If you attempt this at the current time (before the formal release), it’s easy to run into issues, so I’m going to document one install process that did work, and try to collect other sys-gui related information here

Checking the current status of sys-gui

One installation method for sys-gui that worked:
First, check https://www.qubes-os.org/downloads/ to see if 4.1 has been formally released by the time you read this. If 4.1 has been formally released don’t use this, but try using that as it’s probably your best bet using the standard installation procedure
This documents a deterministic installation procedure that got it working. It starts with the iso install so you have the option to replicate it entirely.

  • Install Qubes-R4.1.0-beta1-x86_64.iso https://mirrors.edge.kernel.org/qubes/iso/ using pretty much the standard installation procedure (allowing for some minor changes)

  • Use installation defaults for most things (example: I left the default template as fedora as I didn’t know if the debian template was stable enough)

  • IMPORTANT: After installing 4.1 beta1, do not update becuase updating causes a issue with the fedora-34?-xfce template being missing. This pull request supposedly fixes it, so do not update until this pull request has been merged and deployed: Use qvm.template_installed for installing template for sys-gui too by marmarek · Pull Request #42 · QubesOS/qubes-mgmt-salt-dom0-virtual-machines · GitHub
    (Note: Without the pull reqest, if you install the fedora-34?-xfce template yourself then it seems to work, but then there is no qubes-related packages installed) (give link to conversation about this)

  • Then just follow then steps in the guide listed above, which are:

    qubesctl top.enable qvm.sys-gui
    qubesctl top.enable qvm.sys-gui pillar=True
    qubesctl --all state.highstate

  • Give sys-gui access to sys-net, sys-firewall and the templates by doing: qubes-prefs default_guivm sys-gui
    (I believe this will be automatic in the formal 4.1 relrease)

  • Shut down VM’s (I.E. sys-firewall, sys-usb, sys-net)

  • Log out

  • Click the things in the upper right corner to find a choice between “sys-gui” and “xfce”(I.E. dom0)

  • Choose the “sys-gui” one

  • Log in

  • IMPORTANT: Do not let the screensaver (the lock screen) kick in before you can reset the password! The password will be unknown once the screensaver kicks in. You must reset the password with sudo passwd user each and every time you boot sys-gui (This is a bug that happens in sys-gui (but not sys-gui-gpu or sys-gui-vnc), that is documented in Make user password persistent in GUI domain · Issue #6740 · QubesOS/qubes-issues · GitHub )
    If you lock yourself out, you can reboot your system by hitting Ctrl-Alt-F2, then login as the dom0 user, and do sudo shutdown now

  • Open a terminal in sys-gui and add missing menus with things like:

    qvm-sync-appmenus sys-net
qvm-sync-appmenus sys-firewall

You should now be able to create new qubes from templates, start them, and add them to the left menu with the above qvm-sync-appmenus command

One installation method for sys-gui-vnc that worked
Note: This procedure was done direct from a 4.1 rc1 install, without updating. If you want to be sure you get the same results, do not update.

  • Install Qubes-R4.1.0-rc1-x86_64.iso https://mirrors.edge.kernel.org/qubes/iso/ using pretty much the standard installation procedure (allowing for some minor changes)

  • Use installation defaults for most things (example: I left the default template as fedora as I didn’t know if the debian template was stable enough)

  • Following the standard sys-gui-vnc instructions,

    sudo qubesctl top.enable qvm.sys-gui-vnc
sudo qubesctl top.enable qvm.sys-gui-vnc pillar=True
sudo qubesctl --all state.highstate
qubes-prefs default_guivm sys-gui-vnc

    (Note that from comments, the “qubes-prefs” line sounds like it’s supposed to be done as part of the salt script, but it does not seem to actually happen)

  • Important: You need to go to “Qube Settings” of sys-gui-vnc and add to the service list a new guivm-vnc service. The salt script we used to create this will automatically add a guivm-gui-vnc which does not seem to work (as of 4.1rc1)

  • Now create sys-remote:

    qvm-clone debian-11 debian-11-vnc
qvm-run debian-11-vnc 'sudo apt-get update'
qvm-run debian-11-vnc 'sudo apt-get install xtightvncviewer'
#cant install 2 packages in one apt-get command from qvm-run, so must seperate it out into another qvm-run
#qvm-run debian-11-vnc 'sudo apt-get install tigervnc-viewer'
qvm-shutdown debian-11-vnc
qvm-create --template debian-11-vnc --label purple --property netvm=none sys-remote
qvm-prefs sys-remote guivm dom0

    (for some reason the “netvm=none” parameter does not work, so load the sys-remote qubes settings and change it to none)

  • now set up the networking according to Firewall | Qubes OS
    (still in dom0):
    (Note that this part is still not working yet)

    echo 'sys-remote @default allow,target=sys-gui-vnc'  >> /etc/qubes-rpc/policy/qubes.ConnectTCP
qvm-run sys-remote 'qvm-connect-tcp 5900:@default:5900'

    (note: this command seems to set up the connection, but it also seems to not return after its done. That’s fine. Just leave it and open another dom0 terminal if you need to type another dom0 command)

  • open a terminal to sys-remote. in that terminal type:

    netstat -lntp | grep 5900    #this is just to check that the port is there
vncviewer localhost::5900

    You should see “connected to localhost port 5900”, then the vncviewer should show you the sys-gui-vnc login screen
    (Note: if it’s your first time typing vncviewer localhost::5900 from sys-remote, qubes may say “sys-gui-vnc is starting” then vncviewer may suddenly say: VNC server closed connection. If this happens just wait till sys-gui-vnc finishes starting up then try it again)

The above procedure successfully ended in showing the sys-gui-vnc login screen, so sys-gui-vnc was working! However… when trying to login as “user” the password is not the password of “user” from dom0. This would make it pretty worth worthless, so a pointer to instructions related to working around the issue are added below. (Note: Was Make user password persistent in GUI domain · Issue #6740 · QubesOS/qubes-issues · GitHub just wrong about the password hash successfully coping to sys-gui-vnc (meaning it’s the same issue as sys-gui?))

Basically you need to change the “!” in a line in /rw/config/rc.local inside sys-gui-vnc that looks like:
sudo usermod -p '!' user
to the hash of your password (visible in dom0 via sudo cat /etc/shadow

This can be done by mounting the LVM image /dev/qubes_dom0/vm-sys-gui-vnc-private (instructions for doing this are at: How to mount LVM images | Qubes OS )

Other resources:
sys-gui related comments:

General issues trying to update in 4.1 beta1:

4 Likes
2

This is an issue fixed here: Use qvm.template_installed for installing template for sys-gui too by marmarek · Pull Request #42 · QubesOS/qubes-mgmt-salt-dom0-virtual-machines · GitHub (observe its status, it’s not merged yet)

You should rather do qvm-sync-appmenus with template names as arguments.

3

Thanks, your information has been integrated into the top post.

Sorry, I accidentally hit control-Enter (which apparently sends the post) before I was ready. The full version follows. (I copied it below in case you only access this via email)

Summary of Current Version

First, if you don’t know what sys-gui is, you need to read this first: Qubes Architecture Next Steps: The GUI Domain | Qubes OS

Objective of this document:
Currently (2021-10-01) the best documentation for on how to install/use sys-gui appears to be here. When 4.1 is formally released this information should be all that’s needed.

However, If you attempt this at the current time (before the formal release), it’s easy to run into issues, so I’m going to document one install process that did work, and try to collect other sys-gui related information here

Current status of sys-gui

One installation method that worked:
First, check https://www.qubes-os.org/downloads/ to see if 4.1 has been formally released by the time you read this. If 4.1 has been formally released don’t use this, but try using that as it’s probably your best bet.

  • Install Qubes-R4.1.0-beta1-x86_64.iso https://mirrors.edge.kernel.org/qubes/iso/ using pretty much the standard installation procedure (allowing for some minor changes)

  • Use installation defaults for most things (example: I left the default template as fedora as I didn’t know if the debian template was stable enough)

  • IMPORTANT: After installing 4.1 beta1, do not update becuase updating causes a issue with the fedora-34?-xfce template being missing. This pull request supposedly fixes it, so do not update until this pull request has been merged and deployed: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/pull/42
    (Note: Without the pull reqest, if you install the fedora-34?-xfce template yourself then it seems to work, but then there is no qubes-related packages installed) (give link to conversation about this)

  • Then just follow then steps in the guide listed above, which are:

    qubesctl top.enable qvm.sys-gui
    qubesctl top.enable qvm.sys-gui pillar=True
    qubesctl --all state.highstate

  • Give sys-gui access to sys-net, sys-firewall and the templates by doing: qubes-prefs default_guivm sys-gui
    (I believe this will be automatic in the formal 4.1 relrease)

  • Shut down VM’s (I.E. sys-firewall, sys-usb, sys-net)

  • Log out

  • Click the things in the upper right corner to find a choice between “sys-gui” and “xfce”(I.E. dom0)

  • Choose the “sys-gui” one

  • Log in

  • IMPORTANT: Do not let the screensaver (the lock screen) kick in, as the password will be unknown. Before the screensaver/lock screen kicks in, you must disable it.
    (Note: resetting the password in sys-gui terminal does not seem to update the password needed by the lock screen)

  • Open a terminal in sys-gui and add missing menus with things like:

    qvm-sync-appmenus sys-net
qvm-sync-appmenus sys-firewall

You should now be able to create new qubes from templates, start them, and add them to the left menu with the above qvm-sync-appmenus command

Other resources:
sys-gui related comments:
How to enable the (new) GUI VM? - #30 by zeroday-2023
Sys-gui in Qubes 4.1 - devel - #2 by adw
Feedback Qubes OS alpha with sys-gui
General issues trying to update in 4.1 beta1:
4.1beta upgrade: stage1 errors

1 Like
4

You quoted me saying something mistaken which I then acknowledged two posts later. (This was all back in Sept 2020.) I’ve edited your post to link to the general thread instead of my mistaken comment so as not to mislead others.

5

sys-gui-vnc issue: (possibly no vnc-server in it, or possibly a ConnectTCP issue?)

I went through the sys-gui-vnc setup as I added the commands to this article, but at the end, when doing “vncviewer localhost” instead of showing something a vnc-viewer into a login screen, it says connected to localhost port 5900, then says a connection closed error after I rebooted dom0, (and redid the qvm-connect-tcp command) it gave a connection refused error.

The full details are listed below. Is it possible that there is some connect-tcp service that must be enabled or something? Or is it possible that it’s not listening on port 5900 inside sys-gui-vnc?

(Not-yet working) procedure for setting up sys-gui-vnc (added above)

One partial installation method for sys-gui-vnc (that only partly worked so far)
Note: This procedure was not done direct from iso install. Many commands were hit after iso install (attempting to get sys-gui working) before sys-gui-vnc was attempted, so this will not be fully deterministic.

  • Following the standard sys-gui-vnc instructions,

    sudo qubesctl top.enable qvm.sys-gui-vnc
sudo qubesctl top.enable qvm.sys-gui-vnc pillar=True
sudo qubesctl --all state.highstate
qubes-prefs default_guivm sys-gui-vnc

    (Note that from comments, the “qubes-prefs” line sounds like it’s supposed to be done as part of the salt script, but it does not seem to actually happen)

  • Now create sys-remote:

    qvm-clone debian-11 debian-11-vnc
qvm-run debian-11-vnc 'sudo apt-get update; sudo apt-get install xtightvncviewer tigervnc-viewer'
qvm-shutdown debian-11
qvm-create --template debian-11-vnc --label-purple --property netvm=none sys-remote
qvm-prefs sys-remote guivm dom0

    (for some reason the “netvm=none” parameter does not work, so load the sys-remote qubes settings and change it to none)

  • now set up the networking according to Firewall | Qubes OS
    (still in dom0):
    (Note that this part is still not working yet)

    echo 'sys-remote @default allow,target=sys-gui-vnc'  >> /etc/qubes-rpc/policy/qubes.ConnectTCP
qvm-run sys-remote 'qvm-connect-tcp 5900:@default:5900'

    (note: this command seems to set up the connection, but it also seems to not return after its done)

  • open a terminal to sys-remote. in that terminal type:

    netstat -lntp | grep 5900    #this is just to check that the port is there
vncviewer localhost

    You should see “connected to localhost port 5900”, then the vncviewer should show you the sys-gui-vnc login screen

6

For sys-gui-vnc, you need to enable the guivm-vnc service for the VNC server in sys-gui-vnc to start.

I remember running into this - the salt forumla used the guivm-vnc-gui service name. It was on my TODOs to investigate if this is a salt bug or something extra that wasn’t documented. What that means is, I have both services listed because I’m lazy and it worked.

As an example of “what works” (and purely just one approach), I do this:

  1. run sshd in sys-remote via /rw/config/rc.local and storing sshd config and host keys under /rw/config/ssh/.
  2. Port 22 from sys-net makes its way to sys-remote with forwarding
  3. qubes.ConnectTCP+5900 RPC policy allowed from sys-remote to sys-gui-vnc
  4. qvm-connect-tcp in sys-remote binding sys-remote:5900 to sys-gui-vnc:5900
  5. Connect from the outside via ssh with yet another local bind on the ssh command line (-L 5900:127.0.0.1:5900)
  6. Run vncviewer localhost::5900 on my non-Qubes machine after ssh’ing in to sys-remote

This way, the path is:

non-Qubes machine – [tcp/ip/ssh] – [internet] → sys-net → [ssh] sys-remote → [vnc] sys-gui-vnc.

7

In my case (i915 driver), sys-gui worked as is in the descriptions. but some ui flickers are present almost on every paint.

i blacklisted i915 in dom0

i switched to sys-gui-gpu, but there is a gotcha… for some reason, dom0 loads i915 module. and unless it is unloaded, starting sys-gui-gpu crashes the system immediately.
and blacklisting the i915 might be a multi-step process. now i did it and yeah sys-gui-gpu works… and apparently it is much faster, responsive and feels so too. than the dom0.

Windows are not security-colored, window title bars are all grey at the moment…

8

That was it! After switching to 4.1 rc1, then adding guivm-vnc service seems to have made it work. Thanks.

How are you setting the user password inside sys-gui-vnc so you can actually log into it? :slight_smile: (especially since qvm-run sys-gui-vnc {command} seems to never actually work, just hang)

Anyway, I’ve updated the sys-gui-vnc procedure above to the new “kinda working” (I.E. working, but you can’t log in) procedure.

9

I was able to work around the password problem. Added the following to the OP.

Basically you need to change the “!” in a line in /rw/config/rc.local inside sys-gui-vnc that looks like:
sudo usermod -p '!' user
to the hash of your password (visible in dom0 via sudo cat /etc/shadow )

This can be done by mounting the LVM image /dev/qubes_dom0/vm-sys-gui-vnc-private (instructions for doing this are at: How to mount LVM images | Qubes OS )

10

Does any new doc or guide have been published since ?

I am trying to install & configure a standard “sys-gui” but I have many issues.
By following the doc, it install correctly.

Issues I am having:

  • How can I launch a dom0 xterm or anything in dom0
  • Copying file from dom0 to sys-gui seems to not work.
  • Qubes clipboard (copy+paste) doesn’t work by default. The Qube gui to configure that crash when I launch it. I solved this by configuring the copy/paste shortcut using command line
  • I tried to switch the keyboard layout from US to french. Never saw anything shitting that much on the keyboard layout, it is quite ridiculous. Currently trying to understand how to change the layout to a proper french layout, but none of the things I known seems to be working.
  • Screenlocker issue as already stated in this thread
11

fedora-36-xfce template EOL

Shouldn’t the sys-gui template be using a more up-to-date version of fedora like f37/38?

Why was fedora chosen instead of Devuan or something?

12
13

The Saltstack files you edited were:

/srv/pillar/base/qvm/sys-gui.sls?

when I check this file inside dom0 it is virtually blank inside.

I would like to try running the Saltstack script again using a more recent Fedora-xfce version.

14

The correct Saltstack formula directory is /srv/formulas/base/virtual-machines-formula/qvm/