diff --git a/developer/system/gui.md b/developer/system/gui.md index dfd04801..6de31dc7 100644 --- a/developer/system/gui.md +++ b/developer/system/gui.md @@ -90,9 +90,10 @@ 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 are stored in a regular file in dom0. +- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0 as `/run/qubes/qubes-clipboard.bin`. - if the 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. - the 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. +- a supplementary JSON metadata file will be saved as `/run/qubes/qubes-clipboard.bin.metadata` on global clipboard copy or paste actions. Explanation of each field is available in `xside.h` header file of `qubes-guid` under `clipboard_metadata` structure. While the output from `qubes-guid` is fully JSON compatible, the `qubes-guid` parser is limited. It expects line breaks after each key-value pair and only one key-value pair per line. Opening and closing curly braces should be on their own lines. There should be no leading white-space. This way, the user can quickly copy clipboards between AppVMs. This action is fully controlled by the user, it cannot be triggered/forced by any AppVM. diff --git a/developer/system/template-implementation.md b/developer/system/template-implementation.md index 4feb91fb..1bd4dd2b 100644 --- a/developer/system/template-implementation.md +++ b/developer/system/template-implementation.md @@ -73,19 +73,9 @@ When TemplateVM is stopped, the xen script moves root-cow.img to root-cow.img.ol #### Rollback template changes -There is possibility to rollback last template changes. Saved root-cow.img.old contains all changes made during last TemplateVM run. Rolling back changes is done by reverting this "binary patch". +There is possibility to rollback last template changes. Using the automatic snapshot that is normally saved every time the template is shutdown. -This is done using snapshot-merge device-mapper target (available from 2.6.34 kernel). It requires that no other snapshot device uses underlying block devices (root.img, root-cow.img via loop device). Because of this all AppVMs based on this template must be halted during this operation. - -Steps performed by **qvm-revert-template-changes**: - -1. Ensure that no other VMs uses this template. -2. Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*). -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 at the moment). -7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file). +Refer to volume backup and revert [documentation](/doc/volume-backup-revert) for more information. ### Snapshot device in AppVM diff --git a/introduction/intro.md b/introduction/intro.md index 142d4095..a9089ea6 100644 --- a/introduction/intro.md +++ b/introduction/intro.md @@ -19,7 +19,7 @@ title: Introduction

Qubes OS is a free and open-source, security-oriented operating system for single-user desktop computing. Qubes OS leverages - + Xen-based virtualization to allow for the creation and management of isolated compartments called qubes.

diff --git a/introduction/issue-tracking.md b/introduction/issue-tracking.md index 3296210e..5326e698 100644 --- a/introduction/issue-tracking.md +++ b/introduction/issue-tracking.md @@ -41,7 +41,7 @@ Great! Thank you for taking the time and effort to help improve Qubes! To ensure 1. Carefully read our issue tracking [guidelines](#guidelines). If your issue would violate any of the guidelines, **stop**. Please do not submit it. 2. [Search through the existing issues](#search-tips), both open and closed, to see if your issue already exists. If it does, **stop**. [Do not open a duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues) Instead, comment on the existing issue. 3. Go [here](https://github.com/QubesOS/qubes-issues/issues/new/choose). - 4. Select the [type](#type) of issue you want to open. + 4. Select the [type](#types) of issue you want to open. 5. Enter a descriptive title. 6. Do not delete the provided issue template. Fill out every applicable section. 7. Make sure to mention any relevant documentation and other issues you've already seen. We don't know what you've seen unless you tell us. If you don't list it, we'll assume you haven't seen it. @@ -51,36 +51,36 @@ Great! Thank you for taking the time and effort to help improve Qubes! To ensure Eventually, your issue may be closed. See [how issues get closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, why, and how this occurs. -## Labels and projects +## How issues are organized -Labels and projects are features of GitHub's issue tracking system that we use to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized. +Issues can have several different properties and be organized in various ways. This section explains how we use labels, issue types, projects, and other features of GitHub's issue tracking system in order to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized. ### Labels -When an issue is first created, certain [labels](https://github.com/QubesOS/qubes-issues/labels) may automatically be applied to it based on the type of issue the reporter selected. For example, if someone selects the "Bug report" template, then the `T: bug` label will automatically be applied to that issue. After that, only Qubes team members have permission to modify labels. Many labels have descriptions on them that can be viewed by hovering over them or on the [list of labels](https://github.com/QubesOS/qubes-issues/labels). Let's go over some of the most important ones. - -#### Type - -There are three issue **types**: `T: bug`, `T: enhancement`, and `T: task`. - -- `T: bug` --- Type: bug report. A problem or defect resulting in unintended behavior in something that exists. -- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist **or** improvement of existing functionality. -- `T: task` --- Type: task. An action item that is neither a bug nor an enhancement. - -Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under neither `T: bug` nor `T: enhancement`. +When an issue is first created, it will receive the `P: default` (i.e., default priority) [label](https://github.com/QubesOS/qubes-issues/labels) automatically. After an issue has been created, only Qubes team members have permission to modify labels. Many labels have descriptions on them that can be viewed by hovering over them or on the [list of labels](https://github.com/QubesOS/qubes-issues/labels). Let's go over some of the most important ones. #### Priority -There are several issue **priority** levels ranging from `P: minor` to `P: blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full list). Every open issue should have **exactly one** priority. An open issue should not have more than one priority, and it should not lack a priority entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how the developers use these priorities. +There are several issue **priority** levels ranging from `P: minor` to `P: blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full list). Every open issue should have exactly one priority. An open issue should not have more than one priority, and it should not lack a priority entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how the developers use these priorities. #### Component -There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=C%3A) for the full list). Every open issue should have **at least one** component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`. +There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=C%3A) for the full list). Every open issue should have at least one component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`. #### Affected release A label of the form `affects-` indicates that an issue affects the corresponding Qubes OS release. An issue can have more than one of these labels if it affects multiple releases. +### Types + +There are three issue [types](https://docs.github.com/en/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization): Bug, Feature, and Task. + +- **Bug** --- An unexpected problem or behavior +- **Feature** --- A request, idea, or new functionality +- **Task** --- A specific piece of work + +Every open issue should have exactly one type. **Bug** reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then that issue should instead be a **Feature** request. If something already exists, but you think it could be improved in some way, that also qualifies as a **Feature** request. The **Task** type is for issues that are actionable but that fall under neither the **Bug** nor **Feature** types. + ### Projects According to GitHub, a [project](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) is "an adaptable spreadsheet, task-board, and road map that integrates with your issues and pull requests on GitHub to help you plan and track your work effectively." The issue tracker has several [projects](https://github.com/QubesOS/qubes-issues/projects). Github projects allows more detailed issue states, and also attaching more metadata to issues. They also allow more focused view. @@ -89,21 +89,11 @@ There is a special project in Qubes OS project: the [Current team tasks project] ### Meta-issues -A meta-issue is an issue that serves to collect and organize a group of other issues. We use meta-issues when we need a way to track work on specific features. We cannot use [projects](#projects) for this, because we already use a project for tracking the work of the Qubes team as a whole, and projects cannot contain milestones or other projects. +A meta-issue is an issue that serves primarily to collect and organize a group of other issues. This group of other issues typically exists in a hierarchy of [sub-issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues), usually with the meta-issue at the top. (For example, we use meta-issues when we need a way to track work on specific features. We cannot use [projects](#projects) for this, because we already use a project for tracking the work of the Qubes team as a whole, and projects cannot contain milestones or other projects.) -Meta-issues must abide by the following rules: +Meta-issues should 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. -- 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. - -- 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. - -- 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. - -- Meta-issues must have clear, concrete, and actionable criteria for when they will be closed. Meta-issues should never be "open-ended" or expected to stay open indefinitely. If this ever becomes unclear, the meta-issue should be closed until it becomes clear. +In addition, meta-issues should have clear, concrete, and actionable criteria for when they will be closed. Meta-issues should never be "open-ended" or expected to stay open indefinitely. If this ever becomes unclear, the meta-issue should be closed until it becomes clear. ## Search tips diff --git a/user/advanced-topics/config-files.md b/user/advanced-topics/config-files.md index 3ffdfd55..37ee7c03 100644 --- a/user/advanced-topics/config-files.md +++ b/user/advanced-topics/config-files.md @@ -11,8 +11,7 @@ ref: 180 title: Config files --- -Qubes-specific VM config files ------------------------------- +## Qubes-specific VM config files These files are placed in `/rw`, which survives a VM restart. That way, they can be used to customize a single VM instead of all VMs based on the same template. @@ -76,8 +75,7 @@ Note that scripts need to be executable (`chmod +x`) to be used. Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an app qube and have those changes persist. -GUI and audio configuration in dom0 ------------------------------------ +## GUI and audio configuration in dom0 The GUI configuration file `/etc/qubes/guid.conf` in one of a few not managed by `qubes-prefs` or the Qubes Manager tool. Sample config (included in default installation): diff --git a/user/advanced-topics/resize-disk-image.md b/user/advanced-topics/resize-disk-image.md index b7805bd2..c06eaa1b 100644 --- a/user/advanced-topics/resize-disk-image.md +++ b/user/advanced-topics/resize-disk-image.md @@ -32,7 +32,8 @@ In most cases, the GUI tool Qube Settings (available for every qube from the Sta ![vm-settings-disk-image.png](/attachment/doc/r4.0-vm-settings-disk-image.png) -In case of standalone qubes and templates, just change the Disk Storage settings above. +In case of standalone qubes and templates, just change the Disk Storage settings above. If the standalone fails to start, temporarily increase the `qrexec_timeout`, [as described here](https://github.com/QubesOS/qubes-issues/issues/9251#issuecomment-2121596415). + In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/doc/getting-started/), and so it must be changed in the template settings. If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below. See also the OS-specific follow-up instructions below. diff --git a/user/advanced-topics/volume-backup-revert.md b/user/advanced-topics/volume-backup-revert.md index 85bb4062..f06f1ca8 100644 --- a/user/advanced-topics/volume-backup-revert.md +++ b/user/advanced-topics/volume-backup-revert.md @@ -31,7 +31,7 @@ qvm-volume info vmname:private The output of the above command will also display the "Available revisions (for revert)" at the bottom. For a very large volume in a small pool, -revisions_to_keep should probably be set to the minimum value of 1 to minimize +revisions_to_keep should probably be set to the maximum value of 1 to minimize the possibility of the pool being accidentally filled up by snapshots. For a smaller volume for which you would like to have the future option of reverting, revisions_to_keep should probably be set to at least 2. To set diff --git a/user/downloading-installing-upgrading/installation-guide.md b/user/downloading-installing-upgrading/installation-guide.md index c38cbc35..a4684667 100644 --- a/user/downloading-installing-upgrading/installation-guide.md +++ b/user/downloading-installing-upgrading/installation-guide.md @@ -43,7 +43,7 @@ Even on supported hardware, you must ensure that [IOMMU-based virtualization](ht ### Copying the ISO onto the installation medium -Pick the most secure existing computer and OS you have available for downloading and copying the Qubes ISO onto the installation medium. [Download](/downloads/) a Qubes ISO. +Pick the most secure existing computer and OS you have available for downloading and copying the Qubes ISO onto the installation medium. [Download](/downloads/) a Qubes ISO. If your Internet connection is unstable and the download is interrupted, you could resume the partial download with `wget --continue` in case you are currently using wget for downloading or use a download-manager with resume capability. Alternatively you can download installation ISO via BitTorrent that sometimes enables higher download speeds and more reliable downloads of large files.