Merge pull request #1 from maiska/toki-newlines

Reformat for better conversion to RST

introduction/issue-tracking.md

@@ -96,12 +96,12 @@ Meta-issues must abide by the following rules:
 - Only members of the core team may create meta-issues (or convert existing issues into meta-issues).
 
 
-  Rationale: The purpose of meta-issues is to track the development of certain features that fit into the overall goals of the Qubes OS Project, which requires making informed project-management decisions with the approval of the project lead.
+  - Rationale: The purpose of meta-issues is to track the development of certain features that fit into the overall goals of the Qubes OS Project, which requires making informed project-management decisions with the approval of the project lead.
 
 - Meta-issues must be [locked](https://docs.github.com/en/communities/moderating-comments-and-conversations/locking-conversations).
 
 
-  Rationale: One of the historical problems we've experienced with meta-issues (and one of the reasons they were discouraged for a long time) is that each meta-issue tends to turn into a discussion thread that becomes hopelessly long to the point where the person who is supposed to work on it has no idea what is supposed to be done or where to start, and it eventually just gets closed. Locking is intended to prevent that from happening again.
+  - Rationale: One of the historical problems we've experienced with meta-issues (and one of the reasons they were discouraged for a long time) is that each meta-issue tends to turn into a discussion thread that becomes hopelessly long to the point where the person who is supposed to work on it has no idea what is supposed to be done or where to start, and it eventually just gets closed. Locking is intended to prevent that from happening again.
 
 - Meta-issues must have informative descriptions, not just lists of issues. In particular, each meta-issue should explain its goal, what is in scope, and what the relevant categories and priorities are.
 

user/downloading-installing-upgrading/upgrade/3_1.md

@@ -98,7 +98,7 @@ complete.
 
 4. Reboot dom0.
     
-    The system may hang during the reboot. If that happens, do not panic. All
+   - The system may hang during the reboot. If that happens, do not panic. All
      the filesystems will have already been unmounted at this stage, so you can
      simply perform a hard reboot (e.g., hold the physical power button down
      until the machine shuts off, wait a moment, then press it again to start it

user/how-to-guides/how-to-back-up-restore-and-migrate.md

@@ -53,42 +53,42 @@ fresh installation.
 2. Move the VMs that you want to back up to the right-hand **Selected** column.
    VMs in the left-hand **Available** column will not be backed up.
 
-   You may choose whether to compress backups by checking or unchecking the
+   - You may choose whether to compress backups by checking or unchecking the
      **Compress the backup** box. Normally this should be left on unless you have
      a specific reason otherwise.
 
-   Once you have selected all desired VMs, click **Next**.
+   - Once you have selected all desired VMs, click **Next**.
 
 3. Select the destination for the backup:
 
-   If you wish to send your backup to a (currently running) VM, select the VM
+   - If you wish to send your backup to a (currently running) VM, select the VM
      in the drop-down box next to **Target app qube**. If you wish to send your
      backup to a [USB mass storage device](/doc/usb/), you can use the directory
      selection widget to mount a connected device (under "Other locations" item
      on the left); or first mount the device in a VM, then select the mount point
      inside that VM as the backup destination.
 
-   You must also specify a directory on the device or in the VM, or a command
+   - You must also specify a directory on the device or in the VM, or a command
      to be executed in the VM as a destination for your backup. For example, if
      you wish to send your backup to the `~/backups` folder in the target VM, you
      would simply browse to it using the convenient directory selection dialog
      (`...`) at the right. This destination directory must already exist. If it
      does not exist, you must create it manually prior to backing up.
 
-   By specifying the appropriate directory as the destination in a VM, it is
+   - By specifying the appropriate directory as the destination in a VM, it is
      possible to send the backup directly to, e.g., a USB mass storage device
      attached to the VM. Likewise, it is possible to enter any command as a
      backup target by specifying the command as the destination in the VM. This
      can be used to send your backup directly to, e.g., a remote server using
      SSH.
 
-   **Note:** The supplied passphrase is used for **both** encryption/decryption
+   - **Note:** The supplied passphrase is used for **both** encryption/decryption
      and integrity verification.
 
-   At this point, you may also choose whether to save your settings by checking
+   - At this point, you may also choose whether to save your settings by checking
      or unchecking the **Save settings as default backup profile** box.
 
-   **Warning: Saving the settings will result in your backup passphrase being
+   - **Warning: Saving the settings will result in your backup passphrase being
      saved in plaintext in dom0, so consider your threat model before checking
      this box.**
 
@@ -148,7 +148,7 @@ fresh installation.
 a passphrase was supplied during the creation of your backup (regardless of
 whether it is encrypted), then you must supply it here.
 
-   **Note:** The passphrase which was supplied when the backup was created is
+   - **Note:** The passphrase which was supplied when the backup was created is
      used for **both** encryption/decryption and integrity verification. If the
      backup was not encrypted, the supplied passphrase is used only for integrity
      verification. All backups made from a Qubes R4.0 system will be encrypted.

user/how-to-guides/how-to-install-software.md

@@ -432,7 +432,7 @@ these in an app qube you need to take the following steps:
    **app qube*** launch the Qube Settings. Then go to the Applications tab and
    click "Refresh Applications"
 
-   The refresh will take a few minutes; after it's complete the Snap app will
+   - The refresh will take a few minutes; after it's complete the Snap app will
      appear in the app qube's list of available applications. At this point the
      snap will be persistent within the app qube and will receive updates when
      the app qube is running.

user/how-to-guides/how-to-reinstall-a-template.md

@@ -49,13 +49,13 @@ If you want to reinstall more than one template, repeat these instructions for e
 1. Clone the existing target template.
 
 
-   This can be a good idea if you've customized the existing template and want to keep your customizations.
+   - This can be a good idea if you've customized the existing template and want to keep your customizations.
      On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure.
 
 2. Temporarily change all VMs based on the target template to the new clone template, or remove them.
 
 
-   This can be a good idea if you have user data in these VMs that you want to keep.
+   - This can be a good idea if you have user data in these VMs that you want to keep.
      On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead.
      You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove <vm-name>` in dom0.
 

user/how-to-guides/how-to-use-block-storage-devices.md

@@ -90,9 +90,9 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger
     qvm-block attach work sys-usb:sdb
     ```
 
-    This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
+    - This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
 
-    You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`.
+    - You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`.
 
 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.
@@ -106,7 +106,7 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger
 
 4. When you finish using the block device, click the eject button or right-click and select **Unmount**.
 
-    If you've manually mounted a single partition in the above step, use:
+    - If you've manually mounted a single partition in the above step, use:
 
     ```
     sudo umount mnt
@@ -179,9 +179,9 @@ To attach a file as block device to another qube, first turn it into a loopback
 2. If you want to use the GUI, you're done.
     Click the Device Manager ![device manager icon](/attachment/doc/media-removable.png) and select the `loop0`-device to attach it to another qube.
 
-    If you rather use the command line, continue:
+    - If you rather use the command line, continue:
 
-    In dom0, run `qvm-block` to display known block devices.
+    - In dom0, run `qvm-block` to display known block devices.
       The newly created loop device should show up:
 
     ```shell_session

user/security-in-qubes/data-leaks.md

@@ -48,9 +48,9 @@ Such attacks have been described in the academic literature, but it is doubtful
 3. **Unintentional leaks.** Non-malicious software which is either buggy or doesn't maintain the privacy of user data, whether by design or accident.
    For example, software which automatically sends error reports to a remote server, where these reports contain details about the system which the user did not want to share.
 
-   Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an app qube to "none") can fully protect against leaks of type 3.
+Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an app qube to "none") can fully protect against leaks of type 3.
-   However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2.
+However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2.
-   There are few effective, practical policy measures available to end-users today to stop the leaks of type 1.
+There are few effective, practical policy measures available to end-users today to stop the leaks of type 1.
-   It is likely that the only way to fully protect against leaks of type 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation).
+It is likely that the only way to fully protect against leaks of type 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation).
 
 For further discussion, see [this thread](https://groups.google.com/d/topic/qubes-users/t0cmNfuVduw/discussion).

user/security-in-qubes/firewall.md

@@ -165,7 +165,7 @@ Consider the following example. `mytcp-service` qube has a TCP service running o
     [user@untrusted #]$ qvm-connect-tcp 444:@default:444
     ~~~
 
-  - **Note:** The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
+- **Note:** The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
 
 The service of `mytcp-service` running on port `444` is now accessible in `untrusted` as `localhost:444`.
 
@@ -263,9 +263,9 @@ In order to allow a service present in a qube to be exposed to the outside world
 
 As an example we can take the use case of qube QubeDest running a web server listening on port 443 that we want to expose on our physical interface ens6, but only to our local network 192.168.x.y/24.
 
-> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running
+- **Note:** To have all interfaces available and configured, make sure the 3 qubes are up and running
 
-> Note: [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
+- **Note:** [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
 
 **1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
 
@@ -278,7 +278,7 @@ You can get this information using various methods, but only the first one can b
 
 Note the IP addresses you will need, they will be required in the next steps.
 
-  - **Note:** The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface.
+- **Note:** The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface.
 
 **2. Route packets from the outside world to the FirewallVM**
 
@@ -290,9 +290,9 @@ In the sys-net VM's Terminal, the first step is to define an ntables chain that
 nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
 ```
 
-  - **Note:** the name `custom-dnat-qubeDST` is arbitrary
+- **Note:** the name `custom-dnat-qubeDST` is arbitrary
 
-  - **Note:** while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes
+- **Note:** while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes
 
 Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
 
@@ -306,9 +306,9 @@ Third step, code the appropriate new filtering firewall rule to allow new connec
 nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
 ```
 
-  - **Note:** If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
+- **Note:** If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
 
-> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely.
+- If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely.
 
 Verify the rules on sys-net firewall correctly match the packets you want by looking at its counters, check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
 
@@ -380,7 +380,7 @@ Third step, code the appropriate new filtering firewall rule to allow new connec
 nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
 ```
 
- -  **Note:** If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
+- **Note:** If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
 
 Once you have confirmed that the counters increase, store these commands in the script `/rw/config/qubes-firewall-user-script`
 

user/security-in-qubes/split-gpg.md

@@ -297,7 +297,7 @@ In this example, the following keys are stored in the following locations (see b
 
 - `sec` (master secret key)
 
-   Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys.
+   * Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys.
      This key may be created *without* an expiration date.
      This is for two reasons.
      First, the master secret key is never to leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below).
@@ -306,7 +306,7 @@ In this example, the following keys are stored in the following locations (see b
      An adversary who does *not* possess the passphrase cannot use the key at all.
      In either case, an expiration date provides no additional benefit.
 
-   By the same token, however, having a passphrase on the key is of little value.
+   * By the same token, however, having a passphrase on the key is of little value.
      An adversary who is capable of stealing the key from your `vault` would almost certainly also be capable of stealing the passphrase as you enter it.
      An adversary who obtains the passphrase can then use it in order to change or remove the passphrase from the key.
      Therefore, using a passphrase at all should be considered optional.
@@ -314,40 +314,40 @@ In this example, the following keys are stored in the following locations (see b
 
 - `ssb` (secret subkey)
 
-   Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**.
+   * Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**.
      You may also wish to give these subkeys reasonable expiration dates (e.g., one year).
      Once these keys expire, it is up to you whether to *renew* these keys by extending the expiration dates or to create *new* subkeys when the existing set expires.
 
-   On the one hand, an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted to that subkey.
+   * On the one hand, an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted to that subkey.
      If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the `work-gpg` VM being compromised; see below) in order to decrypt *all* of the user's emails.
      If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails.
 
-   On the other hand, creating a new signing subkey each year without renewing (i.e., extending the expiration dates of) existing signing subkeys would mean that all of your old signatures would eventually read as "EXPIRED" whenever someone attempts to verify them.
+   * On the other hand, creating a new signing subkey each year without renewing (i.e., extending the expiration dates of) existing signing subkeys would mean that all of your old signatures would eventually read as "EXPIRED" whenever someone attempts to verify them.
      This can be problematic, since there is no consensus on how expired signatures should be handled.
      Generally, digital signatures are intended to last forever, so this is a strong reason against regularly retiring one's signing subkeys.
 
 - `pub` (public key)
 
-   This is the complement of the master secret key.
+   * This is the complement of the master secret key.
      It can be uploaded to keyservers (or otherwise publicly distributed) and may be signed by others.
 
 - `vault`
 
-   This is a network-isolated VM.
+   * This is a network-isolated VM.
      The initial master keypair and subkeys are generated in this VM.
      The master secret key *never* leaves this VM under *any* circumstances.
      No files or text is *ever* [copied](/doc/how-to-copy-and-move-files/#security) or [pasted](/doc/how-to-copy-and-paste-text/#security) into this VM under *any* circumstances.
 
 - `work-gpg`
 
-   This is a network-isolated VM.
+   * This is a network-isolated VM.
      This VM is used *only* as the GPG backend for `work-email`.
      The secret subkeys (but *not* the master secret key) are [copied](/doc/how-to-copy-and-move-files/#security) from the `vault` VM to this VM.
      Files from less trusted VMs are *never* [copied](/doc/how-to-copy-and-move-files/#security) into this VM under *any* circumstances.
 
 - `work-email`
 
-   This VM has access to the mail server.
+   * This VM has access to the mail server.
      It accesses the `work-gpg` VM via the Split GPG protocol.
      The public key may be stored in this VM so that it can be attached to emails and for other such purposes.
 

user/troubleshooting/uefi-troubleshooting.md

@@ -23,6 +23,7 @@ If you've installed successfully in legacy mode but had to change some kernel pa
 04. Install using your modified boot entry
 
 **Change xen configuration directly in an iso image**
+
 01. Set up a loop device (replacing `X` with your ISO's version name): `losetup -P /dev/loop0 Qubes-RX-x86_64.iso`
 02. Mount the loop device: `sudo mount /dev/loop0p2 /mnt`
 03. Edit `EFI/BOOT/BOOTX64.cfg` to add your params to the `kernel` configuration key

user/troubleshooting/update-troubleshooting.md

@@ -43,5 +43,6 @@ This can usually be fixed by updating via the command line.
 In dom0, open a terminal and run `sudo qubes-dom0-update`.
 
 Depending on your operating system, open a terminal in the templates and run:
+
 * Fedora: `sudo dnf upgrade`
 * Debian: `apt-get update && apt-get dist-upgrade`