diff --git a/about/faq.md b/about/faq.md index 61e08437..1feb568f 100644 --- a/about/faq.md +++ b/about/faq.md @@ -431,7 +431,7 @@ The encrypted partitions are identified and the user is prompted for password on A fully encrypted drive does not appear in Nautilus. -The work round is to manually decrypt and mount the drive: +The workaround is to manually decrypt and mount the drive: 1. attach usb device to qube - it should be attached as /dev/xvdi or similar. 2. sudo cryptsetup open /dev/xvdi bk --type luks diff --git a/basics_dev/coding-style.md b/basics_dev/coding-style.md index 35477e43..f37e2b90 100644 --- a/basics_dev/coding-style.md +++ b/basics_dev/coding-style.md @@ -97,7 +97,7 @@ General programming style guidelines } ~~~ -- Do **not** use comments to disable code fragments. In a production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.: +- Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.: ~~~ #if 0 @@ -130,7 +130,7 @@ Source Code management (Git) guidelines - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts. - By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code. - Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source. - - We have drastically changes the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html). + - We have drastically changed the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html). Commit message guidelines ------------------------- @@ -165,7 +165,7 @@ Security coding guidelines height = untrusted_conf.height; ~~~ -- Use another variables, without the `untrusted_` prefix to hold the sanitized values, as shown above. +- Use others variables, without the `untrusted_` prefix to hold the sanitized values, as shown above. Python-specific guidelines -------------------------- @@ -178,7 +178,7 @@ C and C++ specific guidelines - Do not place code in `*.h` files. - Use `const` whenever possible, e.g. in function arguments passed via pointers. - Do not mix procedural and objective code together -- if you write in C++, use classes and objects. -- Think about classes hierarchy, before start implementing specific methods. +- Think about classes hierarchy, before starting to implement specific methods. Bash-specific guidelines ------------------------ diff --git a/basics_dev/style-guide.md b/basics_dev/style-guide.md index 160e8666..32f0259a 100644 --- a/basics_dev/style-guide.md +++ b/basics_dev/style-guide.md @@ -68,7 +68,7 @@ Currently, all the icons on the Qubes-OS.org website are generated using [FontAw ## Logos -The following is a collection of various sizes & versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork). +The following is a collection of various sizes and versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
{% for logo in site.data.styleguide.logos %} diff --git a/basics_dev/usability-ux.md b/basics_dev/usability-ux.md index b8762d0e..03747bd0 100644 --- a/basics_dev/usability-ux.md +++ b/basics_dev/usability-ux.md @@ -44,7 +44,7 @@ In making software easy to use, it is crucial to be mindful of [cognitive load]( ## Easy to Understand -There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none these are absolute maxims! +There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none of these are absolute maxims!
Avoid Acronyms @@ -82,7 +82,7 @@ Technical words are usually more accurate, but they often *only* make sense to t - `savefile` - `qrexec-daemon` -These are all terms that have at some point showed up in users' notification messages. Each term is very specific, but requires the user to understand virtualization to interpet. +These are all terms that have at some point showed up in users' notification messages. Each term is very specific, but requires the user to understand virtualization to interpret.
Use Common Concepts @@ -195,7 +195,7 @@ There are many cases where a user wants to perform an action on more than one fi 3. Select proper file 4. Complete task on file -That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couples files in the same directory. We can alleviate some of the work by changing the process: +That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couple files in the same directory. We can alleviate some of the work by changing the process: 1. Click on `Open File` from a menu or button 2. Remember last open folder/file system diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index 3ac2b48d..e58459e8 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -43,7 +43,7 @@ documentation change will be reviewed before it's published to the web. This allows us to maintain quality control and protect our users. As mentioned above, we keep all the documentation in a dedicated [Git -repository][qubes-doc] hosted on [GitHub]. Thanks to GitHub's interface, you can +repository][qubes-doc] hosted on [GitHub]. Thanks to the GitHub's interface, you can edit the documentation even if you don't know Git at all! The only thing you need is a GitHub account, which is free. diff --git a/building/building-archlinux-template.md b/building/building-archlinux-template.md index ff701a4d..a9989c0d 100644 --- a/building/building-archlinux-template.md +++ b/building/building-archlinux-template.md @@ -362,7 +362,7 @@ redirect_from: The `qubes-mgmt-salt` repo is not currently forked under the marmarek user on GitHub, to whom the above instructions set the `GIT_PREFIX`. As Archlinux is not yet supported by mgmt-salt, simply leave it out of the build (when building -the Archlinux template on it's own) by appending the following to your `override.conf` file: +the Archlinux template on its own) by appending the following to your `override.conf` file: `BUILDER_PLUGINS := $(filter-out mgmt-salt,$(BUILDER_PLUGINS))` diff --git a/building/development-workflow.md b/building/development-workflow.md index 4ddce81f..3f9b2fcd 100644 --- a/building/development-workflow.md +++ b/building/development-workflow.md @@ -419,7 +419,7 @@ Remember to also import gpg public key using `rpm --import`. ### Deb packages - Apt repo -Steps are mostly the same as in case of yum repo. Only details differs: +Steps are mostly the same as in the case of yum repo. The only details that differ: - use [linux-deb] instead of [linux-yum] as a base - both in source and target VM - use different `update_repo.sh` script in source VM (below) diff --git a/building/qubes-builder-details.md b/building/qubes-builder-details.md index 735c4cc5..48e5e7d6 100644 --- a/building/qubes-builder-details.md +++ b/building/qubes-builder-details.md @@ -33,8 +33,8 @@ Variables for Windows build: - `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables: - `CERT_FILENAME` Path to key file (pfx format) - `CERT_PASSWORD` Key password - - `CERT_PUBLIC_FILENAME` Certificate path in case of self-signed cert - - `CERT_CROSS_CERT_FILENAME` Certificate path in case of correct autheticode cert + - `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert + - `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert - `SIGNTOOL` Path to signtool - `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command. - `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components. diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index 24be5e44..4d9bd8f8 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -215,7 +215,7 @@ Here are some things to consider when selecting a passphrase for your backups: For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase. * If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). - On the othe hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you. + On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you. Notes ----- diff --git a/common-tasks/full-screen-mode.md b/common-tasks/full-screen-mode.md index b0fef0cc..e5542918 100644 --- a/common-tasks/full-screen-mode.md +++ b/common-tasks/full-screen-mode.md @@ -24,7 +24,7 @@ If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on Secure use of full screen mode ------------------------------ -However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such q mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts. +However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts. Another option is to use Alt+Tab for switching windows. This shortcut is also handled by dom0. Enabling full screen mode for select VMs diff --git a/common-tasks/managing-appvm-shortcuts.md b/common-tasks/managing-appvm-shortcuts.md index e289ae79..237d9368 100644 --- a/common-tasks/managing-appvm-shortcuts.md +++ b/common-tasks/managing-appvm-shortcuts.md @@ -15,11 +15,11 @@ For ease of use Qubes aggregates shortcuts to applications that are installed in ![dom0-menu.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-menu.png) -To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs does this automatically): +To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs do this automatically): `qvm-sync-appmenus vmname` -After that, select the *Add more shortcuts* entry in VM's submenu to customize which applications are shown: +After that, select the *Add more shortcuts* entry in the VM's submenu to customize which applications are shown: ![dom0-appmenu-select.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-appmenu-select.png) @@ -33,7 +33,7 @@ What about applications in DispVMs? Behind the scenes ----------------- -The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`. +The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in the case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`. Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'` Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'` @@ -45,4 +45,4 @@ For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Wi What if my application has not been automatically included in the list of available apps? ----------------------------------------------------------------------------------------- -You can manually create new entries in the "available applications" list of shortcuts. See [Signal](/doc/signal/) for a worked example of creating a new menu item for a Chrome .desktop shortcut. +You can manually create new entries in the "available applications" list of shortcuts. See [Signal](/doc/signal/) for a working example of creating a new menu item for a Chrome .desktop shortcut. diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index e39a1f2c..85974a4d 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -14,7 +14,7 @@ Updating software in dom0 Why would one want to update software in dom0? ---------------------------------------------- -Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain.) Of course, we believe this software is reasonably secure, and we hope it will not need patching. +Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching. However, we anticipate some other situations in which updating dom0 software might be necessary or desirable: diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index 2feab516..2f04d888 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -37,7 +37,7 @@ In order to permanently install new software, you should: - Install/update software as usual (e.g. using dnf, or the dedicated GUI application). Then, shutdown the template VM, -- You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you. +- You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You can restart others whenever this will be convenient to you. Testing repositories -------------------- @@ -124,17 +124,17 @@ As the TemplateVM is used for creating filesystems for other AppVMs, where you a There are several ways to deal with this problem: -- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos. +- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos. - Use *standalone VMs* (see below) for installation of untrusted software packages. -- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from somehow less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos. +- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos. Some popular questions: - So, why should we actually trust Fedora repos -- it also contains large amount of third-party software that might buggy, right? -As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise. +As far as the template's compromise is concerned, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and get infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise. - But why trust Fedora? @@ -147,13 +147,13 @@ Not quite. Dom0 compromise is absolutely fatal, and it leads to Game OverTM Standalone VMs -------------- -Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on its own. But this means that they take a few GBs on disk, and also that centralized updates do not apply to them. +Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own. But this means that they take a few GBs on disk, and also that centralized updates do not apply to them. -Sometime it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. Such situations include e.g.: +Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. Such situations include e.g.: -- VMs used for development (devel environments requires a lot of \*-devel packages and specific devel tools) +- VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools) -- VMs used for installing untrusted packages. Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). However, when you would like to install some packages form less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way. +- VMs used for installing untrusted packages. Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way. In order to create a standalone VM you can use a command line like this (from console in Dom0): @@ -177,14 +177,14 @@ qvm-create --template --label