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 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.