diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index 5f1581bd..dd72699a 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -12,41 +12,42 @@ title: Development workflow A workflow for developing Qubes OS+ -To begin, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide -assumes you're using qubes-builder v2 to build Qubes. +First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide +assumes you're using qubes-builder to build Qubes. ## Repositories and committing Code -Qubes source code is split into many git repos. These are all contained in the -`artifacts/sources` directory under qubes-builder. Subdirectories there are -separate components, stored in separate git repositories. +Qubes is split into a bunch of git repos. These are all contained in the +`qubes-src` directory under qubes-builder. Subdirectories there are separate +components, stored in separate git repositories. The best way to write and contribute code is to create a git repo somewhere -(e.g., GitHub) for the repo you are interested in editing (e.g., +(e.g., github) for the repo you are interested in editing (e.g., `qubes-manager`, `core-agent-linux`, etc). To integrate your repo with the rest of Qubes, cd to the repo directory and add your repository as a remote in git **Example:** ~~~ -$ cd qubes-builder/artifacts/sources/qubes-manager -$ git remote add abel git@GitHub.com:abeluck/qubes-manager.git +$ cd qubes-builder/qubes-src/qubes-manager +$ git remote add abel git@github.com:abeluck/qubes-manager.git ~~~ You can then proceed to easily develop in your own branches, pull in new -commits from the dev branches, merge them, and eventually push to your own repo. +commits from the dev branches, merge them, and eventually push to your own repo +on github. When you are ready to submit your changes to Qubes to be merged, push your changes, then create a signed git tag (using `git tag -s`). Finally, send a -letter to the Qubes listserv describing the changes, and including a link to -your repository. If you are using GitHub you can instead create a pull request. -Don't forget to include the public PGP key you use to sign your tags. +letter to the Qubes listserv describing the changes and including the link to +your repository. You can also create pull request on github. Don't forget to +include your public PGP key you use to sign your tags. ### Kernel-specific notes #### Prepare fresh version of kernel sources, with Qubes-specific patches applied -In `qubes-builder/artifacts/sources/linux-kernel`: +In qubes-builder/qubes-src/linux-kernel: ~~~ make prep @@ -65,7 +66,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/qubes-src/linux-kernel: ~~~ cd kernel-3.4.18/linux-3.4.18 @@ -73,14 +74,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 @@ -116,7 +117,9 @@ vi series.conf #### Building RPMs -Now is a good moment to make sure you have changed the kernel release name in +TODO: Is this step generic for all subsystems? + +Now it is a good moment to make sure you have changed kernel release name in rel file. For example, if you change it to '1debug201211116c' the resulting RPMs will be named 'kernel-3.4.18-1debug20121116c.pvops.qubes.x86\_64.rpm'. This will help @@ -128,23 +131,34 @@ your changes locally. To actually build RPMs, in qubes-builder: ~~~ -./qb -c linux-kernel package fetch prep build +make linux-kernel ~~~ -RPMs will appear in -`artifacts/repository/destination_name/package_name` -(for example `artifacts/repository/host-fc37/linux-kernel-6.6.31-1.1/` +RPMs will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64: -### Useful [QubesBuilder](/doc/qubes-builder-v2/) commands +~~~ +-rw-rw-r-- 1 user user 42996126 Nov 17 04:08 kernel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm +-rw-rw-r-- 1 user user 43001450 Nov 17 05:36 kernel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm +-rw-rw-r-- 1 user user 8940138 Nov 17 04:08 kernel-devel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm +-rw-rw-r-- 1 user user 8937818 Nov 17 05:36 kernel-devel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm +-rw-rw-r-- 1 user user 54490741 Nov 17 04:08 kernel-qubes-vm-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm +-rw-rw-r-- 1 user user 54502117 Nov 17 05:37 kernel-qubes-vm-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm +~~~ -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 - component/template (based on git tags) -3. `./qb package sign` - sign built packages -4. `./qb package publish` and `./qb package upload` - publish signed packages - and upload published - repository +### Useful [QubesBuilder](/doc/qubes-builder/) commands + +1. `make check` - will check if all the code was committed into repository and +if all repository are tagged with signed tag. +2. `make show-vtags` - show version of each component (based on git tags) - +mostly useful just before building ISO. **Note:** this will not show version +for components containing changes since last version tag. +3. `make push` - push change from **all** repositories to git server. You must +set proper remotes (see above) for all repositories first. +4. `make prepare-merge` - fetch changes from remote repositories (can be +specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally) +verify tags and show the changes. This do not merge the changes - there are +left for review as FETCH\_HEAD ref. You can merge them using `git merge +FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them. ## Copying Code to dom0 @@ -283,12 +297,12 @@ if [ "$1" = "tb" ]; then exit $? fi -git remote add $1 git@GitHub.com:$1/qubes-`basename $PWD` +git remote add $1 git@github.com:$1/qubes-`basename $PWD` ~~~ It should be executed from component top level directory. This script takes one argument - remote name. If it is `tb`, then it creates qrexec-based git remote -to `testbuilder` VM. Otherwise it creates remote pointing at GitHub account of +to `testbuilder` VM. Otherwise it creates remote pointing at github account of the same name. In any case it points at repository matching current directory name. @@ -307,7 +321,7 @@ current and current-testing). ### RPM packages - yum repo -In source VM, grab [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in +In source VM, grab [linux-yum](https://github.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in `~/repo-yum-upload` directory) and replace `update_repo.sh` script with: ~~~ @@ -323,7 +337,7 @@ find -type f -name '*.rpm' -delete qrexec-client-vm $VMNAME local.UpdateYum ~~~ -In target VM, setup actual yum repository (also based on [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum), this time +In target VM, setup actual yum repository (also based on [linux-yum](https://github.com/QubesOS/qubes-linux-yum), this time without modifications). You will also need to setup some gpg key for signing packages (it is possible to force yum to install unsigned packages, but it isn't possible for `qubes-dom0-update` tool). Fill `~/.rpmmacros` with @@ -403,7 +417,7 @@ Remember to also import gpg public key using `rpm --import`. Steps are mostly the same as in the case of yum repo. The only details that differ: -- use [linux-deb](https://GitHub.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM +- use [linux-deb](https://github.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://github.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM - use different `update_repo.sh` script in source VM (below) - use `local.UpdateApt` qrexec service in target VM (code below) - in target VM additionally place `update-local-repo.sh` script in repository dir (code below) diff --git a/developer/building/qubes-builder-v2.md b/developer/building/qubes-builder-v2.md deleted file mode 100644 index 2ad60e9f..00000000 --- a/developer/building/qubes-builder-v2.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -lang: en -layout: doc -permalink: /doc/qubes-builder-v2/ -redirect_from: -- /en/doc/qubes-builder-v2/ -- /doc/QubesBuilder2/ -- /wiki/QubesBuilder2/ -ref: 311 -title: Qubes builder v2 ---- - -This is a brief introduction to using Qubes Builder v2 to work with Qubes OS -sources. It will walk you through installing and configuring Builder v2, and -using it to fetch and build Qubes OS packages. - -For details and customization, use [Qubes OS v2 builder documentation](https://github.com/QubesOS/qubes-builderv2/). - -# Overview - -In the second generation of Qubes OS builder, container or disposable qube -isolation is used to perform every stage of the build and release process. -From fetching sources to building, everything is executed inside an isolated -*cage* (either a disposable or a container) using an *executor*. For every -command that needs to perform an action on sources, like cloning and -verifying Git repos, rendering a SPEC file, generating SRPM or Debian -source packages, a new cage is used. Only the signing, publishing, and -uploading stages are executed locally outside a cage. - - -# Setup - -This is a simple setup using a docker executor. This is a good default choice; -if you don't know which executor to use, use docker. - -1. First, decide what qube you are going to use when working with Qubes - Builder v2. It can be an AppVM or a Standalone qube, with some steps - different between the two. - -2. Installing dependencies - - - 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 - ``` - - If you have installed dependencies in the template, close it, and - (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/ - ``` - -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 - ``` - - In an app qube, as `/var/lib/docker` is not persistent by default, you also - need to use [bind-dirs](/doc/bind-dirs/) to avoid repeating this step after reboot, adding - the following to the `/rw/config/qubes-bind-dirs.d/docker.conf` file in - this qube: - - ``` - binds+=( '/var/lib/docker' ) - ``` - -# Configuration - -To use Qubes OS Builder v2, you need to have a `builder.yml` configuration file. -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: - -``` -# include configuration relevant for the current release -include: -- example-configs/qubes-os-r4.2.yml - -# which repository to use to fetch sources -use-qubes-repo: - version: 4.2 - testing: true - -# each package built will have local build number appended to package release -# number. It makes it easier to update in testing environment -increment-devel-versions: true - -# reduce output -debug: false - -# this can be set to true if you do not want sources to be automatically -# fetched from git -skip-git-fetch: false - -# executor configuration -executor: - type: docker - options: - image: "qubes-builder-fedora:latest" -``` - - -# Using Builder v2 - -To fetch sources - in this example, for the `core-admin-client` package, you -can use the following command: - -```shell -$ ./qb -c core-admin-client package fetch -``` - -This will fetch the sources for the listed package and place them in -`artifacts/sources` directory. - -To build a package (from sources in the `artifacts/sources` directory), use: - -```shell -$ ./qb -c core-admin-client package fetch prep build -``` - -or, if you want to build for a specific target (`host-fc37` is a `dom0` -using Fedora 37, `vm-fc40` would be a qube using Fedora 40 etc.), use: - -```shell -$ ./qb -c core-admin-client -d host-fc37 package fetch prep build -``` - -If you want to fetch the entire Qubes OS source use the following: - -```shell -$ ./qb package fetch -``` - -**caution**: some repositories might have additional requirements. You can -disable repositories that are not needed in the `example-configs/*.yml` -file you are using by commenting them out. In particular, `python-fido2`, -`lvm` and `windows`-related repositories have special requirements. - diff --git a/developer/code/code-signing.md b/developer/code/code-signing.md index 8074840d..c94b9e1b 100644 --- a/developer/code/code-signing.md +++ b/developer/code/code-signing.md @@ -144,11 +144,9 @@ 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 83173e6c..85e5cf13 100644 --- a/developer/code/source-code.md +++ b/developer/code/source-code.md @@ -60,7 +60,6 @@ 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 51870d97..38e4aca2 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -132,7 +132,7 @@ Whereas integration tests are mostly stored in the [qubes-core-admin](https://gi To for example run the `qubes-core-admin` unit tests, you currently have to clone at least [qubes-core-admin](https://github.com/QubesOS/qubes-core-admin) and its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec) repository in the branches that you want to test. -The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder-v2/). +The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/). Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests: @@ -267,13 +267,11 @@ 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/debugging/test-bench.md b/developer/debugging/test-bench.md index 66a072c5..ca48a5ea 100644 --- a/developer/debugging/test-bench.md +++ b/developer/debugging/test-bench.md @@ -205,10 +205,9 @@ pushd ${HOME}/builder >/dev/null # the following are needed only if you have sources outside builder #rm -rf qubes-src/core-admin -#qb -c core-admin package fetch +#make COMPONENTS=core-admin get-sources -qb -c core-admin -d host-fc41 prep build -# update your dom0 fedora distribution as appropriate +make core-admin qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm qtb-runtests ``` diff --git a/developer/general/developing-gui-applications.md b/developer/general/developing-gui-applications.md index 19e60a1c..1ff0387c 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](#extending-the-mock-qubes-object). +For details of particular calls, you can use [Extending the mock Qubes object]. ## Available mocks diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index f1044aed..e49d66d9 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -31,7 +31,7 @@ You should start learning the components that you plan on working on before the Coming up with an interesting idea that you can realistically achieve in the time available to you (one summer) is probably the most difficult part. We strongly recommend getting involved in advance of the beginning of GSoC, and we will look favorably on applications from prospective contributors who have already started to act like free and open source developers. -Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder-v2/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer. +Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer. ### Contributor proposal guidelines @@ -174,6 +174,45 @@ If applicable, links to more information or discussions **Mentor**: [Frédéric Pierret](/team/) + ### Qubes Live USB @@ -213,6 +252,26 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552), **Mentor**: [Frédéric Pierret](/team/) + + ### LogVM(s) **Project**: LogVM(s) @@ -363,7 +422,7 @@ for more information and qubes-specific background. **Difficulty**: medium -**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder-v2/) [[2]](https://github.com/QubesOS/qubes-builderv2), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. +**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. **Size of the project**: 350 hours @@ -402,6 +461,44 @@ 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 @@ -441,14 +538,12 @@ 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 @@ -465,7 +560,6 @@ 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) @@ -473,7 +567,6 @@ 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 @@ -493,7 +586,6 @@ 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 ad714e50..0ca6b7af 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://web.archive.org/web/20200928002746/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://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://web.archive.org/web/20210723170547/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://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 a428a121..e0a5751d 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 1bed1302..b80a1959 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, [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/) +* Core management scripts rewrite with better structure and extensibility, [API documentation](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 044a022f..6377844b 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 f241a70a..a96f9ca6 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 main branch. Please see [help, +moment, and bug fixes are backported from the master 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 `main` branch. This +branches should compile. All new development is done in `master` 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 f05ee780..0087bcaf 100644 --- a/developer/services/admin-api.md +++ b/developer/services/admin-api.md @@ -62,100 +62,95 @@ 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=