Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-10-12 18:40:57 -04:00
Code Issues Projects Releases Packages Wiki Activity

Merge remote-tracking branch 'parulin/clean-code-block-console' into rst

Browse source
This commit is contained in:
qubedmaiska 2025-08-15 13:57:46 -04:00
commit d4e09e079f
No known key found for this signature in database
GPG key ID: 204BCE0FD52C0501
111 changed files with 1270 additions and 1265 deletions
Download patch file Download diff file Expand all files Collapse all files

16
user/how-to-guides/backup-emergency-restore-v2.rst
View file

@ -11,7 +11,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Untar the main backup file.
.. code:: bash
.. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456
backup-header
@ -33,7 +33,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
.. code:: bash
.. code:: console
[user@restore ~]$ read -r backup_pass
@ -41,7 +41,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
3. Verify the integrity of the ``private.img`` file which houses your data.
.. code:: bash
.. code:: console
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" private.img.000
@ -59,7 +59,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
4. Decrypt the ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in private.img.000 -out private.img.dec.000
@ -71,7 +71,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
**Note:** For multi-part files, a loop can be used:
.. code:: bash
.. code:: console
find -name 'private.img.*' | sort -V | while read f; do
openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in $f -out
@ -84,7 +84,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
5. Decompress the decrypted ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ zforce private.img.dec.*
[user@restore vm1]$ gunzip private.img.dec.000.gz
@ -99,7 +99,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
6. Untar the decrypted and decompressed ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ tar -M -xvf private.img.dec.000
vm1/private.img
@ -126,7 +126,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
7. Mount the private.img file and access your data.
.. code:: bash
.. code:: console
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/

20
user/how-to-guides/backup-emergency-restore-v3.rst
View file

@ -11,7 +11,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Untar the main backup file.
.. code:: bash
.. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
backup-header
@ -33,7 +33,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
.. code:: bash
.. code:: console
[user@restore ~]$ read -r backup_pass
@ -41,7 +41,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
3. Verify the integrity of the ``backup-header`` file, which contains basic information about your backup.
.. code:: bash
.. code:: console
[user@restore ~]$ openssl dgst -sha512 -hmac "$backup_pass" backup-header
HMAC-SHA512(backup-header)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
@ -58,7 +58,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
4. Read the ``backup-header``. You’ll need some of this information later. The file will look similar to this:
.. code:: bash
.. code:: console
[user@restore ~]$ cat backup-header
version=3
@ -73,7 +73,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
5. Verify the integrity of the ``private.img`` file which houses your data.
.. code:: bash
.. code:: console
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" private.img.000
@ -91,7 +91,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
6. Decrypt the ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -out private.img.dec
@ -100,7 +100,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
7. Decompress the decrypted ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ zforce private.img.dec
private.img.dec -- replaced with private.img.dec.gz
@ -109,7 +109,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
**Note:** If your backup was compressed with a program other than ``gzip``, you must substitute the correct compression program. This information is contained in the ``backup-header`` file (see step 4). For example, if you used ``bzip2``, then you should do this:
.. code:: bash
.. code:: console
[user@restore vm1]$ mv private.img.dec private.img.dec.bz2
[user@restore vm1]$ bunzip2 private.img.dec.bz2
@ -118,7 +118,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
8. Untar the decrypted and decompressed ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ tar -xvf private.img.dec
vm1/private.img
@ -127,7 +127,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
9. Mount the private.img file and access your data.
.. code:: bash
.. code:: console
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/

32
user/how-to-guides/backup-emergency-restore-v4.rst
View file

@ -19,7 +19,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
1. If you’re not on Qubes 4.X, :ref:`import and authenticate the Release 4 Signing Key <project-security/verifying-signatures:how to import and authenticate release signing keys>`.
.. code:: bash
.. code:: console
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
@ -27,14 +27,14 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
2. Download the ``scrypt`` RPM.
.. code:: bash
.. code:: console
[user@restore ~]$ dnf download scrypt
Or, if that doesn’t work:
.. code:: bash
.. code:: console
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
@ -42,7 +42,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
3. Verify the signature on the ``scrypt`` RPM.
.. code:: bash
.. code:: console
[user@restore ~]$ rpm -K scrypt-*.rpm
scrypt-*.rpm: digests signatures OK
@ -52,7 +52,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
4. Install ``rpmdevtools``.
.. code:: bash
.. code:: console
[user@restore ~]$ sudo dnf install rpmdevtools
@ -60,7 +60,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
5. Extract the ``scrypt`` binary from the RPM and make it conveniently available.
.. code:: bash
.. code:: console
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
@ -77,7 +77,7 @@ Emergency recovery instructions
1. Untar the backup metadata from the main backup file.
.. code:: bash
.. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
backup-header backup-header.hmac qubes.xml.000.enc
@ -89,7 +89,7 @@ Emergency recovery instructions
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
.. code:: bash
.. code:: console
[user@restore ~]$ read -r backup_pass
@ -98,7 +98,7 @@ Emergency recovery instructions
3. Verify the integrity of ``backup-header`` using ``backup-header.hmac`` (an encrypted *and integrity protected* version of ``backup-header``).
.. code:: bash
.. code:: console
[user@restore ~]$ set +H
[user@restore ~]$ echo "backup-header!$backup_pass" |\
@ -117,7 +117,7 @@ Emergency recovery instructions
4. Read ``backup-header``.
.. code:: bash
.. code:: console
[user@restore ~]$ cat backup-header
version=4
@ -131,7 +131,7 @@ Emergency recovery instructions
5. Set ``backup_id`` to the value in the last line of ``backup-header``. (Note that there is a hyphen in ``backup-id`` in the file, whereas there is an underscore in ``backup_id`` in the variable you’re setting.)
.. code:: bash
.. code:: console
[user@restore ~]$ backup_id=20230405T123455-1234
@ -139,7 +139,7 @@ Emergency recovery instructions
6. Verify and decrypt, decompress, and extract the ``qubes.xml`` file.
.. code:: bash
.. code:: console
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
@ -155,7 +155,7 @@ Emergency recovery instructions
7. Search inside of the ``qubes.xml`` file for the ``backup-path`` of the qube whose data you wish to restore. If you install the ``xmlstarlet`` package, the following command will convert ``qubes.xml`` to a friendlier listing for this purpose:
.. code:: bash
.. code:: console
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
@ -182,7 +182,7 @@ Emergency recovery instructions
The example output above shows that the backup file includes a qube named ``personal`` and a qube named ``vault``, with ``backup-path`` values of ``vm123/`` and ``vm321/`` respectively. (Every other listed qube was not selected to be included in the backup file.) Use the corresponding value to untar the necessary data files of the qube:
.. code:: bash
.. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
@ -190,7 +190,7 @@ Emergency recovery instructions
8. Verify and decrypt the backed up data, decompress it, and extract it.
.. code:: bash
.. code:: console
[user@restore ~]$ find vm123/ -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
@ -204,7 +204,7 @@ Emergency recovery instructions
9. Mount ``private.img`` and access your data.
.. code:: bash
.. code:: console
[user@restore ~]$ sudo mkdir /mnt/img
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/

2
user/how-to-guides/how-to-back-up-restore-and-migrate.rst
View file

@ -15,7 +15,7 @@ Backing up changes to dom0
When backing up dom0 using the Qubes backup tool (explained below), only the home directory is backed up. Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup. Here is an example of how to back up Qubes config files and RPC policies:
.. code:: bash
.. code:: console
$ mkdir -p ~/backup/etc/qubes/
$ cp -a /etc/qubes/* ~/backup/etc/qubes/

6
user/how-to-guides/how-to-copy-and-move-files.rst
View file

@ -15,7 +15,7 @@ For simplicity, these instructions will refer to copying/moving a single file, b
3. If the target qube is not already running, it will be started automatically, and the file will be copied there. It will show up in this directory (which will automatically be created if it does not already exist):
.. code:: bash
.. code:: text
/home/user/QubesIncoming/<source_qube>/<filename>
@ -28,13 +28,13 @@ For simplicity, these instructions will refer to copying/moving a single file, b
The same operations are also available via these command-line tools:
.. code:: bash
.. code:: console
qvm-copy [--without-progress] file [file]+
.. code:: bash
.. code:: console
qvm-move [--without-progress] file [file]+

8
user/how-to-guides/how-to-copy-and-paste-text.rst
View file

@ -43,7 +43,7 @@ Clipboard automatic policy enforcement
The Qubes clipboard :doc:`RPC policy </user/advanced-topics/rpc-policy>` is configurable in:
.. code:: bash
.. code:: text
/etc/qubes-rpc/policy/qubes.ClipboardPaste
@ -51,7 +51,7 @@ The Qubes clipboard :doc:`RPC policy </user/advanced-topics/rpc-policy>` is conf
You may wish to configure this policy in order to prevent user error. For example, if you are certain that you never wish to paste *into* your “vault” app qube (and it is highly recommended that you do not), then you should edit the policy as follows:
.. code:: bash
.. code:: text
@anyvm vault deny
@anyvm @anyvm ask
@ -66,7 +66,7 @@ By default data pasted into a qube will remain there until user copies something
To enable automatic wiping of the clipboard after a minute use ``qvm-service``:
.. code:: bash
.. code:: console
qvm-service --enable VMNAME gui-agent-clipboard-wipe
@ -78,7 +78,7 @@ Shortcut configuration
The copy/paste shortcuts are configurable via ``qvm-features``, e.g.
.. code:: bash
.. code:: console
qvm-features dom0 gui-default-secure-copy-sequence 'Mod4-c'
qvm-features dom0 gui-default-secure-paste-sequence 'Mod4-v'

6
user/how-to-guides/how-to-copy-from-dom0.rst
View file

@ -15,7 +15,7 @@ Copying files from dom0
To copy a file from dom0 to a VM, simply use ``qvm-copy-to-vm``:
.. code:: bash
.. code:: console
qvm-copy-to-vm <target_vm> <file>
@ -71,7 +71,7 @@ There should normally be few reasons for the user to want to copy anything from
If you are determined to copy some files to dom0 anyway, you can use the following method. (If you want to copy text, first save it into a text file.) Run this command in a dom0 terminal:
.. code:: bash
.. code:: console
qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
@ -79,7 +79,7 @@ If you are determined to copy some files to dom0 anyway, you can use the followi
Note that you can use the same method to copy files from dom0 to domUs (if, for some reason, you don’t want to use ``qvm-copy-to-vm``):
.. code:: bash
.. code:: console
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'

4
user/how-to-guides/how-to-enter-fullscreen-mode.rst
View file

@ -31,7 +31,7 @@ You can always put a window into fullscreen mode in Xfce4 using the trusted wind
As an alternative to the Xfce4 method, you can enable fullscreen mode for select VMs by creating the following entry in the ``/etc/qubes/guid.conf`` file in dom0:
.. code:: bash
.. code:: text
VM: {
personal: {
@ -47,7 +47,7 @@ The string ‘personal’ above is an example only and should be replaced by the
One can also enable this functionality for all the VMs globally in the same file, by modifying the ‘global’ section:
.. code:: bash
.. code:: text
global: {
# default values

38
user/how-to-guides/how-to-install-software.rst
View file

@ -36,7 +36,7 @@ Installing software from default repositories
.. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png
:alt: The Applications tab in Qube Settings
Installing software from other sources
--------------------------------------
@ -52,7 +52,7 @@ If you are still using the distribution package manager, updates will likely sti
If you are using another installation method fetching remote resources, you might still be able to use the updates proxy by making the tools aware of the proxy. For many tools, it is enough to export the following environment variables in your shell session before proceeding:
.. code:: bash
.. code:: console
$ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \
HTTPS_PROXY=$HTTP_PROXY https_proxy=$HTTPS_PROXY \
@ -91,7 +91,7 @@ This method assumes that you are trying to follow instructions to install some p
.. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png
:alt: The Applications tab in Qube Settings
Troubleshooting
---------------
@ -155,7 +155,7 @@ There are three Qubes VM testing repositories (where ``*`` denotes the Release):
To temporarily enable any of these repos, use the ``--enablerepo=<repo-name>`` option. Example commands:
.. code:: bash
.. code:: console
sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing
sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing
@ -193,7 +193,7 @@ RPMFusion for Fedora templates
If you would like to enable the `RPM Fusion <https://rpmfusion.org/>`__ repositories, open a Terminal of the template and type the following commands, depending on which RPM Fusion repositories you wish to enable (see `RPM Fusion <https://rpmfusion.org/>`__ for details):
.. code:: bash
.. code:: console
sudo dnf config-manager setopt rpmfusion-free.enabled=1
sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1
@ -229,7 +229,7 @@ Root revert
2. In a dom0 terminal:
.. code:: bash
.. code:: console
qvm-volume revert <template>:root
@ -281,12 +281,12 @@ The updates proxy uses RPC/qrexec. The proxy is configured in qrexec policy in d
Example policy file in R4.1 (with Whonix installed, but not set as default UpdateVM for all templates):
.. code:: bash
.. code:: console
# any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone
@tag:whonix-updatevm @default allow,target=sys-whonix
@tag:whonix-updatevm @anyvm deny
# other templates use sys-net
@type:TemplateVM @default allow,target=sys-net
@anyvm @anyvm deny
@ -300,7 +300,7 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
1. In the **template** you must install ``snapd`` and ``qubes-snapd-helper``. Open a terminal in the template and run:
.. code:: bash
.. code:: console
[user@fedora-36-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
@ -313,15 +313,15 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
qubes-snapd-helper noarch 1.0.4-1.fc36 qubes-vm-r4.1-current 10 k
Installing dependencies:
[...]
Transaction Summary
========================================================================================================
Install 19 Packages
Total download size: 27 M
Installed size: 88 M
Is this ok [y/N]: y
Downloading Packages:
[..]
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
@ -329,7 +329,7 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
[...]
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
Notifying dom0 about installed applications
Installed:
snapd-2.56.2-4.fc36.x86_64 qubes-snapd-helper-1.0.4-1.fc36.noarch
[...]
@ -337,7 +337,7 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
You may see the following message:
.. code:: bash
.. code:: console
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
/usr/sbin/semodule: Failed!
@ -346,14 +346,14 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
This is expected and you can safely continue.
Shutdown the template:
.. code:: bash
.. code:: console
[user@fedora-36-snap-demo ~]$ sudo shutdown -h now
2. Now open the **app qube** in which you would like to install the Snap application and run a terminal:
.. code:: bash
.. code:: console
[user@snap-demo-app qube ~]$ snap install <package>
@ -377,7 +377,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
2. List the names of the available desktop shortcuts by running the command ``ls /usr/share/applications`` and find the exact name of the shortcut to the app you want to autostart:
.. code:: bash
.. code:: console
[user@example-app qube ~]$ ls /usr/share/applications/
bluetooth-sendto.desktop
@ -390,7 +390,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
3. Create the autostart directory:
.. code:: bash
.. code:: console
[user@example-app qube ~]$ mkdir -p ~/.config/autostart
@ -398,7 +398,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
4. Make a link to the desktop app file you’d like to start in the autostart directory. For example, the command below will link the Thunderbird app into the autostart directory:
.. code:: bash
.. code:: console
[user@example-app qube ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop

18
user/how-to-guides/how-to-organize-your-qubes.rst
View file

@ -15,7 +15,7 @@ Alice, the software developer
Alice is a freelance dev who works on several projects for different clients simultaneously. The projects have varying requirements and often different build environments. She has a separate set of qubes for each project. She keeps them organized by coming up with a naming scheme, such as:
.. code:: bash
.. code:: text
clientA-code
clientA-build
@ -89,7 +89,7 @@ Carol, the investor
Carol works hard and lives below her means so that she can save money and invest it for her future. She hopes to become financially independent and maybe even retire early someday, and she’s decided that her best bet for achieving this is by investing for the long term and allow compounding to do its work. However, after doing some research into her country’s consumer financial protection laws, she learned that there’s no legal guarantee that customers will be made whole in the event of theft or fraud. The various insurance and protection organizations only guarantee recovery in the case of a financial institution *failing*, which is quite different from an individual customer being hacked. Moreover, even though many financial institutions have their own cybercrime policies, rarely, if ever, do they explicitly guarantee reimbursement in the event that a *customer* gets hacked (rather than the institution itself).
.. warning::
Carol looked into how thieves might actually try to steal her hard-earned wealth and was surprised to learn that they have all sorts of ploys that she had never even considered. For example, she had assumed that any theft would, at the bare minimum, have to involve transferring money out of her account. That seems like a safe assumption. But then she read about “pump and dump” attacks, where thieves buy up some penny stock, hack into innocent people’s brokerage accounts, then use the victims’ funds to buy that same penny stock, “pumping” up its price so that the thieves can “dump” their shares on the market, leaving the victims with worthless shares. No money is ever transferred into or out of the victims’ account; it’s just used to buy and sell securities. So, all the safeguards preventing new bank accounts from being added or requiring extra approval for outbound transfers do nothing to protect victims’ funds in cases like these. And this is just one example! Carol realized that she couldn’t assume that existing safeguards against specific, known attacks were enough. She had to think about security at a more fundamental level and design it into her digital life from the ground up.
After learning about all this, Carol decided that it was ultimately up to her to take care of her own cybersecurity. She couldn’t rely on anyone else to do it for her. Sure, most people just use regular consumer tech and will probably end up fine, but, she reminded herself, most people also don’t have as much to lose. It’s not a risk that she was willing to take with her future, especially knowing that there’s probably no government bailout waiting for her and that all the brokerage firms’ vaguely reassuring marketing language about cybersecurity isn’t legally binding. So, Carol started reading more about computer security and eventually stumbled upon Qubes OS after searching the web for “most secure operating system.” She read about how it’s designed and why. Although she didn’t immediately understand all of the technical details, the fundamental principle of :doc:`security-by-compartmentalization </developer/system/architecture>` made intuitive sense to her, and the more she learned about the technical aspects, the more she realized that this is what she’d been looking for. Today, her setup looks like this:
@ -119,7 +119,7 @@ Bonus: Carol explores new financial technology
The vast majority of Carol’s assets are in broad-based, low-cost, passively-managed indexed funds. Lately, however, she’s started getting interested in cryptocurrency. She’s still committed to staying the course with her tried-and-true investments, and she’s always been skeptical of new asset classes, especially those that don’t generate cash flows or that often seem to be associated with scams or wild speculation. However, she finds the ability to self-custody a portion of her assets appealing from a long-term risk management perspective, particularly as a hedge against certain types of political risk.
.. DANGER::
Some of Carol’s friends warned her that cryptocurrency is extremely volatile and that hacking and theft are common occurrences. Carol agreed and reassured them that she’s educated herself about the risks and will make sure she never invests more than she can afford to lose.
Carol has added the following to her Qubes setup:
@ -169,7 +169,7 @@ Conclusion
The characters we’ve met today may be fictional, but they represent the needs of real users like you. You may find that your own needs overlap with more than one of them, in which case you may find it useful to model certain subsets of your overall Qubes system on different examples. You probably also noticed that there are commonalities among them. Most people need to use email, for example, so most people will need at least one email qube and a suitable template to base it on. But not everyone will need :doc:`Split GPG </user/security-in-qubes/split-gpg>`, and not everyone will want to use the same email client. On the other hand, almost everyone will need a password manager, and it pretty much always makes sense to keep it in an offline, network-isolated vault.
.. note::
As you gain experience with Qubes, you may find yourself disagreeing with some of the decisions our fictional friends made. That’s okay! There are many different ways to organize a Qubes system, and the most important criterion is that it serves the needs of its owner. Since everyone’s needs are different, it’s perfectly normal to find yourself doing things a bit differently. Nonetheless, there are some general principles that almost all users find helpful, especially when they’re first starting out.
As you’re designing your own Qubes system, keep in mind some of the following lessons from our case studies:
@ -189,16 +189,16 @@ As you’re designing your own Qubes system, keep in mind some of the following
.. |Alice’s system: diagram 1| image:: /attachment/doc/howto_use_qubes_alice_1.png
.. |Alice’s system: diagram 2| image:: /attachment/doc/howto_use_qubes_alice_2.png
.. |A diagram of Bob’s system| image:: /attachment/doc/howto_use_qubes_bob.png
.. |A diagram of Carol’s system| image:: /attachment/doc/howto_use_qubes_carol.png
.. |Simple VM setup| image:: /attachment/doc/Simple_Setup.png

12
user/how-to-guides/how-to-reinstall-a-template.rst
View file

@ -11,7 +11,7 @@ Automatic Method
First, copy any files that you wish to keep from the template’s ``/home`` and ``/rw`` folders to a safe storage location. Then, in a dom0 terminal, run:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
@ -23,7 +23,7 @@ Note that Qubes may initially refuse to perform the reinstall if the exact revis
**Reminder:** If you’re trying to reinstall a template that is not in an enabled repo, you must enable that repo. For example:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
@ -51,14 +51,14 @@ In what follows, the term “target template” refers to whichever template you
3. Uninstall the target template from dom0:
.. code:: bash
.. code:: console
$ sudo dnf remove <template-package-name>
For example, to uninstall the ``whonix-gw`` template:
.. code:: bash
.. code:: console
$ sudo dnf remove qubes-template-whonix-gw
@ -66,14 +66,14 @@ In what follows, the term “target template” refers to whichever template you
4. Reinstall the target template in dom0:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --enablerepo=<optional-additional-repo> \
<template-package-name>
For example, to install the ``whonix-gw`` template:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
qubes-template-whonix-gw

16
user/how-to-guides/how-to-update.rst
View file

@ -36,7 +36,7 @@ By default, the **Qubes Update** tool will appear as an icon in the Notification
However, you can also start the tool manually by selecting it in the Applications Menu under “Qubes Tools.” Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting all desired items from the list and clicking “Update”.
.. note::
For information about how templates download updates, please see :ref:`Why don’t templates have normal network access? <user/how-to-guides/how-to-install-software:why don't templates have normal network access?>` and the :ref:`Updates proxy <user/how-to-guides/how-to-install-software:updates proxy>` .
By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. You can check the date of the last update check in the “last checked” column. If updates are available for any qube, you will receive a notification as described above, and in the “Updates available” column you will see “YES” for that qube(s). If the update check did not find any new updates, “NO” will appear in the column. Respectively, for qubes that are no longer supported, “OBSOLETE” will be displayed. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. By default, after a week, if updates for a given qube have not been checked, the value in the “Updates available” column will be set to “MAYBE”.
@ -82,7 +82,7 @@ Command-line interface
.. DANGER::
**Warning:** Updating with direct commands such as dnf update and apt update is not recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the **Qubes Update** tool or its command-line equivalents, as described below. (By contrast, :doc:`installing </user/how-to-guides/how-to-install-software>` packages using direct package manager commands is fine.)
Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
@ -159,7 +159,7 @@ First, ensure that your UpdateVM contains the ``fwupd-qubes-vm`` package. This p
In a dom0 terminal, install the ``fwupd-qubes-dom0`` package:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update fwupd-qubes-dom0
@ -167,7 +167,7 @@ In a dom0 terminal, install the ``fwupd-qubes-dom0`` package:
Once the package is installed:
.. code:: bash
.. code:: console
$ sudo qubes-fwupdmgr get-devices
@ -175,7 +175,7 @@ Once the package is installed:
Examine the terminal output for warnings or errors. You may see the following warning:
.. code:: bash
.. code:: output
WARNING: UEFI capsule updates not available or enabled
@ -185,7 +185,7 @@ If so, `adjust your BIOS settings <https://github.com/fwupd/fwupd/wiki/PluginFla
Once resolved, in a dom0 terminal:
.. code:: bash
.. code:: console
$ sudo qubes-fwupdmgr get-devices
$ sudo qubes-fwupdmgr refresh
@ -212,7 +212,7 @@ Computers without fwupd support
For computers that do not have firmware update support via ``fwupd``, follow the firmware update instructions on the manufacturer’s website. Verify the authenticity of any firmware updates you apply.
.. |Qube Updates Available| image:: /attachment/doc/r4.2-qube-updates-available.png
.. |Qubes Update| image:: /attachment/doc/r4.2-software-update.png

34
user/how-to-guides/how-to-use-block-storage-devices.rst
View file

@ -27,7 +27,7 @@ Block Devices in VMs
If not specified otherwise, block devices will show up as ``/dev/xvdi*`` in a linux VM, where ``*`` may be the partition-number. If a block device isn’t automatically mounted after attaching, open a terminal in the VM and execute:
.. code:: bash
.. code:: console
cd ~
mkdir mnt
@ -55,14 +55,14 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
1. In a dom0 console (running as a normal user), list all available block devices:
.. code:: bash
.. code:: console
qvm-block
This will list all available block devices in your system across all VMs. The name of the qube hosting the block device is displayed before the colon in the device ID. The string after the colon is the ID of the device used within the qube, like so:
.. code:: bash
.. code:: console
sourceVM:sdb Cruzer () 4GiB
sourceVM:sdb1 Disk () 2GiB
@ -71,7 +71,7 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
2. Assuming your block device is attached to ``sys-usb`` and its device node is ``sdb``, we attach the device to a qube with the name ``work`` like so:
.. code:: bash
.. code:: console
qvm-block attach work sys-usb:sdb
@ -85,7 +85,7 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
3. The block device is now attached to the qube. If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. If you’ve attached a single partition (e.g. ``sdb2`` instead of ``sdb`` in our example), you may need to manually mount before it becomes visible:
.. code:: bash
.. code:: console
cd ~
mkdir mnt
@ -99,7 +99,7 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
.. code:: bash
.. code:: console
sudo umount mnt
@ -107,7 +107,7 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
5. In a dom0 console, detach the device
.. code:: bash
.. code:: console
qvm-block detach work sys-usb:sdb
@ -125,7 +125,7 @@ If you fail to detach the device before it’s destroyed in the sourceVM (e.g. 
To recover from this error state, in dom0 run
.. code:: bash
.. code:: console
virsh detach-disk targetVM xvdi
@ -145,7 +145,7 @@ Currently (until issue `1082 <https://github.com/QubesOS/qubes-issues/issues/108
2. Attach the device manually to the same VM using the ``xl block-attach`` command. It is important to use the same “frontend” device name (by default, ``xvdi``). You can get it from the ``qvm-block`` listing:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
@ -175,7 +175,7 @@ To attach a file as block device to another qube, first turn it into a loopback
1. In the linux sourceVM run
.. code:: bash
.. code:: console
sudo losetup -f --show /path/to/file
@ -190,7 +190,7 @@ To attach a file as block device to another qube, first turn it into a loopback
.. code:: bash
.. code:: console
~]$ qvm-block
BACKEND:DEVID DESCRIPTION USED BY
@ -199,7 +199,7 @@ To attach a file as block device to another qube, first turn it into a loopback
3. Attach the ``loop0``-device using qvm-block as usual:
.. code:: bash
.. code:: console
qvm-block a targetVM sourceVM:loop0
@ -207,7 +207,7 @@ To attach a file as block device to another qube, first turn it into a loopback
4. After detaching, destroy the loop-device inside the sourceVM as follows:
.. code:: bash
.. code:: console
sudo losetup -d /dev/loop0
@ -229,7 +229,7 @@ This option allows you to specify the name of the device node made available in
usage example:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz
@ -247,7 +247,7 @@ If the device is a read-only device, this option is forced true.
usage example:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 -o read-only=true
@ -255,7 +255,7 @@ usage example:
There exists a shortcut to set read-only ``true``, ``--ro``:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 --ro
@ -271,7 +271,7 @@ Usually, a block device is attached as disk. In case you need to attach a block
usage example:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 -o devtype=cdrom

20
user/how-to-guides/how-to-use-disposables.rst
View file

@ -63,7 +63,7 @@ On a fresh installation of Qubes, the default disposable template is called ``fe
You can set any app qube to have the ability to act as a disposable template with:
.. code:: bash
.. code:: console
qvm-prefs <APP_QUBE> template_for_dispvms True
@ -73,7 +73,7 @@ The default system wide disposable template can be changed with ``qubes-prefs de
You can change this behavior for individual qubes: in the Application Menu, open Qube Settings for the qube in question and go to the “Advanced” tab. Here you can edit the “Default disposable” setting to specify which disposable template will be used to launch disposables from that qube. This can also be changed from the command line with:
.. code:: bash
.. code:: console
qvm-prefs <QUBE> default_dispvm <DISPOSABLE_TEMPLATE>
@ -89,7 +89,7 @@ A disposable launched from the app menu inherits the net qube and firewall setti
**Important Notes:** Some disposable templates will automatically create a menu item to launch a disposable. If you do not see an entry and want to add one, please use the command:
.. code:: bash
.. code:: console
qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
@ -97,7 +97,7 @@ A disposable launched from the app menu inherits the net qube and firewall setti
To launch a disposable template from the command line, execute the following command in dom0:
.. code:: bash
.. code:: console
qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+<APPLICATION>
@ -136,7 +136,7 @@ Opening a file in a disposable via command line (from app qube)
Use the ``qvm-open-in-dvm`` command from a terminal in your app qube:
.. code:: bash
.. code:: console
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
@ -166,7 +166,7 @@ Starting an arbitrary program in a disposable from an app qube
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details `here <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). Starting an arbitrary program can be done from an app qube by running
.. code:: bash
.. code:: console
[user@vault ~]$ qvm-run '@dispvm' xterm
@ -180,7 +180,7 @@ Starting an arbitrary application in a disposable via command line from dom0
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details `here <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). It is possible to start an arbitrary application in a disposable directly from dom0 by running:
.. code:: bash
.. code:: console
$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
@ -194,7 +194,7 @@ Opening a link in a disposable based on a non-default disposable template from a
Suppose that the default disposable template for your ``email`` qube has no networking (e.g., so that untrusted attachments can’t phone home). However, sometimes you want to open email links in disposables. Obviously, you can’t use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template. You can do that with this command from the ``email`` qube (as long as your RPC policies allow it):
.. code:: bash
.. code:: console
$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> https://www.qubes-os.org
@ -208,7 +208,7 @@ Example of RPC policies to allow this behavior
In dom0, add the following line at the beginning of the file ``/etc/qubes-rpc/policy/qubes.OpenURL``
.. code:: bash
.. code:: text
@anyvm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> allow
@ -235,4 +235,4 @@ Customizing disposables
You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found :doc:`here </user/advanced-topics/disposable-customization>`.
.. |disposablevm-example.png| image:: /attachment/doc/disposablevm-example.png

12
user/how-to-guides/how-to-use-pci-devices.rst
View file

@ -53,7 +53,7 @@ The ``qvm-pci`` tool allows PCI attachment and detachment. It’s a shortcut for
To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
.. code:: bash
.. code:: console
qvm-pci
@ -61,7 +61,7 @@ To figure out what device to attach, first list the available PCI devices by run
This will show you the ``backend:BDF`` (Bus_Device.Function) address of each PCI device. It will look something like ``dom0:00_1a.0``. Once you’ve found the address of the device you want to attach, then attach it like this:
.. code:: bash
.. code:: console
qvm-pci attach targetVM sourceVM:[BDF] --persistent
@ -71,7 +71,7 @@ Since PCI devices have to be attached on bootup, attaching has to happen with th
For example, if ``00_1a.0`` is the BDF of the device you want to attach to the “work” domain, you would do this:
.. code:: bash
.. code:: console
qvm-pci attach work dom0:00_1a.0 --persistent
@ -99,7 +99,7 @@ Do not require PCI device to be reset before attaching it to another VM. This ma
usage example:
.. code:: bash
.. code:: console
qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
@ -113,7 +113,7 @@ Allow write access to full PCI config space instead of whitelisted registers. Th
usage example:
.. code:: bash
.. code:: console
qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true
@ -139,7 +139,7 @@ or
- Go to the sysfs (``/sys/bus/pci``), find the right device, detach it from the pciback driver, and attach it back to the original driver. Replace ``<BDF>`` with your full device, for example ``0000:00:1c.2``:
.. code:: bash
.. code:: console
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`

22
user/how-to-guides/how-to-use-usb-devices.rst
View file

@ -47,7 +47,7 @@ In dom0, you can use ``qvm-usb`` from the commandline to attach and detach devic
Listing available USB devices:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
@ -58,7 +58,7 @@ Listing available USB devices:
Attaching selected USB device:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
@ -72,7 +72,7 @@ Now, you can use your USB device (camera in this case) in the ``work`` qube. If
When you finish, detach the device.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
@ -102,7 +102,7 @@ If you receive this error: ``ERROR: qubes-usb-proxy not installed in the qube``,
- Fedora:
.. code:: bash
.. code:: console
sudo dnf install qubes-usb-proxy
@ -110,7 +110,7 @@ If you receive this error: ``ERROR: qubes-usb-proxy not installed in the qube``,
- Debian/Ubuntu:
.. code:: bash
.. code:: console
sudo apt-get install qubes-usb-proxy
@ -136,7 +136,7 @@ You can find your controller and its BDF address using the method described belo
First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
.. code:: bash
.. code:: console
lsusb
@ -144,7 +144,7 @@ First, find out which USB bus the device is connected to (note that these steps
For example, I want to attach a broadband modem to the NetVM. In the output of ``lsusb`` it may be listed as something like:
.. code:: bash
.. code:: output
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
@ -156,7 +156,7 @@ The device is connected to USB bus #3. Check which other devices are connected t
To find the right controller, follow the usb bus:
.. code:: bash
.. code:: console
readlink /sys/bus/usb/devices/usb3
@ -164,7 +164,7 @@ To find the right controller, follow the usb bus:
This should output something like:
.. code:: bash
.. code:: output
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
@ -172,7 +172,7 @@ This should output something like:
Now you see the path: the text between ``/pci0000:00/0000:`` and ``/usb3`` i.e. ``00:1a.0`` is the BDF address. Strip the address and pass it to the :doc:`qvm-pci tool </user/how-to-guides/how-to-use-pci-devices>` to attach the controller to the target qube, like this:
.. code:: bash
.. code:: console
qvm-pci attach --persistent personal dom0:00_1a.0
@ -180,7 +180,7 @@ Now you see the path: the text between ``/pci0000:00/0000:`` and ``/usb3`` i.e.
It is possible that on some system configurations the readlink method produces output which is different from the example above, For example, you might see output like this:
.. code:: bash
.. code:: output
../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1