Merge master into pool licensing feature branch

.github/workflows/generate-and-build-sdks.yml

@@ -168,6 +168,7 @@ jobs:
         run: |
           dotnet test source/XenServerTest `
           --disable-build-servers `
+          -p:DefineConstants=BUILD_FOR_TEST `
           --verbosity=normal
 
       - name: Build C# SDK

.github/workflows/main.yml

@@ -1,7 +1,11 @@
 name: Build and test
 
 on:
+  # When only Hugo docs change, this workflow is not required:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   pull_request:
   schedule:
     # run daily, this refreshes the cache

.github/workflows/other.yml

@@ -1,7 +1,11 @@
 name: Build and test (other)
 
 on:
+  # When only Hugo docs change, this workflow is not required:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   pull_request:
   schedule:
     # run daily, this refreshes the cache

doc/README.md

@@ -1,17 +1,104 @@
-Quick start guide:
+# Quick start guide
+
+- Visit <https://xapi-project.github.io/new-docs/> to view the current documentation.
+
+## Required software
+
+The docs use Hugo and the [Hugo Relearn theme](https://mcshelby.github.io/hugo-theme-relearn),
+an enhanced fork of the popular Hugo Learn theme.
+
+### Supported versions of Hugo and the Hugo Relearn theme
+
+Hugo Relearn 7.3.2 is currently used (defined by a git tag in `doc/go.mod`).
+
+- The minimum Hugo version required by the Relearn theme is 0.126.0.
+- The current Ubuntu `snap` (which provides 0.142.0) also works.
+
+## Installation
+
+- Install Hugo 0.126 or newer (required by the Hugo Relearn theme)
+  follow the guidance on <https://gohugo.io/installing>.
+  You'll need to install Go as well: see <https://go.dev/>
+  - On Ubuntu, use the `snap` package:
+    - `sudo snap install hugo` installs the current version
+      `apt-get install hugo` would install a version that is too old,
+      (this applies up to Ubuntu 24.04)
+
+  - To install Hugo from source, you need a recent `golang-1.2x` compiler:
+    - On Ubuntu 22.04, this can be done with:
+
+      ```bash
+      sudo apt install golang-1.23-go
+      # Add it to your path, assuming your .local/bin/ is early in your PATH:
+      ln -s /usr/lib/go-1.23/bin/go ~/.local/bin/go
+      go version
+      go install github.com/gohugoio/hugo@v0.127.0
+      ```
+
+## Development
 
-- Visit https://xapi-project.github.io/new-docs/ to view the current documentation.
-- Install Hugo; follow the guidance on https://gohugo.io/getting-started/installing.
-  You'll need Go as well: see https://go.dev/
-  - On Ubuntu 22.04 and older, use `sudo snap install hugo` to get the needed newer version of `hugo`.
 - Run a local server: `hugo server`
-- Open a browser at http://127.0.0.1:1313/new-docs/
+- Open a browser at <http://127.0.0.1:1313/new-docs/>
 - Add content to `doc/content/`:
   - Documents are written in Markdown.
-  - Please wrap lines in paragraphs to make review and diffs easier to read.
-  - The menu hierarchy comes mostly from the directory structure in `content/`.
+  - Please wrap lines in paragraphs to make reviews more manageable.
+  - The menu hierarchy comes mainly from the directory structure in `content/`.
   - A file called `_index.md` is needed in a directory to define a new level in the menu.
-    - To set the page title which is also used for the main menu,
+    - To set the page title,
       [use the front matter](https://gohugo.io/content-management/front-matter/).
-  - For a page that has images or other stuff included, it is best to create a new directory. Put the contents in a `index.md` file (no `_`) and the related files next to it. See https://gohugo.io/content-management/organization/ for more information.
-  - Look at https://mcshelby.github.io/hugo-theme-relearn/ for more information about what the Relearn theme offers, including some handy "shortcodes".
+  - For a page that has images or other stuff included, it is best to create a new directory:
+    Put the contents in an `index.md` file (no `_`) and the related files next to it.
+    See <https://gohugo.io/content-management/organization/> for more information.
+
+  See <https://mcshelby.github.io/hugo-theme-relearn/> for more information about
+  the features of the Relearn theme, including handy "shortcodes".
+
+Note: When switching versions, before re-generating the documentation using
+`hugo server`, delete the previously generated static site using `rm -r docs/public`.
+
+### Notes for supporting current versions of Hugo and the Relearn theme
+
+Backported fixes to support newer Hugo versions:
+
+- `layouts/partials/header.html`, it fixes:
+  ```js
+  ERROR deprecated: .Sites.First was deprecated in Hugo v0.127.0 and will be removed in Hugo 0.143.0. Use .Sites.Default instead.
+  ```
+- `layouts/partials/menu.html`, it fixes:
+  ```js
+  ERROR deprecated: .Site.IsMultiLingual was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.143.0. Use hugo.IsMultilingual instead.
+  ```
+
+The fixes for those issues were backported from the Hugo Relearn v7.x.x theme.
+When updating to Hugo Relearn 7.x.x, please remove them (if possible).
+
+#### Tips when upgradubg to newer Hugo Relearn versions
+
+Check the release notes of the Hugo Relearn theme for breaking changes:
+https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes
+
+These pages might need review when making changes as their content is
+generated by layouts/partials/content.html:
+
+- XenAPI Reference: <https://xapi-project.github.io/new-docs/xen-api/classes>
+- XenAPI Releases: <https://xapi-project.github.io/new-docs/xen-api/releases>
+
+For a summary of the partials supported by the Hugo Relearn theme, see:
+https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/partials
+
+Hint: For upgrading the Hugo Relearn theme, you can use:
+
+```bash
+cd doc; hugo mod get -u github.com/McShelby/hugo-theme-relearn@7.4.0
+```
+
+#### Summary
+
+Hugo >= 0.126 and the Hugo Relearn >= 7.3.2 are supported to render the docs.
+
+#### References
+
+- Changes with Relearn 6.x:
+  <https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/6/#6-0-0>
+- Breaking changes with Relearn 7.x:
+  <https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/7/#7-0-0>

doc/content/design/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Design Documents"
-menuTitle = "Designs"
+linkTitle = "Designs"
 +++
 
 {{< design_docs_list >}}

doc/content/design/cpu-levelling-v2.md

@@ -29,7 +29,7 @@ The old XS 5.6-style Heterogeneous Pool feature that is based around hardware-le
 History
 =======
 
-- Original XS 5.6 design: [heterogeneous-pools](../heterogeneous-pools)
+- Original XS 5.6 design: [heterogeneous-pools](heterogeneous-pools)
 - Changes made in XS 5.6 FP1 for the DR feature (added CPUID checks upon migration)
 - XS 6.1: migration checks extended for cross-pool scenario
 

doc/content/design/emulated-pci-spec.md

@@ -11,7 +11,7 @@ status: proposed
 At present (early March 2015) the datamodel defines a VM as having a "platform" string-string map, in which two keys are interpreted as specifying a PCI device which should be emulated for the VM. Those keys are "device_id" and "revision" (with int values represented as decimal strings).
 
 Limitations:
-* Hardcoded defaults are used for the the vendor ID and all other parameters except device_id and revision.
+* Hardcoded defaults are used for the vendor ID and all other parameters except device_id and revision.
 * Only one emulated PCI device can be specified.
 
 When instructing qemu to emulate PCI devices, qemu accepts twelve parameters for each device.

doc/content/design/integrated-gpu-passthrough/index.md

@@ -11,7 +11,7 @@ Introduction
 ------------
 
 Passthrough of discrete GPUs has been
-[available since XenServer 6.0]({{site.baseurl}}/xapi/design/gpu-passthrough.html).
+[available since XenServer 6.0](../gpu-passthrough.md).
 With some extensions, we will also be able to support passthrough of integrated
 GPUs.
 

doc/content/design/local-database.md

@@ -25,7 +25,7 @@ We propose to:
   this should reduce the number of RPCs across the network.
 
 In a later phase we can move to a completely
-[distributed database](../distributed-database).
+[distributed database](distributed-database/index).
 
 Replicating the database
 ------------------------

doc/content/design/multiple-cluster-managers.md

@@ -14,7 +14,7 @@ revision_history:
 Introduction
 ------------
 
-Xapi currently uses a cluster manager called [xhad](../../features/HA/HA.html). Sometimes other software comes with its own built-in way of managing clusters, which would clash with xhad (example: xhad could choose to fence node 'a' while the other system could fence node 'b' resulting in a total failure). To integrate xapi with this other software we have 2 choices:
+Xapi currently uses a cluster manager called [xhad](../toolstack/features/HA/index). Sometimes other software comes with its own built-in way of managing clusters, which would clash with xhad (example: xhad could choose to fence node 'a' while the other system could fence node 'b' resulting in a total failure). To integrate xapi with this other software we have 2 choices:
 
 1. modify the other software to take membership information from xapi; or
 2. modify xapi to take membership information from this other software.
@@ -70,4 +70,4 @@ The `xapi.conf` file will have a new field: `cluster-stack-root` which will have
 
 In `Pool.enable_ha` with `cluster_stack="foo"` we will verify that the subdirectory `<cluster-stack-root>/foo` exists. If it does not exist, then the call will fail with `UNKNOWN_CLUSTER_STACK`.
 
-Alternative cluster stacks will need to conform to the exact same interface as [xhad](../../features/HA/HA.html).
+Alternative cluster stacks will need to conform to the exact same interface as [xhad](../toolstack/features/HA).

doc/content/design/ocfs2/index.md

@@ -461,7 +461,7 @@ Summary of the impact on the admin
 
 OCFS2 is fundamentally a different type of storage to all existing storage
 types supported by xapi. OCFS2 relies upon O2CB, which provides
-[Host-level High Availability](../../../features/HA/HA.html). All HA implementations
+[Host-level High Availability](../../toolstack/features/HA/index). All HA implementations
 (including O2CB and `xhad`) impose restrictions on the server admin to
 prevent unnecessary host "fencing" (i.e. crashing). Once we have OCFS2 as
 a feature, we will have to live with these restrictions which previously only

doc/content/design/patches-in-vdis.md

@@ -71,7 +71,7 @@ Changes beneath the XenAPI
 Summary of the impact on the admin
 ==================================
 
-- There will nolonger be a size limit on hotfixes imposed by the mechanism
+- There will no longer be a size limit on hotfixes imposed by the mechanism
   itself.
 - There must be enough free space in an SR connected to the host to be able
   to apply a patch on that host.

doc/content/design/schedule-snapshot.md

@@ -28,8 +28,8 @@ Introduction
 * Multiple VMs can be a part of VMSS but a VM cannot be a part of multiple VMSS.
 * A VMSS takes VMs snapshot with type [`snapshot`, `checkpoint`, `snapshot_with_quiesce`].
 * VMSS takes snapshot of VMs on configured intervals:
-	* `hourly` -> On everyday, Each hour, Mins [0;15;30;45]
-	* `daily` -> On everyday, Hour [0 to 23], Mins [0;15;30;45]
+	* `hourly` -> On every day, Each hour, Mins [0;15;30;45]
+	* `daily` -> On every day, Hour [0 to 23], Mins [0;15;30;45]
 	* `weekly` -> Days [`Monday`,`Tuesday`,`Wednesday`,`Thursday`,`Friday`,`Saturday`,`Sunday`], Hour[0 to 23], Mins [0;15;30;45]
 * VMSS will have a limit on retaining number of VM snapshots in range [1 to 10].
 

doc/content/design/user-certificates.md

@@ -16,7 +16,7 @@ and not impersonating the actual host.
 Historically there has not been a supported mechanism to do this, and as a
 result users have had to rely on guides written by third parties that show how
 to manually replace the xapi-ssl.pem file on a host. This process is
-error-prone, and if a mistake is made, can result in an unuseable system.
+error-prone, and if a mistake is made, can result in an unusable system.
 This design provides a fully supported mechanism to allow replacing the
 certificates.
 
@@ -200,7 +200,7 @@ should be removed to avoid a build-up of messages.
 
 Additionally, the task may also produce messages for expired server
 certificates which must use the name `HOST_SERVER_CERTIFICATE_EXPIRED`.
-These kind of message must contain the message "The TLS server certificate has
+This kind of message must contain the message "The TLS server certificate has
 expired." as well as the expiry date, like the expiring messages.
 They also may replace the existing expiring messages in a host.
 
@@ -220,7 +220,7 @@ A new class, Certificate, will be added with the following schema:
 | ---------- | --------- | ----- |
 | uuid       |           |
 | type       | CA        | Certificate trusted by all hosts
-|            | Host      | Certificate that the host present sto normal clients
+|            | Host      | Certificate that the host presents to normal clients
 | name       | String    | Name, only present for trusted certificates
 | host       | Ref _host | Host where the certificate is installed
 | not_before | DateTime  | Date after which the certificate is valid
@@ -246,7 +246,7 @@ and it will accept the parameter `host-uuid=<uuid>`.
 ## Recovery mechanism
 
 In the case a certificate is let to expire TLS clients connecting to the host
-will refuse establish the connection.
+will refuse to establish the connection.
 This means that the host is going to be unable to be managed using the xapi
 API (Xencenter, or a CVAD control plane)
 

doc/content/squeezed/architecture/index.md

@@ -18,7 +18,7 @@ includes:
   together describe a range, within which the domain's actual used memory
   should remain.
 - Per-domain calibration data which allows us to compute the necessary balloon
-  target value to achive a particular memory usage value.
+  target value to achieve a particular memory usage value.
 
 Squeezed is a single-threaded program which receives commands from xenopsd over
 a Unix domain socket. When Xenopsd wishes to start a new VM, squeezed will be

doc/content/squeezed/squeezer.md

@@ -4,7 +4,7 @@ hidden: true
 ---
 
 {{% notice warning %}}
-This was converted to markdown from squeezer.tex. It is not clear how much
+This was converted to Markdown from squeezer.tex. It is not clear how much
 of this document is still relevant and/or already present in the other docs.
 {{% /notice %}}
 

doc/content/toolstack/_index.md

@@ -1,6 +1,6 @@
 ---
 title: The XAPI Toolstack
-menuTitle: The Toolstack
+linkTitle: The Toolstack
 weight: 10
 ---
 

doc/content/toolstack/features/DR/index.md

@@ -2,7 +2,7 @@
 title = "Disaster Recovery"
 +++
 
-The [HA](../HA/HA.html) feature will restart VMs after hosts have failed, but what
+The [HA](HA) feature will restart VMs after hosts have failed, but what
 happens if a whole site (e.g. datacenter) is lost? A disaster recovery
 configuration is shown in the following diagram: