diff --git a/basics_dev/coding-style.md b/basics_dev/coding-style.md index c7a18b80..b506db81 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 equivalent 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/reporting-bugs.md b/basics_user/reporting-bugs.md index 7cd31084..6cc8f78c 100644 --- a/basics_user/reporting-bugs.md +++ b/basics_user/reporting-bugs.md @@ -74,7 +74,7 @@ How to submit a report on GitHub We track all bugs in the [qubes-issues] tracker on GitHub. When you file a new issue, you should be sure to include the version of Qubes -your'e using, as well as versions of related software packages. If your issue is +you're using, as well as versions of related software packages. If your issue is related to hardware, provide as many details as possible about the hardware, which could include using command-line tools such as `lspci`. If you're reporting a bug in a package that is in a [testing] repository, please reference the appropriate issue in the [updates-status] repository. diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index c1e1a716..1bd3f567 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -125,7 +125,7 @@ Some popular questions: - So, why should we actually trust Fedora repos -- it also contains large amount of 3rd 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 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. +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? @@ -138,7 +138,7 @@ 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. 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.: diff --git a/configuration/config-files.md b/configuration/config-files.md index dc59d50c..66b53df3 100644 --- a/configuration/config-files.md +++ b/configuration/config-files.md @@ -40,8 +40,8 @@ problematic device drivers. Note that scripts need to be executable (chmod +x) to be used. -Also take a look at [bind-dirs](/doc/bind-dirs) for instruction how to easily -modify arbitrary system file in AppVM and have those changes persistent. +Also take a look at [bind-dirs](/doc/bind-dirs) for instructions on +how to easily modify arbitrary system files in AppVM and have those changes persist. GUI and audio configuration in dom0 =================================== diff --git a/configuration/managing-vm-kernel.md b/configuration/managing-vm-kernel.md index 6166337b..39d2eb05 100644 --- a/configuration/managing-vm-kernel.md +++ b/configuration/managing-vm-kernel.md @@ -227,7 +227,7 @@ sudo qubes-dom0-update grub2-xen ### Installing kernel in Fedora VM In Fedora based VM, you need to install `qubes-kernel-vm-support` package. This -package include required additional kernel module and initramfs addition +package includes required additional kernel module and initramfs addition required to start Qubes VM (for details see [template implementation](/doc/template-implementation/)). Additionally you need some GRUB tools to create its configuration. Note: you don't need actual @@ -240,7 +240,7 @@ sudo yum install qubes-kernel-vm-support grub2-tools Then install whatever kernel you want. If you are using distribution kernel package (`kernel` package), initramfs and kernel module should be handled automatically, but you need to ensure you have `kernel-devel` package for the -same kernel version installed. If you are using manually build kernel, you need +same kernel version installed. If you are using a manually built kernel, you need to handle this on your own. Take a look at `dkms` and `dracut` documentation. Especially `dkms autoinstall` command may be useful. @@ -265,7 +265,7 @@ start kernel configured within VM. ### Installing kernel in Debian VM In Debian based VM, you need to install `qubes-kernel-vm-support` package. This -package include required additional kernel module and initramfs addition +package includes required additional kernel module and initramfs addition required to start Qubes VM (for details see [template implementation](/doc/template-implementation/)). Additionally you need some GRUB tools to create its configuration. Note: you don't need actual diff --git a/configuration/multiboot.md b/configuration/multiboot.md index 3cba4ec7..d33152a5 100644 --- a/configuration/multiboot.md +++ b/configuration/multiboot.md @@ -178,7 +178,7 @@ If you install Qubes without making any backups beforehand, don't worry. If you didn't overwrite the original partitions, then it is usually possible to recover your old systems relatively easily, as described above. -If you decided to use a shared /boot and *dont* have backups of your previous +If you decided to use a shared /boot and *don't* have backups of your previous grub config, it is quite easy to fix this. This example may help. diff --git a/debugging/vm-interface.md b/debugging/vm-interface.md index bfb19458..507909db 100644 --- a/debugging/vm-interface.md +++ b/debugging/vm-interface.md @@ -32,7 +32,7 @@ QubesDB - `none` - none - `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` - `/qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet). -- `/qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0` +- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0` - `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using qvm-service command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService) - `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" - `/qubes-ip - IP address for this VM (only when VM has netvm set) @@ -50,7 +50,7 @@ QubesDB QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in separate key for each target VM. Entries: -- `/qubes-iptables` - control entry - dom0 writing `reload` here signal `qubes-firewall` service to reload rules +- `/qubes-iptables` - control entry - dom0 writing `reload` here signals `qubes-firewall` service to reload rules - `/qubes-iptables-header` - rules not related to any particular VM, should be applied before domains rules - `/qubes-iptables-domainrules/NNN` - rules for domain `NNN` (arbitrary number) in `iptables-save` format. Rules are self-contained - fill `FORWARD` iptables @@ -59,7 +59,7 @@ final default action (`DROP`/`ACCEPT`) VM after applying rules may signal some error, writing a message to `/qubes-iptables-error` key. This does not exclude any other way of -communicating problem - like a popup. +communicating problems - like a popup. #### Firewall rules in 4.x #### @@ -84,7 +84,7 @@ by space. Order of those pairs in a single rule is undefined. QubesDB enforces a limit on a single entry length - 3072 bytes. Possible options for a single rule: - - `action`, values: `accept`, `drop`; this is present it every rule + - `action`, values: `accept`, `drop`; this is present in every rule - `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24` - `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3` - `dstname`, value: DNS hostname of destination host @@ -100,7 +100,7 @@ Possible options for a single rule: Rule matches only when all predicates matches. Only one of `dst4`, `dst6`, `dstname`, `specialtarget` can be used in a single rule. -If tool applying firewall encounter any parse error (unknown option, invalid +If tool applying firewall encounters any parse error (unknown option, invalid value etc), it should drop all the traffic coming from that `SOURCE_IP`, regardless of properly parsed rules. @@ -117,7 +117,7 @@ Example valid rules: - `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. - Qubes 4.0+ format: used memory size in the VM, in kbytes -- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries: +- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries: - `desc` - device description (ASCII text) - `size` - device size in bytes - `mode` - default connection mode; `r` for read-only, `w` for read-write @@ -130,7 +130,7 @@ Qubes RPC Services called by dom0 to provide some VM configuration: -- `qubes.SetMonitorLayout` - provide list of monitors, one in a line, each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional) +- `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional) - `qubes.WaitForSession` - called to wait for full VM startup - `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here - `qubes.GetImageRGBA` - receive image/application icon. Protocol: @@ -172,7 +172,7 @@ Other Qrexec services installed by default: - `qubes.Restore` - retrieve Qubes backup. The service receives backup location entered by the user (one line, terminated by '\n'), then should output backup archive in [qfile format](/doc/qfilecopy/) (core-agent-linux component contains - `tar2qfile` utility to do the conversion + `tar2qfile` utility to do the conversion) - `qubes.SelectDirectory`, `qubes.SelectFile` - services which should show file/directory selection dialog and return (to stdout) a single line containing selected path, or nothing in the case of cancellation @@ -199,7 +199,7 @@ abstraction. This will change in the future. Those tools are: - `gpk-update-viewer` - called by Qubes Manager to display available updates in a TemplateVM - `systemctl start qubes-update-check.timer` (and similarly stop) - called when enabling/disabling updates checking in given VM (`qubes-update-check` [qvm-service](/doc/qubes-service/)) -Additionally automatic tests extensively calls various commands directly in VMs. We do not plan to change that. +Additionally automatic tests extensively call various commands directly in VMs. We do not plan to change that. GUI protocol ------------ diff --git a/security/yubi-key.md b/security/yubi-key.md index 77f512a3..1bba22ba 100644 --- a/security/yubi-key.md +++ b/security/yubi-key.md @@ -26,7 +26,7 @@ applications (it will deny further authentications if you try). Contrary to instruction there, currently there is no binary packages in Qubes repository and you need to compile it yourself. This might change in the future. -Challenge-reponse mode +Challenge-response mode ---------------------- In this mode, your YubiKey will generate response based on secret key, and diff --git a/services/qmemman.md b/services/qmemman.md index 471acb95..356ddbf5 100644 --- a/services/qmemman.md +++ b/services/qmemman.md @@ -23,7 +23,7 @@ The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM Therefore, in Qubes another solution is used. There is the *qmemman* dom0 daemon. All VMs report their memory usage (via xenstore) to *qmemman*, and it makes decisions on whether to balance memory across domains. The actual mechanism to add/remove memory from a domain (*xc.domain\_set\_target\_mem*) is already supported by both PV Linux guests and Windows guests (the latter via PV drivers). -Similarly, when there is need for Xen free memory (for instance, in order to create a new VM), traditionally the memory is obtained from dom0 only. When *qmemman* is running, it offers interface to obtain memory from all domains. +Similarly, when there is need for Xen free memory (for instance, in order to create a new VM), traditionally the memory is obtained from dom0 only. When *qmemman* is running, it offers an interface to obtain memory from all domains. To sum up, *qmemman* pros and cons. Pros: @@ -34,7 +34,7 @@ To sum up, *qmemman* pros and cons. Pros: Cons: - the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality -- *qmemman* is notified by a VM about memory usage change not more often than 10 times per seconds (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements +- *qmemman* is notified by a VM about memory usage change not more often than 10 times per second (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements - it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory Interface diff --git a/system/gui.md b/system/gui.md index ceee7e42..dadfa01a 100644 --- a/system/gui.md +++ b/system/gui.md @@ -73,7 +73,7 @@ Security markers on dom0 windows It is important that user knows which AppVM a given window belongs to. This prevents a rogue AppVM from painting a window pretending to belong to other AppVM or dom0 and trying to steal, for example, passwords. -In Qubes, a custom window decorator is used that paints a colourful frame (the colour is determined during AppVM creation) around decorated windows. Additionally, the window title always starts with **[name of the AppVM]**. If a window has a *override_redirect* attribute, meaning that it should not be treated by a window manager (typical case is menu windows), *qubes_guid* draws a two-pixel colourful frame around it manually. +In Qubes, a custom window decorator is used that paints a colourful frame (the colour is determined during AppVM creation) around decorated windows. Additionally, the window title always starts with **[name of the AppVM]**. If a window has an *override_redirect* attribute, meaning that it should not be treated by a window manager (typical case is menu windows), *qubes_guid* draws a two-pixel colourful frame around it manually. Clipboard sharing implementation -------------------------------- @@ -81,7 +81,7 @@ Clipboard sharing implementation Certainly, it would be insecure to allow AppVM to read/write the clipboards of other AppVMs unconditionally. Therefore, the following mechanism is used: -- there is a "qubes clipboard" in dom0 - its contents is stored in a regular file in dom0. +- there is a "qubes clipboard" in dom0 - its contents are 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 local clipboard, and then user can paste its contents to local applications normally. diff --git a/system/storage-pools.md b/system/storage-pools.md index 250ec1c2..c4129208 100644 --- a/system/storage-pools.md +++ b/system/storage-pools.md @@ -7,31 +7,31 @@ permalink: /doc/storage-pools/ Storage Pools in Qubes ====================== -Qubes OS R 3.2 introduced the concept of storage drivers & pools. This feature +Qubes OS R3.2 introduced the concept of storage drivers and pools. This feature was a first step towards a saner storage API, which is heavily rewritten in R4. A storage driver provides a way to store VM images in a Qubes OS system. Currently, the default driver is `xen` which is the default way of storing volume images as files in a directory tree like `/var/lib/qubes/`. -A pool storage driver can be identified either by the driver name with the +A storage pool driver can be identified either by the driver name with the `driver` key or by the class name like this: `class=qubes.storage.xen.XenStorage`. Because R3.2 doesn't use Python `setup_hooks`, to actually use a short driver name for a custom storage driver, you have to patch `qubes-core-admin`. You can use the `class` config key instead, when your class is accessible by `import` in Python. -A pool (in R3.2) is a configuration information which can be referenced when +A pool (in R3.2) is configuration information which can be referenced when creating a new VM. Each pool is saved in `storage.conf`. It has a name, a storage driver and some driver specific configuration attached. -When installed, the system has, as you can see from the content of +When installed, the system has, as you can see from the contents of `/etc/qubes/storage.conf`, a pool named `default`. It uses the driver `xen`. The default pool is special in R3.2. It will add `dir_path=/var/lib/qubes` configuration value from `defaults[pool_config]`, if not overwritten. Currently the only supported driver out of the box is `xen`. The benefit of -pools (besides that you can write an own storage driver e.g. for Btrfs) in R3.2 +pools (besides that you can write your own storage driver e.g. for Btrfs) in R3.2 is that you can store your domains in multiple places. You can add a pool to `storage.conf` like this: @@ -42,7 +42,7 @@ driver=xen dir_path=/opt/qubes-vm ``` -Now, when creating a new VM on the command-line, a you may pass the `-Pfoo` +Now, when creating a new VM on the command-line, you may pass the `-Pfoo` argument to `qvm-create` to have the VM images stored in pool `foo`. See also `qvm-create --help`.