diff --git a/Guide/src/SUMMARY.md b/Guide/src/SUMMARY.md index ea051dbbca..3ff883227e 100644 --- a/Guide/src/SUMMARY.md +++ b/Guide/src/SUMMARY.md @@ -61,7 +61,9 @@ - [Coding Conventions](./dev_guide/contrib/code.md) - [Save State](./dev_guide/contrib/save-state.md) - [Snapshot Format](./dev_guide/snapshot_format.md) - - [Releases & Code Flow](./dev_guide/contrib/release.md) + - [OpenVMM Release Model and Support](./dev_guide/contrib/openvmm_release.md) + - [Packaging OpenVMM for a Linux Distribution](./dev_guide/contrib/openvmm_packaging.md) + - [OpenHCL Release Management](./dev_guide/contrib/release.md) - [Submitting Changes](./dev_guide/contrib/pr.md) - [Code Review Process](./dev_guide/contrib/code_review.md) - [Guide Updates](./dev_guide/contrib/guide.md) diff --git a/Guide/src/dev_guide/contrib/openvmm_packaging.md b/Guide/src/dev_guide/contrib/openvmm_packaging.md new file mode 100644 index 0000000000..4b79282508 --- /dev/null +++ b/Guide/src/dev_guide/contrib/openvmm_packaging.md @@ -0,0 +1,176 @@ +# Packaging OpenVMM for a Linux Distribution + +This page describes building the `openvmm` binary as a Linux distribution +package, from public source only. It is aimed at downstream packagers (for +example, an RPM or `.deb` maintainer) who build from the official OpenVMM source +release rather than from the in-repo `cargo xflowey` provisioning flow. + +The examples target [Azure Linux](https://github.com/microsoft/azurelinux), but +the requirements generalize to any glibc distribution. + +```admonish note title="See also" +[OpenVMM Release Model and Support](./openvmm_release.md) describes the source +release archive and version identity that a distribution package builds from. +[Crypto Backends](./crypto_backends.md) explains the backend selection that +determines the native dependencies below. +``` + +## What a distribution package builds + +A distribution package builds the host `x86_64-unknown-linux-gnu` target: +dynamically linked against the system glibc and OpenSSL. This differs from the +official prebuilt Linux release archives, which are statically linked `musl` +binaries built through the repository's own provisioning tooling. + +The gnu build deliberately avoids the repository's `.packages/` provisioning +(`cargo xflowey restore-packages`), which fetches prebuilt native libraries a +distribution build cannot consume. A packager instead supplies every native +dependency from distribution packages and overrides the few build settings that +otherwise point into `.packages/`. + +```admonish tip title="Only two overrides are required" +Building the `openvmm` binary for the gnu target needs no source patches. It +needs the distribution build packages below, plus two environment overrides +(`PROTOC` and `OPENSSL_NO_VENDOR`). +``` + +## Toolchain + +The workspace declares a minimum supported Rust version (MSRV) in the root +`Cargo.toml` (`rust-version`). Building requires a Rust toolchain at least that +new. The MSRV advances over time, so confirm the current value in the source +you are packaging and require at least that Rust version in the package. + +```admonish warning title="Distribution Rust may lag the MSRV" +If the distribution's packaged `rust` is older than the workspace MSRV, `cargo` +fails during resolution — for example: + + error: package `x86emu@0.0.0` cannot be built because it requires + rustc 1.95 or newer, while the currently active rustc version is 1.90.0 + +Target a distribution whose packaged Rust meets the MSRV, or arrange a newer +toolchain in the package build environment. +``` + +## Native build dependencies + +The `openvmm` gnu binary compiles a small amount of C through build scripts and +shells out to `protoc`. The native build dependencies are: + +- a C toolchain (`gcc`, the glibc development headers, and `binutils`); +- the Linux UAPI headers (`kernel-headers`), for the bundled SQLite compiled by + `libsqlite3-sys`; +- the OpenSSL development headers, for `openssl-sys`; +- a Protocol Buffers compiler providing `protoc`, for `prost` / `pbjson`. + +```admonish note title="SymCrypt is not needed for the gnu build" +The `crypto` crate selects the OpenSSL backend on `target_os = "linux"` for +non-`musl` targets, and SymCrypt only on `musl`. The `openvmm` gnu binary +therefore does not depend on SymCrypt, `ms-tpm-20-ref`, or `mimalloc` — none of +them appear in `cargo tree -p openvmm` for the host target. Only `musl` +(OpenHCL) builds link SymCrypt. See [Crypto Backends](./crypto_backends.md). +``` + +### Azure Linux package names + +Package names differ between Azure Linux versions: + +| Need | Azure Linux 3.0 | Azure Linux 4.0 | +| --- | --- | --- | +| C toolchain | `gcc`, `glibc-devel`, `binutils` | same | +| Linux UAPI headers | `kernel-headers` | `kernel-headers` | +| OpenSSL headers | `openssl-devel` | `openssl-devel` | +| `protoc` | `protobuf` | `protobuf-compiler`, `protobuf-devel` | + +Azure Linux 3.0 ships a newer `protoc` that embeds the well-known types, so its +`protobuf` package is sufficient. Azure Linux 4.0 ships an older `protoc`, so +`protobuf-devel` is also required to supply `google/protobuf/*.proto` on disk. + +## Environment overrides + +The in-repo `.cargo/config.toml` sets `PROTOC` to a path under `.packages/` +unconditionally. A distribution build must point it at the system `protoc`. +Setting `OPENSSL_NO_VENDOR` makes `openssl-sys` link the system OpenSSL rather +than building a vendored copy: + +```bash +export PROTOC="$(command -v protoc)" +export OPENSSL_NO_VENDOR=1 +``` + +## Offline vendored build + +A package build should be reproducible and offline. Vendor all dependencies — +including the Git dependencies and the `[patch.crates-io]` pins — into a tarball +alongside the source archive: + +```bash +cargo vendor vendor/ > vendor-config.toml +``` + +`cargo vendor` captures the Git dependencies and their Git submodule C sources +(for example the `ms-tpm-20-ref` and SymCrypt submodules), so the vendored tree +is self-contained. Append the generated `[source]` redirection to +`.cargo/config.toml`, then build without network access: + +```bash +cargo build --release -p openvmm --offline +``` + +## Runtime dependencies + +The resulting binary links a small, stable set of shared libraries. Confirm the +exact set for your build with `ldd`: + +- glibc (`libc`, `libm`); +- OpenSSL (`libssl`, `libcrypto`); +- `libgcc_s`. + +Depending on the OpenSSL build, `libz` may also appear transitively. The bundled +SQLite is linked statically and adds no runtime dependency. RPM automatic +dependency generation derives these from the ELF `NEEDED` entries; the +corresponding packages are typically `glibc`, `openssl-libs`, and `zlib`. + +## Worked example: Azure Linux RPM + +This uses a common Rust-packaging pattern: a source tarball, a `cargo vendor` +tarball, and an offline build. The distribution package version is independent +from the OpenVMM product version (see +[Independent version spaces](./openvmm_release.md#independent-version-spaces)). + +Use `openvmm--source.tar.gz` from the release as `Source0` so the build +retains its release identity through `.openvmm-release.json`. Do not use +GitHub's automatic archive links, which drop that metadata. + +Declare the build and runtime dependencies: + +```spec +BuildRequires: rust >= 1.95 +BuildRequires: cargo >= 1.95 +BuildRequires: gcc glibc-devel binutils kernel-headers +BuildRequires: openssl-devel +BuildRequires: protobuf-compiler protobuf-devel + +Requires: glibc +Requires: openssl-libs +Requires: zlib +``` + +Build offline and install the single binary: + +```spec +%build +export PROTOC="$(command -v protoc)" +export OPENSSL_NO_VENDOR=1 +cargo build --release --offline -p openvmm \ + --target x86_64-unknown-linux-gnu + +%install +install -D -m0755 \ + target/x86_64-unknown-linux-gnu/release/openvmm \ + %{buildroot}%{_bindir}/openvmm +``` + +On Azure Linux 3.0, replace `protobuf-compiler protobuf-devel` with `protobuf`, +and confirm the packaged `rust` meets the workspace MSRV before adopting a base +version. diff --git a/Guide/src/dev_guide/contrib/openvmm_release.md b/Guide/src/dev_guide/contrib/openvmm_release.md new file mode 100644 index 0000000000..4e335f3ed2 --- /dev/null +++ b/Guide/src/dev_guide/contrib/openvmm_release.md @@ -0,0 +1,367 @@ +# OpenVMM Release Model and Support + +This page describes standalone OpenVMM releases, support policy, source-build +identity, and the maintainer release runbook. OpenVMM versions are independent +from OpenHCL servicing versions. + +## One repository, two products + +OpenVMM and OpenHCL share a repository and substantial code, but they are +separate products with different release and support policies. + +| Product | Release and support model | +| --- | --- | +| OpenVMM | Cross-platform Virtual Machine Monitor. Continuous development on `main`, with standalone releases identified by OpenVMM-specific tags. | +| OpenHCL | Paravisor built on OpenVMM. Releases and in-market servicing use selected long-lived release branches. | + +```admonish note title="See also" +[OpenHCL Release Management](./release.md) describes the OpenHCL release +branch and backport process. +``` + +## Pre-1.0 cadence and support + +Before `1.0`, maintainers target approximately one OpenVMM release per month +from a healthy `main` commit. A release may be delayed or skipped when the +candidate does not meet the quality bar. Calendar months are not encoded into +the product version. + +Normal releases advance the minor version: + +```text +0.1.0 +0.2.0 +0.3.0 +``` + +Only the newest OpenVMM release is supported. Before `1.0`, fixes — including +security fixes and release-blocking regressions — ship by rolling forward: the +fix lands on `main` and rides the next release, cut early when it is urgent. +Once a newer release ships, the previous line leaves support. + +```admonish note title="Patch releases and servicing branches are post-1.0" +The patch-version scheme just below and the +[Patch release runbook](#patch-release-runbook) describe servicing an older +in-support line in isolation. That model arrives with post-`1.0` stable release +branches. Pre-`1.0`, OpenVMM rolls forward from `main` rather than maintaining +release branches, so patch releases (`X.Y.Z` with `Z` greater than `0`) are not +produced yet. +``` + +Patch releases advance the patch version: + +```text +0.2.1 +0.2.2 +``` + +Before `1.0`, normal minor releases may make breaking changes to APIs, +command-line behavior, device models, snapshot formats, and other interfaces. +Breaking changes should be intentional and documented in the release notes, +with migration guidance when practical. Patch releases correct the currently +supported minor line and should not intentionally introduce breaking changes. + +## Release tags + +Git tags are the only source of public OpenVMM semantic versions. There is no +checked-in OpenVMM product-version file. + +Release tags use: + +```text +openvmm-vMAJOR.MINOR.PATCH +``` + +Examples: + +```text +openvmm-v0.1.0 +openvmm-v0.1.1 +openvmm-v0.2.0 +``` + +Tags must contain exactly three canonical unsigned numeric components. +Prerelease suffixes, build metadata, leading zeroes, and additional components +are rejected. + +Normal `MAJOR.MINOR.0` tags must point to commits reachable from `main`. A +patch tag must descend from its immediate predecessor. For example, +`openvmm-v0.2.2` must descend from `openvmm-v0.2.1`. + +More than one `openvmm-v*` tag on the same commit is an error. After Git checks +out a tagged commit, the source identity cannot determine which of several tags +the caller intended. Selecting the highest version could therefore make a +checkout of an older tag report a newer version. Each release commit must have +exactly one OpenVMM release tag. Pushed release tags are immutable. + +## Build identity + +```admonish note +The source-identity versioning described here is under development. It is the +intended model, not current behavior: today `openvmm --version` reports the +Cargo package version. Treat this section as planned until the implementation +lands. +``` + +OpenVMM resolves its displayed version from source identity: + +| Source state | Displayed version | +| --- | --- | +| Clean exact `openvmm-v0.2.0` tag | `0.2.0` | +| Dirty exact tag | `0.2.0+dirty` | +| Clean untagged Git checkout | `0.0.0-dev+g012345678` | +| Dirty untagged Git checkout | `0.0.0-dev+g012345678.dirty` | +| No usable Git or generated release metadata | `0.0.0-dev` | + +The `g` prefix follows the `git describe` convention and identifies the +following nine characters as an abbreviated Git commit ID. It is not part of +the commit ID. + +More than one OpenVMM release tag on `HEAD` fails the build rather than +selecting an arbitrary version. + +`openvmm --version` prints the concise displayed version. The full source +revision remains available as separate embedded build information. + +A copied or exported source tree may contain neither Git metadata nor generated +release metadata. Examples include GitHub's automatic source archives and +metadata-free vendored source trees. Such a build warns that `0.0.0-dev` is not +an official release identity. The official OpenVMM source archive described +below instead includes generated release metadata and retains the exact release +identity without Git. + +Windows numeric version resources use `MAJOR.MINOR.PATCH.0` for an official +release and `0.0.0.0` for a development build. + +### Independent version spaces + +The OpenVMM product version is independent from: + +- internal Cargo crate versions; +- OpenHCL release and servicing versions; +- distribution package versions; +- CI build counters; +- source revision identifiers. + +Build and distribution systems may record package versions, build IDs, and +source revisions as additional metadata. They must not present those values as +the OpenVMM product version. + +## Release assets + +The initial release contains nine archives plus a separate `SHA256SUMS` +checksum file: + +- `openvmm--windows-x64.zip`; +- `openvmm--windows-x64-symbols.zip`; +- `openvmm--windows-arm64.zip`; +- `openvmm--windows-arm64-symbols.zip`; +- `openvmm--linux-x64-musl.tar.gz`; +- `openvmm--linux-x64-musl-symbols.tar.gz`; +- `openvmm--linux-arm64-musl.tar.gz`; +- `openvmm--linux-arm64-musl-symbols.tar.gz`; +- `openvmm--source.tar.gz`; +- `SHA256SUMS`. + +Runtime archives contain the runnable binary and `LICENSE`. Symbol archives +contain the matching debug symbols and `LICENSE`. Linux runtime binaries retain +executable permissions. + +`SHA256SUMS` covers all nine archives. Every archive and `SHA256SUMS` receives a +public GitHub build provenance attestation before the release is published. + +```admonish warning title="Windows signing is not implemented" +The public release workflow does not Authenticode-sign Windows artifacts. Do +not describe downloaded Windows executables as signed. +``` + +## Building a release from source + +A real Git checkout with the exact release tag available derives its version +directly from Git: + +```bash +git clone https://github.com/microsoft/openvmm.git +cd openvmm +git checkout openvmm-v0.2.0 +``` + +Build OpenVMM from the checkout with Cargo: + +```bash +cargo build +``` + +See [Building OpenVMM](../getting_started/build_openvmm.md) for prerequisites +and additional build options. + +Once the release automation lands, each release will also publish an official +attested source archive. The archive will contain `.openvmm-release.json` at +its root, recording the metadata schema, release version, release tag, and full +source revision. Builds from this archive retain the exact release identity +without a `.git` directory. + +```admonish warning title="Use the official source archive" +GitHub's automatic "Source code (zip)" and "Source code (tar.gz)" links omit Git +metadata and do not preserve the OpenVMM release identity. They are convenience +snapshots, not supported version-preserving build inputs. Use a real checkout of +the release tag or `openvmm--source.tar.gz`. +``` + +## Normal release runbook + +```admonish note +The tag-triggered release automation described below is under development. Do +not create a public OpenVMM release tag until that implementation has landed. +``` + +Tag creation is the release decision. A successful workflow publishes +automatically after building, packaging, checksumming, and attesting every +asset. There is no separate manual approval or draft-review phase. + +### 1. Select the release + +Choose a healthy commit already on `main`. Confirm that: + +- required changes are merged; +- required CI checks pass; +- the next normal version follows the release sequence; +- the version has not already been released; +- the commit is suitable for public release. + +Do not create the tag while required changes or checks are outstanding. + +### 2. Create and push the tag + +Update local `main`, confirm the working tree is clean, and create an annotated +tag. For example: + +```bash +git switch main +git pull --ff-only +git status --short +version="0.2.0" +tag="openvmm-v${version}" +git tag -a "${tag}" -m "OpenVMM ${version}" +git push origin "${tag}" +``` + +Do not move, delete, or recreate a pushed release tag. + +### 3. Monitor automatic publication + +The tag starts the OpenVMM release workflow. The workflow: + +1. validates the tag and commit topology; +2. builds Windows x64, Windows ARM64, Linux musl x64, and Linux musl ARM64; +3. creates separate runtime and symbol archives; +4. creates the official source archive; +5. creates `SHA256SUMS`; +6. attests every archive and the checksum file; +7. publishes a non-draft GitHub Release with generated notes. + +If a build, packaging, checksum, or attestation step fails, no public release +is created. The same immutable tag may be rerun after a pipeline or +infrastructure failure when no release was published. + +If a public release already exists, the workflow refuses to replace its assets. +Correct a bad published release with a new version rather than mutating it. + +### 4. Confirm the release + +After the workflow succeeds, confirm that: + +- the release page points to the intended tag and revision; +- all four targets have separate runtime and symbol archives; +- the official source archive is present; +- every runtime and symbol archive contains `LICENSE`; +- `SHA256SUMS` covers all nine archives; +- every archive and `SHA256SUMS` has a provenance attestation; +- generated notes cover the intended pull requests; +- Windows assets are not described as signed; +- the release is presented as the newest supported OpenVMM release. + +After downloading all assets into one directory, verify the checksums: + +```bash +sha256sum -c SHA256SUMS +``` + +Verify an asset's provenance with the GitHub CLI: + +```bash +gh attestation verify path/to/ --repo microsoft/openvmm +``` + +Smoke-test runnable archives on compatible hosts where practical. At minimum, +confirm that the executable starts and reports the expected version. + +## Patch release runbook + +```admonish note title="Post-1.0: requires stable release branches" +This runbook applies once OpenVMM adopts post-`1.0` stable release branches for +servicing an older in-support line. Pre-`1.0`, fixes instead roll forward in the +next release from `main` and no patch branches are created — see +[Pre-1.0 cadence and support](#pre-10-cadence-and-support). This process mirrors +the OpenHCL [release branch model](./release.md). +``` + +OpenVMM does not create a release branch for every normal release. Create a +patch branch only when the currently supported release requires a security or +release-blocking fix. + +1. Implement and merge the fix into `main`. +2. Create a temporary patch branch from the currently supported release tag. +3. Cherry-pick the fix onto that branch. +4. Validate the branch and the affected release artifacts. +5. Tag the corrected commit with the next patch version. +6. Push the tag and monitor the normal automatic release workflow. + +For example: + +```bash +git switch main +git pull --ff-only +git switch -c patch/openvmm-0.2.x openvmm-v0.2.0 +git cherry-pick +git tag -a openvmm-v0.2.1 -m "OpenVMM 0.2.1" +git push origin openvmm-v0.2.1 +``` + +Further patches must branch from or include their immediate predecessor. For +example, `openvmm-v0.2.2` must descend from `openvmm-v0.2.1`. + +The patch branch is not a new general development branch. New work continues +on `main`, and the older line leaves support when the next normal release +ships. + +## How fixes flow + +Shared fixes always land in `main` first. + +For OpenHCL, maintainers cherry-pick a fix to each live OpenHCL release branch +that requires it. + +For OpenVMM before `1.0`, the fix ships in the next release rolled forward from +`main`, cut early when it is urgent. On-demand patch releases to an older +in-support line arrive post-`1.0` with stable release branches. + +## Reporting security issues + +Do not report security vulnerabilities through public GitHub issues, pull +requests, or discussions. Report them privately through the Microsoft Security +Response Center (MSRC) as described in the repository +[`SECURITY.md`](https://github.com/microsoft/openvmm/blob/main/SECURITY.md). + +A confirmed security issue in the currently supported OpenVMM release ships as a +patch following the patch release runbook above. + +## Future policy + +The project may later designate selected releases for longer support, but no +LTS policy exists yet. Before supporting multiple OpenVMM lines or publishing +`1.0.0`, maintainers must document the compatibility, deprecation, +support-window, and servicing commitments. + +Public nightly releases are deferred until a concrete consumer requires them. +Ordinary CI artifacts remain available for engineering use. diff --git a/Guide/src/dev_guide/contrib/release.md b/Guide/src/dev_guide/contrib/release.md index aa1b269d5a..aaed239003 100644 --- a/Guide/src/dev_guide/contrib/release.md +++ b/Guide/src/dev_guide/contrib/release.md @@ -1,16 +1,33 @@ -# Release Management +# OpenHCL Release Management -Occasionally, the OpenVMM project will declare upcoming release milestones. We -stabilize the code base in a `release/..` branch, typically +This page describes the OpenHCL release branch, stabilization, and servicing +process. + +```admonish note title="See also" +[OpenVMM Release Model and Support](./openvmm_release.md) describes standalone +OpenVMM releases. OpenVMM tags and versions are independent from the OpenHCL +release branches described below. +``` + +```admonish warning +The `release/*` branches on this page service OpenHCL. They are not standalone +OpenVMM release branches. OpenVMM normally releases directly from `main` and +creates a separate on-demand patch branch only when its currently supported +release requires a security or release-blocking fix. +``` +Occasionally, the OpenHCL project will declare upcoming release milestones. +We stabilize the code base in a `release/..` branch, typically named for the YYMM when the branch was forked. Future references to the release number will be shortened to `` in this doc. We expect a high quality -bar for all code that goes into the OpenVMM main branch, and we ask developers -to hold these release branches to the highest quality standards. The OpenVMM -maintainers will gradually slow the rate of churn into these branches as we get -closer to a close date. +bar for all code that goes into the repository's main branch, and we ask +developers to hold these release branches to the highest quality standards. The +OpenHCL maintainers will gradually slow the rate of churn into these branches +as we get closer to a close date. -> **Note:** Some older release branches use the format `release/` without -> the major and minor version numbers (e.g., `release/2411`, `release/2505`). +```admonish note +Some older release branches use the format `release/` without the major +and minor version numbers, such as `release/2411` and `release/2505`. +``` This process should not impact your typical workflow; all new work should go into the `main` branch. But, to ease the cherry-picks, we may ask that you hold @@ -19,10 +36,8 @@ process. ## Marking, Approval Process, Code Flow -The OpenVMM maintainers will publish various dates for the upcoming releases. -Currently, these dates are driven by a Microsoft-internal process and can, and -do, often change. Microsoft does not mean to convey any new product launches by -choices of these dates. +The OpenHCL maintainers will publish various dates for upcoming releases. These +dates may change as release needs evolve and do not convey new product launches. Releases naturally fall into several phases: @@ -42,7 +57,9 @@ We track the state of candidates for a given release by tagging the PRs with the * N.B.: A maintainer will _remove_ this tag if the fix is not accepted into the release. * `backported_`: This PR (to `main`) has been cherry-picked to the release branch. -The [`repo_support/relabel_backported.py`](https://github.com/microsoft/openvmm/blob/main/repo_support/relabel_backported.py) script can be used to automatically transition PRs from `backport_` to `backported_` once they have been cherry-picked to the release branch. +The [`repo_support/relabel_backported.py`][relabel-backported] script can +automatically transition PRs from `backport_` to +`backported_` once they have been cherry-picked to the release branch. #### Seeking Approval for Backport @@ -66,7 +83,7 @@ When creating a backport PR to a release branch: resolution or additional modifications), clearly indicate this in the PR description. This signals to the reviewer that extra care is needed during the review process. - + ## Existing Release Branches | Release | Phase | Notes | @@ -81,3 +98,5 @@ When creating a backport PR to a release branch: We welcome feedback, especially if you would like to depend on a reliable release process. Please reach out! + +[relabel-backported]: https://github.com/microsoft/openvmm/blob/main/repo_support/relabel_backported.py diff --git a/Guide/src/reference/openvmm/management/cli.md b/Guide/src/reference/openvmm/management/cli.md index 5e76d4b488..3d9a17faaf 100644 --- a/Guide/src/reference/openvmm/management/cli.md +++ b/Guide/src/reference/openvmm/management/cli.md @@ -7,6 +7,12 @@ The most up to date reference is always the [code itself](https://openvmm.dev/ru as well as the generated CLI help (via `cargo run -- --help`). ``` +* `--version`, `-V`: Prints the OpenVMM version and exits. The tag-derived + source identity output (a clean release tag reports `MAJOR.MINOR.PATCH`, a + dirty tagged checkout adds `+dirty`, and an untagged checkout reports a + development version containing the source revision) is under development. + Current in-repo builds report the Cargo package version instead. See the + [OpenVMM release model](../../../dev_guide/contrib/openvmm_release.md#build-identity). * `--processors `: The number of processors. Defaults to 1. * `--memory `: Configure guest RAM. Defaults to `size=1G`. `SPEC` can be a size-only shorthand, such as `--memory 4G`, or a