Documentation is unclear about how to configure a single AppVM application shortcut involving qvm-run and qubes.StartApp

[heinrich-ulbricht]

Qubes OS version:

R4.0

Affected component(s):

Documentation about shortcuts to AppVM applications (and some RPC service info)

---

Expected behavior:

I have an app saved to one AppVM home directory that is not automatically included in the list of available apps in this AppVM's menu - which is ok and expected. I now want to add a shortcut to this app by following the instructions of the official documentation.

Unfortunately, reading this documentation I was not able to achieve the following (but should be):

• creating a shortcut to an application in a single AppVM as advertised here
• using a .desktop file that resides inside this single AppVM
• referencing this .desktop file using qvm-run (with qubes.StartApp service) from dom0 as described in the Behind the scenes section of the documentation

As a technical user with no Linux background I should be able to configure this. I'm sure I made mistakes on my way and I'd like to improve the documentation so that people like me can get it running :)

Actual behavior:

Here the section If you only want to create a shortcut for a single AppVM, you can create a custom menu entry instead describes, how to add an application as shortcut by doing things entirely in dom0 while referring to qvm-run in the Behind the scenes section which says I can refer to a .desktop file in my AppVM. But exactly how to do this was not entirely clear to me.

My questions about these instructions are:

• Is it really ok to modify ~/.config/menus/applications-merged/<vmname>-vm.menu in dom0? It feels odd (for a newbie to the os) for several reasons:
  • There are no <vmname>-vm.menu files (the docs refer to them) in this folder, but rather user-<vmname>-vm.menu files - should I modify those instead?
  • The folder name applications-merged suggests the files in there are auto-generated and will be overwritten at some point - are my changes really persisted? Do I have to re-apply them after synchronizing shortcuts between VMs? I think it even says in the .menu files that these were auto-generated and that they shouldn't be touched, yet the documentation says to do so.
• In which folder do I have to place the .desktop file in the AppVM so it can be called via qvm-run and qubes.StartApp from dom0?
• While trying things I suspected my call to the qubes.StartApp service was wrong - how to debug this? Is qubes.StartApp documented somewhere? I found a list of services here, not including qubes.StartApp.
  • Specifically in the string qubes.StartApp+firefox (this is from a sample in the docs) - is firefox the name of the .desktop file (without ending) in the AppVM? Bonus question: how does this handle spaces in the filename; what's the syntax?
  • Is it even necessary to create a .desktop file in the AppVM? Can the binary of the app be referenced as well?

General notes:

With above questions clarified I can verify that my configuration is either wrong or correct and then file a technical issue if still necessary.

Any information or links to additional documentation I might not have been able to find are appreciated.

[heinrich-ulbricht]

I found my answers in QubesOS/qubes-core-agent-linux@22e261f which added the service qubes.StartApp. To make my scenario work you have to do the following:

1. create a .desktop file in the AppVM (in my case vault) in /home/user/.local/share/applications
   • create the applications folder if it doesn't yet exist
2. in a dom0 terminal create a .desktop file in ~/.local/share/applications as described in the docs
   • the Exec value can now reference the .desktop file in the AppVM, e.g.: Exec=qvm-run -q -a --service -- vault qubes.StartApp+keepass, where keepass is the name of the file created in step 1 (keepass.desktop) without its ending
3. still in dom0 terminal edit the user-<vm name>-vm.menu file in ~/.config/menus/applications-merged as described in the docs (but note the user- prefix that is missing in the docs)
   • this warning in the file can apparently be ignored: Do not edit manually - generated and managed by xdg-desktop-menu ...
   • these manual changes stay in this file also after calling qvm-sync-appmenus fedora-26

The reason it didn't work in my case was completely unrelated to any of this. In my AppVM .desktop file I had errors in the Exec value. To test and debug this you can call qubes-desktop-run in the AppVM to invoke your .desktop file directly. This is what qubes.StartApp does under the hood.

[heinrich-ulbricht]

I'm now using a different approach to creating shortcuts for specific AppVMs:

1. in your AppVM make sure there is a .desktop file as described in my last comment - this is going to be called
2. in a dom0 terminal create a .desktop file in ~/.local/share/qubes-appmenus/<vmname>/apps.templates (for details see my last comment as well)
   • the apps.templates directory did not exist in my case so I created it
   • don't use the real name of your AppVM in property values for Name, GenericName and Exec - use the placeholder %VMNAME% in its place; otherwise you'll get an error when opening the Qube's settings

You can check that this worked by calling qvm-appmenus --get-available --i-understand-format-is-unstable <vmname> in a dom0 terminal. This lists all available applications including the one you created.
Note: If you did not use the %VMNAME% placeholder correctly you will get the following error: AssertionError: template '<path to .desktop file>' does not contain name

This approach feels more in line with how the collection of AppVM shortcuts works. (Correct me if I'm wrong here.)
I don't know if this approach is specific to Qubes 4 so I'm hesitant to edit the documentation.

[marmarek]

Since #4152 got implemented, it should be enough to create .desktop file in the qube with command you want to run - it should be visible in qube settings in "applications" tab for this particular qube. You may need to press "Refresh Applications" button.
Since it's relatively new thing (especially GUI part of it), you may need to install updates from testing repositories.
Both what you've described and the above simplified version is specific to Qubes 4.x.