diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index f125533f..5f1581bd 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -46,7 +46,7 @@ Don't forget to include the public PGP key you use to sign your tags. #### Prepare fresh version of kernel sources, with Qubes-specific patches applied -In qubes-builder/artifacts/sources/linux-kernel: +In `qubes-builder/artifacts/sources/linux-kernel`: ~~~ make prep @@ -65,7 +65,7 @@ drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj #### Go to the kernel tree and update the version -In qubes-builder/artifacts/sources/linux-kernel: +In `qubes-builder/artifacts/sources/linux-kernel`: ~~~ cd kernel-3.4.18/linux-3.4.18 @@ -73,14 +73,14 @@ cd kernel-3.4.18/linux-3.4.18 #### Changing the config -In kernel-3.4.18/linux-3.4.18: +In `kernel-3.4.18/linux-3.4.18`: ~~~ cp ../../config .config make oldconfig ~~~ -Now change the configuration. For example, in kernel-3.4.18/linux-3.4.18: +Now change the configuration. For example, in `kernel-3.4.18/linux-3.4.18`: ~~~ make menuconfig @@ -139,7 +139,7 @@ RPMs will appear in 1. `./qb package diff` - show uncommitted changes 2. ` ./qb repository check-release-status-for-component` and -`./qb repository check-release-status-for-template`- show version of each +`./qb repository check-release-status-for-template` - show version of each component/template (based on git tags) 3. `./qb package sign` - sign built packages 4. `./qb package publish` and `./qb package upload` - publish signed packages diff --git a/developer/building/qubes-builder-v2.md b/developer/building/qubes-builder-v2.md index 1210910b..2ad60e9f 100644 --- a/developer/building/qubes-builder-v2.md +++ b/developer/building/qubes-builder-v2.md @@ -39,18 +39,20 @@ if you don't know which executor to use, use docker. 2. Installing dependencies - If you want to use an app qube for developing, install dependencies in the template. + - If you want to use an app qube for developing, install dependencies in the template. If you are using a standalone, install them in the qube itself. Dependencies are specified in `dependencies-*. txt` files in the main builder directory, and you can install them easily in the following ways: 1. for Fedora, use: + ```shell $ sudo dnf install $(cat dependencies-fedora.txt) $ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split ``` 2. for Debian (note: some Debian packages require Debian version 13 or later), use: + ```shell $ sudo apt install $(cat dependencies-debian.txt) $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split @@ -60,6 +62,7 @@ if you don't know which executor to use, use docker. (re)start the development qube. 3. Clone the qubes-builder v2 repository into a location of your choice: + ```shell git clone https://github.com/QubesOS/qubes-builderv2 cd qubes-builderv2/ @@ -68,12 +71,14 @@ if you don't know which executor to use, use docker. 4. If you haven't previously used docker in the current qube, you need to set up some permissions. In particular, the user has to be added to the `docker` group: + ```shell $ sudo usermod -aG docker user ``` Next, **restart the qube**. 5. Finally, you need to generate a docker image: + ```shell $ tools/generate-container-image.sh docker ``` @@ -94,7 +99,7 @@ You can use one of the sample files from the `example-configs/` directory; for a more readable `builder.yml`, you can also include one of the files from that directory in your `builder.yml`. An example `builder.yml` is: -```yaml +``` # include configuration relevant for the current release include: - example-configs/qubes-os-r4.2.yml @@ -120,7 +125,6 @@ executor: type: docker options: image: "qubes-builder-fedora:latest" - ``` diff --git a/developer/code/code-signing.md b/developer/code/code-signing.md index c94b9e1b..8074840d 100644 --- a/developer/code/code-signing.md +++ b/developer/code/code-signing.md @@ -144,9 +144,11 @@ Although GitHub adds a little green `Verified` button next to the commit, the [s 1. Is the commit signed? If the commit is not signed, you can see the message + > policy/qubesos/code-signing — No signature found 2. If the commit is signed, the key is downloaded from a GPG key server. If you can see the following error message, please check if you have uploaded the key to a key server. + > policy/qubesos/code-signing — Unable to verify (no valid key found) ### No Signature Found diff --git a/developer/code/source-code.md b/developer/code/source-code.md index 85e5cf13..83173e6c 100644 --- a/developer/code/source-code.md +++ b/developer/code/source-code.md @@ -60,6 +60,7 @@ method you choose, you must [sign your code](/doc/code-signing/) before it can b * **Preferred**: Use GitHub's [fork & pull requests](https://guides.github.com/activities/forking/). + Opening a pull request on GitHub greatly eases the code review and tracking process. In addition, especially for bigger changes, it's a good idea to send a message to the [qubes-devel mailing list](/support/#qubes-devel) in order to notify people who diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index 1f72ede8..51870d97 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -267,11 +267,13 @@ It feeds off of the openQA test data to make graph plots. Here is an example: ![openqa-investigator-splitgpg-example.png](/attachment/doc/openqa-investigator-splitgpg-example.png) Some outputs: + - plot by tests - plot by errors - markdown Some filters: + - filter by error - filter by test name diff --git a/developer/general/developing-gui-applications.md b/developer/general/developing-gui-applications.md index 1ff0387c..19e60a1c 100644 --- a/developer/general/developing-gui-applications.md +++ b/developer/general/developing-gui-applications.md @@ -59,7 +59,7 @@ If error should be thrown, you need to provide the error code and name, for exam b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00' ``` -For details of particular calls, you can use [Extending the mock Qubes object]. +For details of particular calls, you can use [Extending the mock Qubes object](#extending-the-mock-qubes-object). ## Available mocks diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index a2990cd9..f1044aed 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -174,45 +174,6 @@ If applicable, links to more information or discussions **Mentor**: [Frédéric Pierret](/team/) - ### Qubes Live USB @@ -252,26 +213,6 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552), **Mentor**: [Frédéric Pierret](/team/) - - ### LogVM(s) **Project**: LogVM(s) @@ -461,44 +402,6 @@ Some related discussion: **Mentor**: [Marek Marczykowski-Górecki](/team/) - - ### Android development in Qubes **Project**: Research running Android in Qubes VM (probably HVM) and connecting it to Android Studio @@ -538,12 +441,14 @@ Since the Admin API is continuously growing and changing, continuous security as A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of these assessments. **Expected results**: + - fully automated & extensible Fuzzer for parts of the Admin API - user & developer documentation **Difficulty**: medium **Prerequisites**: + - basic Python understanding - some knowledge about fuzzing & existing fuzzing frameworks (e.g. [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/qubes-os)) - a hacker's curiosity @@ -560,6 +465,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of **Brief explanation**: Since recently, Xen supports "unified EFI boot" which allows to sign not only Xen binary itself, but also dom0 kernel and their parameters. While the base technology is there, enabling it is a painful and complex process. The goal of this project is to integrate configuration of this feature into Qubes, automating as much as possible. See discussion in [issue #4371](https://github.com/QubesOS/qubes-issues/issues/4371) **Expected results**: + - a tool to prepare relevant boot files for unified Xen EFI boot - this includes collecting Xen, dom0 kernel, initramfs, config file, and possibly few more (ucode update?); the tool should then sign the file with user provided key (preferably propose to generate it too) - integrate it with updates mechanism, so new Xen or dom0 kernel will be picked up automatically - include a fallback configuration that can be used for troubleshooting (main unified Xen EFI intentionally does not allow to manipulate parameters at boot time) @@ -567,6 +473,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of **Difficulty**: hard **Knowledge prerequisite**: + - basic understanding of Secure Boot - Bash and Python scripting @@ -586,6 +493,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of **Difficulty**: medium **Knowledge prerequisite**: + - Python scripting - Basic knowledge of Linux system services management (systemd, syslog etc) diff --git a/developer/general/gsod.md b/developer/general/gsod.md index 0ca6b7af..ad714e50 100644 --- a/developer/general/gsod.md +++ b/developer/general/gsod.md @@ -58,9 +58,9 @@ Qubes OS regularly participates in Google Summer of Code and Google Season of Do ## Past Projects -You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/). +You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://web.archive.org/web/20200928002746/https://refre.ch/report-qubesos/). -You can view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733). +You can view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://web.archive.org/web/20210723170547/https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733). You can view the results of the project we had in 2023 [here](https://www.youtube.com/playlist?list=PLjwSYc73nX6aHcpqub-6lzJbL0vhLleTB). diff --git a/developer/releases/2_0/release-notes.md b/developer/releases/2_0/release-notes.md index e0a5751d..a428a121 100644 --- a/developer/releases/2_0/release-notes.md +++ b/developer/releases/2_0/release-notes.md @@ -68,7 +68,7 @@ Note: if the user has custom Template VMs (i.e. other than the default template, #### From Qubes R1 to R2 beta1 -If you're already running Qubes Release 1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). This procedure is described [here?](/doc/upgrade-to-r2/). +If you're already running Qubes Release 1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). This procedure is described [here](/doc/upgrade-to-r2/). #### From Qubes R1 or R2 Beta 1 to R2 beta2 diff --git a/developer/releases/4_0/release-notes.md b/developer/releases/4_0/release-notes.md index b80a1959..1bed1302 100644 --- a/developer/releases/4_0/release-notes.md +++ b/developer/releases/4_0/release-notes.md @@ -9,7 +9,7 @@ title: Qubes R4.0 release notes New features since 3.2 ---------------------- -* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/) +* Core management scripts rewrite with better structure and extensibility, [current API documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/) and the documentation API index as a [webarchive](https://web.archive.org/web/20230128102821/https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/) * [Admin API](/news/2017/06/27/qubes-admin-api/) allowing strictly controlled managing from non-dom0 * All `qvm-*` command-line tools rewritten, some options have changed * Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM diff --git a/developer/releases/4_2/release-notes.md b/developer/releases/4_2/release-notes.md index 6377844b..044a022f 100644 --- a/developer/releases/4_2/release-notes.md +++ b/developer/releases/4_2/release-notes.md @@ -57,17 +57,17 @@ We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after - Qubes 4.2.2 includes a fix for [#8332: File-copy qrexec service is overly restrictive](https://github.com/QubesOS/qubes-issues/issues/8332). As explained in the issue comments, we introduced a change in Qubes 4.2.0 that caused inter-qube file-copy/move actions to reject filenames containing, e.g., non-Latin characters and certain symbols. The rationale for this change was to mitigate the security risks associated with unusual unicode characters and invalid encoding in filenames, which some software might handle in an unsafe manner and which might cause confusion for users. Such a change represents a trade-off between security and usability. - After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place. + - After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place. - Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service. + - Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service. - Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules: + - Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules: - ``` - qubes.Filecopy +allow-all-names @anyvm @anyvm deny - ``` + ``` + qubes.Filecopy +allow-all-names @anyvm @anyvm deny + ``` - For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc). + - For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc). - Beginning with Qubes 4.2, the recommended way to update Qubes OS via the command line has changed. Salt is no longer the preferred method, though it is still supported. Instead, `qubes-dom0-update` is recommended for updating dom0, and `qubes-vm-update` is recommended for updating templates and standalones. (The recommended way to update via the GUI has not changed. The Qubes Update tool is still the preferred method.) For more information, see [How to update](/doc/how-to-update/). diff --git a/developer/releases/version-scheme.md b/developer/releases/version-scheme.md index a96f9ca6..f241a70a 100644 --- a/developer/releases/version-scheme.md +++ b/developer/releases/version-scheme.md @@ -71,7 +71,7 @@ When enough progress has been made, we announce the first stable release, e.g. `3.0.0`. This is not only a version but an actual release. It is considered stable, and we commit to supporting it according to our [support schedule](/doc/supported-releases/). Core components are branched at this -moment, and bug fixes are backported from the master branch. Please see [help, +moment, and bug fixes are backported from the main branch. Please see [help, support, mailing lists, and forum](/support/) for places to ask questions about stable releases. No major features or interface incompatibilities are to be included in this release. We release bug fixes as patch releases (`3.0.1`, @@ -173,7 +173,7 @@ We mark each component version in the repository by tag containing At the release of some release we create branches named like `release2`. Only bug fixes and compatible improvements are backported to these branches. These -branches should compile. All new development is done in `master` branch. This +branches should compile. All new development is done in `main` branch. This branch is totally unsupported and may not even compile depending on maintainer of repository. diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md index 0087bcaf..f05ee780 100644 --- a/developer/services/admin-api.md +++ b/developer/services/admin-api.md @@ -62,95 +62,100 @@ yet documented. The API should be implemented as a set of qrexec calls. This is to make it easy to set the policy using current mechanism. -| call | dest | argument | inside | return | note | -| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- | -| `admin.vmclass.List` | `dom0` | - | - | `\n` | -| `admin.vm.List` | `dom0|` | - | - | ` class= state=\n` | -| `admin.vm.Create.` | `dom0` | template | `name= label=