diff --git a/user/troubleshooting/app-menu-shortcut-troubleshooting.md b/user/troubleshooting/app-menu-shortcut-troubleshooting.md index 4b918736..dd5d7d55 100644 --- a/user/troubleshooting/app-menu-shortcut-troubleshooting.md +++ b/user/troubleshooting/app-menu-shortcut-troubleshooting.md @@ -16,19 +16,56 @@ Clicking on such shortcut runs the assigned application in its app qube. ![dom0-menu.png"](/attachment/doc/r4.0-dom0-menu.png) -To make applications newly installed via the OS's package manager show up in the menu, use the `qvm-sync-appmenus` command (Linux qubes do this automatically): +How-to add a shortcut +--------------------- -`qvm-sync-appmenus vmname` +With the graphical user interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -After that, select the *Add more shortcuts* entry in the qube's submenu to customize which applications are shown: +To make applications newly installed show up in the menu, you can use the qube's *Settings*. Under the *Applications* tab, use the *Refresh Applications* button. Linux qubes do this automatically, if the *Settings* are opened after the installation of the package. ![dom0-appmenu-select.png"](/attachment/doc/r4.0-dom0-appmenu-select.png) -The above image shows that Windows HVMs are also supported (provided that Qubes Tools are installed). +After that, use the directional buttons (`>`, `>>`, `<` or `<<`) to customize which applications are shown, by moving them to the *Applications shown in App Menu* part (on the right side). Use the *Apply* (or *Ok*) button to see the changes in the app menu. + +With the console user interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To update the list of available applications, use the `qvm-sync-appmenus` command in dom0, replacing `` by the qube name: + +```console +$ qvm-sync-appmenus +``` + +When using the *Refresh Applications* button in a qube's settings, the command `qvm-sync-appmenus` is used at least one time. When refreshing an AppvM applications, it is also run against the template. So the console equivalent of clicking the *Refresh button* is the following (always in dom0): + +```console +$ qvm-sync-appmenus +$ qvm-sync-appmenus +``` + +In dom0, the `qvm-appmenus` tool allows the user to see the list of available applications (unstable feature), the whitelist of currently show application (unstable feature) and to change this list: + +```console +$ qvm-appmenus --set-whitelist +``` + +To change the whitelist shown in app menu, you need to provide a list of the desktop entries. Each line contains a desktop entry name, with its `.desktop` extension, like this: + +``` +qubes-open-file-manager.desktop +qubes-run-terminal.desktop +[...] +``` + +You can replace the file path by a single hyphen (`-`) to read it from standard input. What if my application has not been automatically included in the list of available apps? ----------------------------------------------------------------------------------------- +Missing desktop entry +^^^^^^^^^^^^^^^^^^^^^ + Sometimes applications may not have included a `.desktop` file and may not be detected by `qvm-sync-appmenus`. Other times, you may want to make a web shortcut available from the Qubes start menu. @@ -42,22 +79,20 @@ To do this: ``` [Desktop Entry] - Version=1.0 Type=Application - Terminal=false - Icon=/usr/share/icons/Adwaita/256x256/devices/scanner.png Name=VueScan - GenericName=Scanner - Comment=Scan Documents - Categories=Office;Scanning; Exec=vuescan ``` -3. In dom0, run `qvm-sync-appmenus `. -4. Go to VM Settings of the app qube(s) to which you want to add the new shortcut, then the Applications tab. - Move the newly created shortcut to the right under selected. +3. Follow the instructions in [How-to add a shortcut](#how-to-add-a-shortcut) -If you only want to create a shortcut for a single app qube, you can create a custom menu entry instead: +If you only want to create a shortcut for a single app qube: + +1. Open a terminal window to the template. +2. Create a custom `.desktop` file in either `~/.local/share/applications` or `/usr/local/share/applications` (you may need to first create the subdirectory). See the previous instructions about the desktop entry format. +3. Follow the instructions in [How-to add a shortcut](#how-to-add-a-shortcut) + +To add a custom menu entry instead: 1. Open a terminal window to Dom0. 2. Create a custom `.desktop` file in `~/.local/share/applications`. @@ -75,46 +110,85 @@ If you only want to create a shortcut for a single app qube, you can create a cu ~~~ +Unavailable desktop entry +^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you created a desktop entry but it doesn't show up, there are some steps to run inside the qube, to identify the problem: + +1. make sure the name is a valid name (only ascii letters, numbers, hyphens and point) +2. if this program is available, run `desktop-file-validate ` +3. run it through `gtk-launch` +4. run `/etc/qubes-rpc/qubes.GetAppmenus` and check that your desktop entry is listed in the output + What about applications in disposables? ----------------------------------- [See here](/doc/disposable-customization/). -Fixing shortcuts ----------------- +What if a removed application is still in the app menu? +-------------------------------------------------------- First, try this in dom0: ``` -$ qvm-appmenus --update --force +$ qvm-appmenus --update --force ``` -If that doesn't work, you can manually modify the files in `~/.local/share/applications/` or `/usr/local/share/applications/`. - -For example, suppose you've deleted `my-old-vm`, but there is a leftover Application Menu shortcut, and you find a related file in `~/.local/share/applications/`. -In dom0: +You can also try: ``` -$ rm -i ~/.local/share/applications/my-old-vm-* +$ qvm-appmenus --remove +``` + +If that doesn't work, you can manually modify the files in `~/.local/share/applications/` or in `~/.local/share/qubes-appmenus/`. + +For example, suppose you've deleted `my-old-vm`, but there is a leftover Application Menu shortcut, and you find a related file in `~/.local/share/applications/`, try to delete it. The hyphens in the name of the qube are replaced by an underscore and the letter, so instead of looking for `my-old-vm`, try `my_dold_dvm`. + +What if my application is shown in app menu, but doesn't run anything? +---------------------------------------------------------------------- + +First, check in the corresponding `.desktop` file in `~/.local/share/qubes-appmenus//`, inside dom0. + +The line starting with `Exec=` points out the exact command run by dom0 to start the application. It should be something like: + +``` +Exec=qvm-run -q -a --service -- qubes.StartApp+ +``` + +It's possible to run the command to check the output, by copying this line without `Exec=`, and remove `-q` (quiet option). But it could be more useful to run it in the qube, with the `qubes.StartApp` service: + +``` +$ /etc/qubes-rpc/qubes.StartApp ``` Behind the scenes ----------------- `qvm-sync-appmenus` works by invoking the *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain. -This service enumerates applications installed in that qube and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates `.desktop` files in the app qube/template directory of dom0. +This service enumerates applications installed in that qube and sends formatted info back to dom0 which creates `.desktop` files in the app qube/template directory of dom0. For Linux qubes the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default. -The list of installed applications for each app qube is stored in dom0's `~/.local/share/qubes-appmenus//apps.templates`. +The list of installed applications for each app qube is stored in dom0's `~/.local/share/qubes-appmenus//apps.templates`. Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). -Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus//apps`. +Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus//apps` and in `~/.local/share/applications/`. + +The whitelist given to `qvm-appmenu --set-whitelist` is stored as a feature called `menu-items`, where each desktop entry is separated by a space. Actual command lines for the menu shortcuts involve the `qvm-run` command which starts a process in another domain. -Examples: `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager` or `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox` +Examples: -Note that you can create a shortcut that points to a `.desktop` file in your app qube with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox`. +``` +qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox +qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager +``` + +Note that you can create a shortcut that points to a `.desktop` file in your app qube with e.g.: + +``` +qvm-run -q -a --service -- personal qubes.StartApp+firefox +``` While this works well for standard applications, creating a menu entry for Windows applications running under *wine* may need an additional step in order to establish the necessary environment in *wine*. Installing software under *wine* will create the needed `.desktop` file in the target Linux qube in the directory `~/.local/share/applications/wine/Programs/` or a subdirectory thereof, depending on the Windows menu structure seen under *wine*. If the name of this file contains spaces, it will not be found, because the `qvm-run` command is falsely seen as terminating at this space. The solution is to remove these spaces by renaming the `.desktop` file accordingly, e.g. by renaming `Microsoft Excel.desktop` to `Excel.desktop`. Refreshing the menu structure will then build working menu entries.