mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-07-29 01:28:59 -04:00
Merge branch 'QubesOS:main' into main
This commit is contained in:
m
GitHub
commit
7e2b1b1858
2 changed files with 107 additions and 41 deletions
|
|
@ -91,25 +91,27 @@ This section will demonstrate a simple installation using mostly default setting
|
|||
|
||||
### Getting to the boot screen
|
||||
|
||||
"Booting" is the process of starting your computer. When a computer boots up, it first runs low-level software before the main operating system. Depending on the computer, this low-level software is may be called the ["BIOS"](https://en.wikipedia.org/wiki/BIOS) or ["UEFI"](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface).
|
||||
"Booting" is the process of starting your computer. When a computer boots up, it first runs low-level software before the main operating system. Depending on the computer, this low-level software may be called the ["BIOS"](https://en.wikipedia.org/wiki/BIOS) or ["UEFI"](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface).
|
||||
|
||||
Since you're installing Qubes OS, you'll need to access your computer's BIOS or UEFI menu so that you can tell it to boot from the USB drive to which you just copied the Qubes installer ISO.
|
||||
|
||||
To begin, power off your computer and plug the USB drive into a USB port, but don't press the power button yet. Right after you press the power button, you'll have to immediately press a specific key to enter the BIOS or UEFI menu. The key to press varies from brand to brand. `Esc`, `Del`, and `F10` are common ones. If you're not sure, you can search the web for `<COMPUTER_MODEL> BIOS key` or `<COMPUTER_MODEL> UEFI key` (replacing `<COMPUTER_MODEL>` with your specific computer model) or look it up in your computer's manual.
|
||||
|
||||
Once you know the key to press, press your computer's power button, then repeatedly press that key until you've entered your computer's BIOS or UEFI menu. To give you and idea of what you should be looking for, we've provided a couple of example photos below.
|
||||
Once you know the key to press, press your computer's power button, then repeatedly press that key until you've entered your computer's BIOS or UEFI menu. To give you an idea of what you should be looking for, we've provided a couple of example photos below.
|
||||
|
||||
Here's an example of what the BIOS menu looks like on a ThinkPad T430:
|
||||
|
||||
[](/attachment/doc/Thinkpad-t430-bios-main.jpg)
|
||||
|
||||
And here's an example of what a UEFI menu looks like:
|
||||
And here's an example of what a modern UEFI menu looks like:
|
||||
|
||||
[](/attachment/doc/uefi.jpeg)
|
||||
|
||||
Once you access your computer's BIOS or UEFI menu, you'll want to go to the "boot menu," which is where you tell your computer which devices to boot from. The goal is to tell the computer to boot from your USB drive so that you can run the Qubes installer. If your boot menu lets you select which device to boot from first, simply select your USB drive. (If you have multiple entries that all look similar to your USB drive, and you're not sure which one is correct, one option is just to try each one until it works.) If, on the other hand, your boot menu presents you with a list of boot devices in order, then you'll want to move your USB drive to the top so that the Qubes installer runs before anything else.
|
||||
Once you access your computer's BIOS or UEFI menu, you'll want to go to the "boot menu", which is where you tell your computer which devices to boot from. The goal is to tell the computer to boot from your USB drive so that you can run the Qubes installer. If your boot menu lets you select which device to boot from first, simply select your USB drive. (If you have multiple entries that all look similar to your USB drive, and you're not sure which one is correct, one option is just to try each one until it works.) If, on the other hand, your boot menu presents you with a list of boot devices in order, then you'll want to move your USB drive to the top so that the Qubes installer runs before anything else.
|
||||
|
||||
Once you're done on the boot menu, save your changes. How you do this depends on your BIOS or UEFI, but the instructions should be displayed right there on the screen or in a nearby tab. (If you're not sure whether you've saved your changes correctly, you can always reboot your computer and go back into the boot menu to check whether it still reflects your changes.) Once your BIOS or UEFI is configured the way you want it, reboot your computer. This time, don't press any special keys. Instead, let the BIOS or UEFI load and let your computer boot from your USB drive. If you're successful in this step, after a few seconds you'll be presented with the Qubes installer screen:
|
||||
Then, if you are on a computer using UEFI, you'll have to disable [Secure Boot](https://en.m.wikipedia.org/wiki/UEFI#SECURE-BOOT) to allow Qubes OS to boot.
|
||||
|
||||
Once you're done with the settings, save your changes. How you do this depends on your BIOS or UEFI, but the instructions should be displayed right there on the screen or in a nearby tab. (If you're not sure whether you've saved your changes correctly, you can always reboot your computer and go back into the boot menu to check whether it still reflects your changes.) Once your BIOS or UEFI is configured the way you want it, reboot your computer. This time, don't press any special keys. Instead, let the BIOS or UEFI load and let your computer boot from your USB drive. If you're successful in this step, after a few seconds you'll be presented with the Qubes installer screen:
|
||||
|
||||
[](/attachment/doc/boot-screen-4.2.png)
|
||||
|
||||
|
|
|
|||
|
|
@ -14,20 +14,52 @@ title: App menu shortcut troubleshooting
|
|||
For ease of use Qubes aggregates shortcuts to applications that are installed in app qubes and shows them in one application menu (aka "app menu" or "start menu") in dom0.
|
||||
Clicking on such shortcut runs the assigned application in its app qube.
|
||||
|
||||
|
||||
[](/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.
|
||||
|
||||
|
||||
[](/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.
|
||||
|
||||
What if my application has not been automatically included in the list of available apps?
|
||||
-----------------------------------------------------------------------------------------
|
||||
### With the command-line 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 application, 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 +74,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 +105,80 @@ If you only want to create a shortcut for a single app qube, you can create a cu
|
|||
</Menu>
|
||||
~~~
|
||||
|
||||
What about applications in disposables?
|
||||
-----------------------------------
|
||||
### Unavailable desktop entry
|
||||
|
||||
[See here](/doc/disposable-customization/).
|
||||
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:
|
||||
|
||||
Fixing shortcuts
|
||||
----------------
|
||||
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 [Adding programs to the app menu in Disposable customization](/doc/disposable-customization/#adding-programs-to-the-app-menu).
|
||||
|
||||
## 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>
|
||||
```
|
||||
|
||||
Behind the scenes
|
||||
-----------------
|
||||
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…
Add table
Add a link
Reference in a new issue