Merge branch 'master' of https://github.com/QubesOS/qubes-doc

developers/code-signing.md

@@ -0,0 +1,139 @@
+---
+layout: doc
+title: Code Signing
+permalink: /doc/code-signing/
+---
+
+Code Signing
+============
+
+All contributions to the Qubes OS [source code] must be cryptographically signed
+by the author's PGP key.
+
+
+Generating a Key
+----------------
+
+(Note: If you already have a PGP key, you may skip this step.)
+
+Alex Cabal has written an excellent [guide] on creating a PGP keypair.
+Below, we reproduce just the minimum steps in generating a keypair using GnuPG.
+Please read Cabal's full guide for further important details.
+
+~~~
+$ gpg --gen-key
+gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
+This is free software: you are free to change and  redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Please select what kind of key you want:
+    (1) RSA and RSA (default)
+    (2) DSA and Elgamal
+    (3) DSA (sign only)
+    (4) RSA (sign only)
+Your selection? 1
+
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048) 4096
+
+Requested keysize is 4096 bits
+Please specify how long the key should be valid.
+    0 = key does not expire
+    <n>  = key expires in n days
+    <n>w = key expires in n weeks
+    <n>m = key expires in n months
+    <n>y = key expires in n years
+Key is valid for? (0) 0
+
+Key does not expire at all
+Is this correct? (y/N) y
+
+
+You need a user ID to identify your key; the software constructs the user ID
+from the Real Name, Comment and E-mail Address in this form:
+    "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
+
+Real name: Bilbo Baggins
+
+E-mail address: bilbo@shire.org
+
+Comment: 
+You selected this USER-ID:
+    "Bilbo Baggins <bilbo@shire.org>"
+
+Change (N)ame, (C)omment, (E)-mail or (O)kay/(Q)uit? O
+
+You need a Passphrase to protect your secret key.
+
+<type your passphrase>
+
+gpg: key 488BA441 marked as ultimately trusted
+public and secret key created and signed.
+
+gpg: checking the trustdb
+gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
+pub   4096R/488BA441 2013-03-13
+      Key fingerprint = B878 1FB6 B187 B94C 3E52  2AFA EB1D B79A 488B A441
+uid                  Bilbo Baggins <bilbo@shire.org>
+sub   4096R/69B0EA85 2013-03-13
+~~~
+
+
+Using PGP with Git
+------------------
+
+If you're submitting a patch via GitHub (or a similar Git server), please sign
+your Git commits.
+
+1. Set up Git to use your key:
+
+   ~~~
+   git config --global user.signingkey <KEYID>
+   ~~~
+
+2. Set up Git to sign your commits with your key:
+
+   ~~~
+   git config --global commit.gpgsign true
+   ~~~
+
+   Alternatively, manually specify when a commit is to be signed:
+
+   ~~~
+   commit -S
+   ~~~
+
+3. (Optional) Create signed tags:
+
+   ~~~
+   git tag -s <tag_name> -m "<tag_message>"
+   ~~~
+
+   You can also create an alias to make this easier:
+
+   ~~~
+   stag = "!id=`git rev-parse --verify HEAD`; git tag -s tag_for_${id:0:8} -m \"Tag for commit $id\""
+   ~~~
+
+   You may also find it convenient to have an alias for verifying the tag on the
+   latest commit:
+
+   ~~~
+   vtag = !git tag -v `git describe`
+   ~~~
+
+
+Using PGP with Email
+--------------------
+
+If you're submitting a patch via email (to the developer [mailing list]), simply
+sign your email with your PGP key. (One good way to do this is with a program
+like [Enigmail].)
+
+
+[guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
+[source code]: /doc/source-code/
+[mailing list]: /doc/mailing-lists/
+[Enigmail]: https://www.enigmail.net/
+

developers/contributing.md

@@ -19,6 +19,7 @@ First you should decide what you are interested in (and good in). The Qubes proj
 -   Code audit (e.g. gui-daemon)
 -   New features
 -   Artwork (plymouth themes, KDM themes, installer themes, wallpapers, etc)
+-   [Documentation](/doc/doc-guidelines)
 
 Perhaps the best starting point is to have a look at the [issues](https://github.com/QubesOS/qubes-issues/issues) to see what are the most urgent tasks to do.
 

developers/doc-guidelines.md

@@ -8,8 +8,8 @@ redirect_from:
 - /doc/DocStyle/
 ---
 
-Guidelines for Documentation Contributors
-=========================================
+Documentation Guidelines
+========================
 
 All Qubes OS documentation pages are stored as plain text files in the
 dedicated [qubes-doc] repository. By cloning and regularly pulling from

developers/fundamentals/gui.md

@@ -75,7 +75,7 @@ Certainly, it would be insecure to allow AppVM to read/write clipboard of other
 
 -   there is a "qubes clipboard" in dom0 - its contents is stored in a regular file in dom0.
 -   if user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD_DATA* message followed by clipboard contents.
--   user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the the local clipboard, and then user can paste its contents to local applications normally.
+-   user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the local clipboard, and then user can paste its contents to local applications normally.
 
 This way, user can quickly copy clipboards between AppVMs. This action is fully controlled by the user, it cannot be triggered/forced by any AppVM.
 

developers/fundamentals/template-implementation.md

@@ -87,7 +87,7 @@ Steps performed by **qvm-revert-template-changes**:
 3.  Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed).
 4.  Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed.
 5.  Replace *snapshot-merge* d-m target back to *snapshot*.
-6.  Cleanup snapshot device (if nobody uses it it the moment).
+6.  Cleanup snapshot device (if nobody uses it at the moment).
 7.  Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
 
 Snapshot device in AppVM

developers/services/dvm-impl.md

@@ -30,7 +30,7 @@ Preparing a savefile is done by */usr/lib/qubes/qubes\_prepare\_saved\_domain.sh
 6.  when `qubes_used_mem` key appears, the domain memory is reduced to this amount, to make the savefile smaller.
 7.  APPVM private image is detached
 8.  the domain is saved via *xl save*
-9.  the COW file volatile.img (cow for for root fs and swap) is packed to `saved_cows.tar` archive
+9.  the COW file volatile.img (cow for root fs and swap) is packed to `saved_cows.tar` archive
 
 *qubes\_prepare\_saved\_domain.sh* script is somehow lowlevel. It is usually called by *qvm-create-default-dvm* script, that takes care of creating a special AppVM (named template\_name-dvm) to be passed to *qubes\_prepare\_saved\_domain.sh*, as well as copying the savefile to /dev/shm (the latter action is not done if the `/var/lib/qubes/dvmdata/dont_use_shm` file exists).
 
@@ -53,4 +53,4 @@ Validating the DisposableVM savefile
 
 DisposableVM savefile contains references to template rootfs and to COW files. The COW files are restored before each DisposableVM start, so they cannot change. On the other hand, if templateVM is started, the template rootfs will change, and it may not be coherent with the COW files.
 
-Therefore, the check for template rootfs modification time being older than DisposableVM savefile modification time is required. It is done in *qfilexchgd* daemon, just before restoring DisposableVM. If necassary, an attempt is made to recreate the DisposableVM savefile, using the last template used (or default template, if run for the first time) and the default prerun script, residing at */var/lib/qubes/vm-templates/templatename/dispvm\_prerun.sh*. Unfortunately, the prerun script takes a lot of time to execute - therefore, after template rootfs modification, the next DisposableVM creation can be longer by about 2.5 minutes.
+Therefore, the check for template rootfs modification time being older than DisposableVM savefile modification time is required. It is done in *qfilexchgd* daemon, just before restoring DisposableVM. If necessary, an attempt is made to recreate the DisposableVM savefile, using the last template used (or default template, if run for the first time) and the default prerun script, residing at */var/lib/qubes/vm-templates/templatename/dispvm\_prerun.sh*. Unfortunately, the prerun script takes a lot of time to execute - therefore, after template rootfs modification, the next DisposableVM creation can be longer by about 2.5 minutes.

developers/services/qmemman.md

@@ -70,7 +70,7 @@ Additionally, the balance algorithm is tuned so that XEN\_FREE\_MEM\_LEFT (50MB)
 Whenever *qmemman* is asked to return X megabytes of memory to Xen free pool, the following algorithm (*qmemman\_algo.balloon*) is executed:
 
 1.  find all domains ("donors") whose actual memory is greater than its `prefmem`
-2.  calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If is is less than X, return error.
+2.  calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If it is less than X, return error.
 3.  shrink donors, proportionally to their `prefmem`, so that X MB should become free
 4.  wait BALOON\_DELAY (0.1s)
 5.  if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error).

developers/services/qrexec2.md

@@ -313,7 +313,7 @@ steps are taken:
  * `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target
  vmname, rpc action, and CID as cmdline arguments
  * `qrexec-policy` evaluates the policy file. If successful, creates a pair of
- `qrexec-client` processes, whose stdin/stdout are cross-connencted.
+ `qrexec-client` processes, whose stdin/stdout are cross-connected.
    * The first `qrexec-client` connects to the src VM, using the `-c ClientID`
    parameter, which results in not creating a new process, but connecting to
    the existing process file descriptors (these are the fds of unix socket

developers/source-code.md

@@ -11,16 +11,17 @@ redirect_from:
 Qubes Source Code Repositories
 ==============================
 
-All the Qubes code is kept in GIT repositories. We divided the project into several components, each of which has its own separate repository, some of them:
+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:
 
--   `core-admin.git` -- the core Qubes infrastructure responsible for VM management, VM templates, fs sharing, etc.
--   `gui-daemon.git` -- GUI virtualization, Dom0 side.
--   `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
--   `linux-template-builder.git` - scripts and other files used to create Qubes templates images.
+ * `core-admin.git` -- The core Qubes infrastructure, responsible for VM
+   management, VM templates, fs sharing, etc.
+ * `gui-daemon.git` -- GUI virtualization, Dom0 side.
+ * `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
+ * `linux-template-builder.git` -- Scripts and other files used to create Qubes
+   template images.
 
-You can browse the repositories [online on
-GitHub](https://github.com/QubesOS/). The Qubes official repositories are on
-this `QubesOS` github account.
+All of our repositories are available under the [QubesOS GitHub account].
 
 To clone a repository:
 
@@ -34,15 +35,47 @@ e.g.:
 git clone git://github.com/QubesOS/qubes-core-admin.git core-admin
 ~~~
 
-## Sending a patch
+To clone **all** of our repositories in a single command:
 
-If you want to contribute to the project, there are two ways:
+~~~
+curl "https://api.github.com/orgs/QubesOS/repos?page=1&per_page=100" | grep -e 'git_url*' | cut -d \" -f 4 | xargs -L1 git clone
+~~~
 
-*  **Preferred**: Use github [fork & pull requests](https://guides.github.com/activities/forking/)
-*  Sending a patch via the project's mailing list (`git format-patch`).
+To update (git fetch) **all** of these repositories in a single command:
+
+~~~
+find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-submodules=on-demand --all \;
+~~~
+
+(Alternatively, you can pull instead of just fetching.)
+
+
+How to Send Patches
+-------------------
+
+If you want to contribute code to the project, there are two ways. Whichever
+method you choose, you must [sign your code] before it can be accepted.
+
+*  **Preferred**: Use GitHub's [fork & pull requests].
+*  Send a patch to our developer [mailing list] (`git format-patch`).
+
+   1. Make all the changes in your working directory, i.e. edit files, move them
+      around (you can use 'git mv' for this), etc.
+   2. Add the changes and commit them (`git add`, `git commit`). Never mix
+      different changes into one commit! Write a good description of the commit.
+      The first line should contain a short summary, and then, if you feel like
+      more explanations are needed, enter an empty new line, and then start the
+      long, detailed description (optional).
+   3. Test your changes NOW: check if RPMs build fine, etc.
+   4. Create the patch using `git format-patch`. This has an advantage over
+      `git diff`, because the former will also include your commit message, your
+      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]`.
+
+
+[QubesOS GitHub account]: https://github.com/QubesOS/
+[sign your code]: /doc/code-signing/
+[fork & pull requests]: https://guides.github.com/activities/forking/
+[mailing list]: /doc/mailing-lists/
 
-    1.  Make all the changes in your working directory, i.e. edit files, move them around (you can use 'git mv' for this), etc.
-    2.  Add the changes and commit them (git add, git commit). Never mix different changes into one commit! Write a good description of the commit. The first line should contain a short summary, and then, if you feel like more explanations are needed, enter an empty new line, and then start the long, detailed description (optional).
-    3.  Test your changes NOW: check if RPMs build fine, etc.
-    4.  Create the patch using 'git format-patch'. This has an advantage over 'git diff', because the former will also include your commit message, your 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 the '[PATCH]' string.