mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-03-15 03:06:31 -04:00
Adding more headers and ideas to troubleshoot appmenus
The "App menu shortcut troubleshooting" page seemed to be somewhat
outdated and lacking in information to facilitate troubleshooting. This
is what I did:
* trying to use consistently "qube" instead of "vm"
* trying to get consistent placeholders as uppercase between brackets
* the first part now has a title and distinguishes the GUI from the CLI,
when needed, it is referred to in the following part, instead of
repeating it.
* when a shortcut is missing, add a way to check it from the qube, to
get a better understanding of the problem ("Unavailable desktop
entry")
* the example of a desktop entry is simplified to its bare minimum
* "Fixing shortcuts" is replaced by a more accurate title. Not sure if
this part is still useful.
* mention that `my-old-vm` becomes `my_dold_dvm`
* removed an off-topic comment on Windows HVM and a missing (old?) script
* new part about how to troubleshoot a shortcut that doesn't do anything
Todo:
* update the screenshots
* is the "custom entry" still useful ?
* "Behind the scenes" could be developed
This commit is contained in:
parulin
parent
647e60feee
commit
c7465b0d6e
@ -16,19 +16,56 @@ Clicking on such shortcut runs the assigned application in its app qube.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 `<QUBE_NAME>` by the qube name:
|
||||
|
||||
```console
|
||||
$ qvm-sync-appmenus <QUBE_NAME>
|
||||
```
|
||||
|
||||
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 <APPVM_NAME>
|
||||
$ qvm-sync-appmenus <TEMPLATE_NAME>
|
||||
```
|
||||
|
||||
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 <FILE_PATH> <QUBE_NAME>
|
||||
```
|
||||
|
||||
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 <templateName>`.
|
||||
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
|
||||
</Menu>
|
||||
~~~
|
||||
|
||||
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 <DESKTOP_FILE_PATH>`
|
||||
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 <vm_name>
|
||||
$ qvm-appmenus --update --force <QUBE_NAME>
|
||||
```
|
||||
|
||||
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 <QUBE_NAME>
|
||||
```
|
||||
|
||||
If that doesn't work, you can manually modify the files in `~/.local/share/applications/` or in `~/.local/share/qubes-appmenus/<QUBE_NAME>`.
|
||||
|
||||
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/<QUBE_NAME>/`, 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 -- <QUBE_NAME> qubes.StartApp+<APPLICATION_NAME>
|
||||
```
|
||||
|
||||
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 <APPLICATION_NAME>
|
||||
```
|
||||
|
||||
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/<vmname>/apps.templates`.
|
||||
The list of installed applications for each app qube is stored in dom0's `~/.local/share/qubes-appmenus/<QUBE_NAME>/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/<vmname>/apps`.
|
||||
Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus/<QUBE_NAME>/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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user