Update test-bench machine setup

CONTRIBUTING.md

@@ -1,9 +1,8 @@
-Contributing to `qubes-doc`
-===========================
+# Contributing to `qubes-doc`
 
 Thank you for your interest in contributing to `qubes-doc`, the Qubes OS
 Project's dedicated documentation repository! Please take a moment to read our
-[Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/) before you begin writing. These guidelines are
-important to maintaining high quality documentation, and following them will
-increase the likelihood that your contribution will be accepted.
-
+[Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/) before
+you begin writing. These guidelines are important to maintaining high quality
+documentation, and following them will increase the likelihood that your
+contribution will be accepted.

README.md

@@ -1,13 +1,11 @@
-Qubes OS Documentation
-======================
+# Qubes OS Documentation
 
 Canonical URL: https://www.qubes-os.org/doc/
 
-All [Qubes OS Project](https://github.com/QubesOS) documentation pages are stored as plain text
-files in this dedicated repository. By cloning and regularly pulling from
-this repo, users can maintain their own up-to-date offline copy of all
-Qubes documentation rather than relying solely on the Web.
+All [Qubes OS Project](https://github.com/QubesOS) documentation pages are
+stored as plain text files in this dedicated repository. By cloning and
+regularly pulling from this repo, users can maintain their own up-to-date
+offline copy of all Qubes documentation rather than relying solely on the Web.
 
 For more information about the documentation, including how to contribute,
 please see the [Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/).
-

developer/building/development-workflow.md

@@ -10,7 +10,6 @@ ref: 66
 title: Development Workflow
 ---
 
-
 A workflow for developing Qubes OS+
 
 First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
@@ -537,4 +536,3 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and
 ~~~
 deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main
 ~~~
-

developer/building/qubes-builder-details.md

@@ -10,7 +10,6 @@ ref: 65
 title: Qubes Builder Details
 ---
 
-
 Components Makefile.builder file
 --------------------------------
 

developer/building/qubes-iso-building.md

@@ -12,7 +12,6 @@ ref: 63
 title: Qubes ISO Building
 ---
 
-
 Build Environment
 -----------------
 

developer/building/qubes-template-configs.md

@@ -3,5 +3,6 @@ lang: en
 layout: doc
 permalink: /doc/qubes-template-configs/
 redirect_to: https://github.com/QubesOS/qubes-template-configs
+ref: 248
 title: Qubes Template Configs
 ---

developer/code/code-signing.md

@@ -6,7 +6,6 @@ ref: 51
 title: Code Signing
 ---
 
-
 All contributions to the Qubes OS [source code](/doc/source-code/) must be cryptographically signed by the author's PGP key.
 
 ## Generating a Key
@@ -202,4 +201,3 @@ Please upload it.
 If you're submitting a patch by emailing the [developer mailing list](/support/#qubes-devel), simply sign your email with your PGP key.
 One good way to do this is with a program like [Enigmail](https://www.enigmail.net/).
 Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails.
-

developer/code/coding-style.md

@@ -11,7 +11,6 @@ ref: 53
 title: Coding Style
 ---
 
-
 Rationale
 ---------
 

developer/code/license.md

@@ -10,7 +10,14 @@ ref: 52
 title: Software License
 ---
 
+Qubes OS is a compilation of software packages, each under its own license. The
+compilation is made available under the GNU General Public License version 2
+(GPLv2).
 
-Qubes is a compilation of software packages, each under its own license. The compilation is made available under the GNU General Public License version 2.
+The source code of Qubes OS is contained in repositories under the
+[@QubesOS](https://github.com/QubesOS) account on GitHub. This source code is
+made available under GPLv2, unless there is a `LICENSE` file in the root of the
+containing repository that specifies a different license.
 
-The full text of the GPL v2 license can be found [here](https://www.gnu.org/licenses/gpl-2.0.html).
+The full text of the GPLv2 license can be found
+[here](https://www.gnu.org/licenses/gpl-2.0.html).

developer/code/source-code.md

@@ -10,7 +10,6 @@ ref: 54
 title: Source Code
 ---
 
-
 All the Qubes code is kept in Git repositories. We have divided the project into
 several components, each of which has its own separate repository, for example:
 
@@ -81,4 +80,3 @@ method you choose, you must [sign your code](/doc/code-signing/) before it can b
       name and email, so that *your* name will be used as a commit's author.
    5. Send your patch to `qubes-devel`. Start the message subject with
       `[PATCH]`.
-

developer/debugging/automated-tests.md

@@ -9,7 +9,6 @@ ref: 45
 title: Automated Tests
 ---
 
-
 ## Unit and Integration Tests
 
 Starting with Qubes R3 we use [python unittest](https://docs.python.org/3/library/unittest.html) to perform automatic tests of Qubes OS.
@@ -114,7 +113,7 @@ vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file
 
 Example test run:
 
-![snapshot-tests2.png](/attachment/wiki/developers/snapshot-tests2.png)
+![snapshot-tests2.png](/attachment/doc/snapshot-tests2.png)
 
 Tests are also compatible with nose2 test runner, so you can use this instead:
 
@@ -260,4 +259,3 @@ In practice, however, either Xen or QEMU crashes when this is attempted.
 Nonetheless, PV works well, which is sufficient for automated installation testing.
 
 Thanks to an anonymous donor, our openQA system is hosted in a datacenter on hardware that meets these requirements.
-

developer/debugging/mount-lvm-image.md

@@ -6,7 +6,6 @@ ref: 46
 title: How to Mount LVM Images
 ---
 
-
 You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0).
 
 1: make the image available for qubesdb.
@@ -53,4 +52,3 @@ From the GUI, or from the command line:
 # References
 
 Please consult this issue's [comment](https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625).
-

developer/debugging/profiling.md

@@ -10,7 +10,6 @@ ref: 48
 title: Python Profiling
 ---
 
-
 This is a python profiling primer.
 
 For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats.
@@ -94,6 +93,6 @@ make REMOTE=example.com:public_html/qubes/profiling/ upload
 
 This example is from `qubes-manager` (`qubesmanager/main.py`).
 
-!["update\_table-20140424-170010.svg"](//attachment/wiki/Profiling/update_table-20140424-170010.svg)
+!["update\_table-20140424-170010.svg"](//attachment/doc/update_table-20140424-170010.svg)
 
 It is apparent that the problem is around `get_disk_usage`, which calls something via `subprocess.call`. It does this 15 times, probably once per VM.

developer/debugging/safe-remote-ttys.md

@@ -8,7 +8,6 @@ ref: 49
 title: Safe Remote Dom0 Terminals
 ---
 
-
 If you do not have working graphics in Dom0, then using a terminal can be quite annoying!
 This was the case for the author while trying to debug PCI-passthrough of a machine's primary (only) GPU.
 

developer/debugging/test-bench.md

@@ -10,62 +10,75 @@ ref: 44
 title: How to Set Up a Test Bench
 ---
 
-
 This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal.
 
 We will set up a spare machine (bare metal, not a virtual) that will be hosting our experimental Dom0. We will communicate with it via Ethernet and SSH. This tutorial assumes you are familiar with [QubesBuilder](/doc/qubes-builder/) and you have it set up and running flawlessly.
 
-## Setting up the machine
+> **Notice:**
+> This setup intentionally weakens some security properties in the testing system. So make sure you understand the risks and use exclusively for testing.
 
-First, do a clean install from ISO you built or grabbed elsewhere.
+## Setting up the Machine
 
-You have to fix network, because it is intentionally broken. This script should reenable your network card without depending on anything else.
+### Install ISO
+First, do a clean install from the `.iso` [you built](/doc/qubes-iso-building/) or grabbed elsewhere (for example [here](https://qubes-os.discourse.group/t/qubesos-4-1-alpha-signed-weekly-builds/3601))
 
-```bash
-#!/bin/sh
+### Enabling Network Access in Dom0
 
-# adjust this for your NIC (run lspci)
-BDF=0000:02:00.0
-
-prog=$(basename $0)
-
-pciunbind() {
-    local path
-    path=/sys/bus/pci/devices/${1}/driver/unbind
-    if ! [ -w ${path} ]; then
-        echo "${prog}: Device ${1} not bound"
-        return 1
-    fi
-    echo -n ${1} >${path}
-}
-
-pcibind() {
-    local path
-    path=/sys/bus/pci/drivers/${2}/bind
-    if ! [ -w ${path} ]; then
-        echo "${prog}: Driver ${2} not found"
-        return 1
-    fi
-    echo ${1} >${path}
-}
-
-pciunbind ${BDF}
-pcibind ${BDF} e1000e
-
-dhclient
-```
+Internet access is intentionally disabled by default in dom0. But to ease the deployment process we will give it access. The following steps should be done in `dom0`.
 
-TODO: describe how to run this at every startup
+> **Note:** the following assume you have only one network card. If you have two, pick one and leave the other attached to `sys-net`.
 
-Now configure your DHCP server so your testbench gets static IP and connect your machine to your local network. You should ensure that your testbench can reach the Internet.
+1. Remove the network card (PCI device) from `sys-net`
+2. Restart your computer (for the removal to take effect)
+3. The following script should enable your network card in dom0. *Be sure to adjust the script's variables to suit your needs.* You'll need to run this at every startup (TODO: describe how to run this at every startup).
 
-Install `openssh-server` on your testbench:
+    ```bash
+    #!/bin/sh
 
-~~~
-yum install openssh-server
-~~~
+    # adjust this for your NIC (run lspci)
+    BDF=0000:02:00.0
+
+    # adjust this for your network driver
+    DRIVER=e1000e
 
-Ensure that sudo works without password from your user account (it should by default).
+    prog=$(basename $0)
+
+    pciunbind() {
+        local path
+        path=/sys/bus/pci/devices/${1}/driver/unbind
+        if ! [ -w ${path} ]; then
+            echo "${prog}: Device ${1} not bound"
+            return 1
+        fi
+        echo -n ${1} >${path}
+    }
+
+    pcibind() {
+        local path
+        path=/sys/bus/pci/drivers/${2}/bind
+        if ! [ -w ${path} ]; then
+            echo "${prog}: Driver ${2} not found"
+            return 1
+        fi
+        echo ${1} >${path}
+    }
+
+    pciunbind ${BDF}
+    pcibind ${BDF} ${DRIVER}
+
+    sleep 1
+    dhclient
+    ```
+
+4. Configure your DHCP server so your testbench gets static IP and connect your machine to your local network. You should ensure that your testbench can reach the Internet.
+
+5. Install `openssh-server` on your testbench.
+
+    ~~~
+    sudo dnf --setopt=reposdir=/etc/yum.repos.d install openssh-server
+    ~~~
+
+> **Note:** If you want to install additional software in dom0 and your only network card was assigned to dom0, then _instead_ of the usual `sudo qubes-dom0-update <PACKAGE>` now you run `sudo dnf --setopt=reposdir=/etc/yum.repos.d install <PACKAGE>`.
 
 ## Development VM
 
@@ -87,7 +100,9 @@ Host testbench
     HostName 192.168.123.45
 ~~~
 
-Then connect to your testbench and paste newly generated `id_ecdsa.pub` to `.ssh/authorized_keys` on testbench so you can log in without entering password every time.
+#### Passwordless SSH Login
+
+To log to your testbench without entering password every time, copy your newly generated public key (`id_ecdsa.pub`) to `~/.ssh/authorized_keys` on your testbench. You can do this easily by running this command on `qubes-dev`: `ssh-copy-id -i ~/.ssh/id_ecdsa.pub user@192.168.123.45` (substituting with the actual username address of your testbench).
 
 ### Scripting
 
@@ -116,7 +131,7 @@ fi
 set -e
 
 ssh testbench mkdir -p "${TMPDIR}"
-scp "${@}" testbench:"${TMPDIR}"
+scp "${@}" testbench:"${TMPDIR}" || echo "check if you have 'scp' installed on your testbench"
 
 while [ $# -gt 0 ]; do
         ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})"

developer/debugging/vm-interface.md

@@ -11,7 +11,6 @@ ref: 47
 title: VM Configuration Interface
 ---
 
-
 Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
 
 - QubesDB

developer/debugging/windows-debugging.md

@@ -10,7 +10,6 @@ ref: 50
 title: Windows Debugging
 ---
 
-
 Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs.
 
 User-mode debugging is usually straightforward if it can be done on one machine. Just duplicate your normal debugging environment in the VM.