doc/config options: link to config options where possible

Ruth Fuchss · Ruth Fuchss · commit 3ab13a6becac · 2024-03-27T17:00:45.000+01:00
Signed-off-by: Ruth Fuchss &lt;ruth.fuchss@canonical.com&gt;
diff --git a/doc/dev-lxd.md b/doc/dev-lxd.md
@@ -214,7 +214,7 @@ This never returns. Each notification is sent as a separate JSON object:
 
 * Description: Download a public/cached image from the host
 * Return: raw image or error
-* Access: Requires `security.devlxd.images` set to `true`
+* Access: Requires {config:option}`instance-security:security.devlxd.images` set to `true`
 
 Return value:
 
diff --git a/doc/explanation/clustering.md b/doc/explanation/clustering.md
@@ -197,7 +197,7 @@ def instance_placement(request, candidate_members):
     return # Return empty to allow instance placement to proceed.
 ```
 
-The scriptlet must be applied to LXD by storing it in the `instances.placement.scriptlet` global configuration setting.
+The scriptlet must be applied to LXD by storing it in the {config:option}`server-miscellaneous:instances.placement.scriptlet` global configuration setting.
 
 For example, if the scriptlet is saved inside a file called `instance_placement.star`, then it can be applied to LXD with the following command:
 
diff --git a/doc/explanation/security.md b/doc/explanation/security.md
@@ -55,14 +55,14 @@ The root user and all members of the `lxd` group can interact with the local dae
 ### Access to the remote API
 
 By default, access to the daemon is only possible locally.
-By setting the `core.https_address` configuration option, you can expose the same API over the network on a {abbr}`TLS (Transport Layer Security)` socket.
+By setting the {config:option}`server-core:core.https_address` configuration option, you can expose the same API over the network on a {abbr}`TLS (Transport Layer Security)` socket.
 See {ref}`server-expose` for instructions.
 Remote clients can then connect to LXD and access any image that is marked for public use.
 
 There are several ways to authenticate remote clients as trusted clients to allow them to access the API.
 See {ref}`authentication` for details.
 
-In a production setup, you should set `core.https_address` to the single address where the server should be available (rather than any address on the host).
+In a production setup, you should set {config:option}`server-core:core.https_address` to the single address where the server should be available (rather than any address on the host).
 In addition, you should set firewall rules to allow access to the LXD port only from authorized hosts/subnets.
 
 (container-security)=
diff --git a/doc/howto/cluster_config_networks.md b/doc/howto/cluster_config_networks.md
@@ -2,7 +2,7 @@
 # How to configure networks for a cluster
 
 All members of a cluster must have identical networks defined.
-The only configuration keys that may differ between networks on different members are [`bridge.external_interfaces`](network-bridge-options), [`parent`](ref-networks), [`bgp.ipv4.nexthop`](network-bridge-options) and [`bgp.ipv6.nexthop`](network-bridge-options).
+The only configuration keys that may differ between networks on different members are {config:option}`network-bridge-network-conf:bridge.external_interfaces`, {config:option}`network-physical-network-conf:parent`, {config:option}`network-bridge-network-conf:bgp.ipv4.nexthop`, and {config:option}`network-bridge-network-conf:bgp.ipv6.nexthop`.
 See {ref}`clustering-member-config` for more information.
 
 Creating additional networks is a two-step process:
diff --git a/doc/howto/cluster_manage.md b/doc/howto/cluster_manage.md
@@ -75,7 +75,7 @@ This command migrates all instances on the given server, moving them to other cl
 The evacuated cluster member is then transitioned to an "evacuated" state, which prevents the creation of any instances on it.
 
 You can control how each instance is moved through the {config:option}`instance-miscellaneous:cluster.evacuate` instance configuration key.
-Instances are shut down cleanly, respecting the `boot.host_shutdown_timeout` configuration key.
+Instances are shut down cleanly, respecting the {config:option}`instance-boot:boot.host_shutdown_timeout` configuration key.
 
 When the evacuated server is available again, use the [`lxc cluster restore`](lxc_cluster_restore.md) command to move the server back into a normal running state.
 This command also moves the evacuated instances back from the servers that were temporarily holding them.
diff --git a/doc/howto/instances_create.md b/doc/howto/instances_create.md
@@ -302,7 +302,7 @@ Lastly, attach the custom ISO volume to the VM using the following command:
 ```
 ````
 
-The `boot.priority` configuration key ensures that the VM will boot from the ISO first.
+The {config:option}`device-disk-device-conf:boot.priority` configuration key ensures that the VM will boot from the ISO first.
 Start the VM and {ref}`connect to the console <instances-console>` as there might be a menu you need to interact with:
 
 ````{tabs}
diff --git a/doc/howto/instances_troubleshoot.md b/doc/howto/instances_troubleshoot.md
@@ -71,7 +71,7 @@ The {doc}`container requirements <../container-environment>` specify that every
 If those directories don't exist, LXD cannot mount them, and `systemd` will then try to do so.
 As this is an unprivileged container, `systemd` does not have the ability to do this, and it then freezes.
 
-So you can see the environment before anything is changed, and you can explicitly change the init system in a container using the `raw.lxc` configuration parameter.
+So you can see the environment before anything is changed, and you can explicitly change the init system in a container using the {config:option}`instance-raw:raw.lxc` configuration parameter.
 This is equivalent to setting `init=/bin/bash` on the Linux kernel command line.
 
     lxc config set systemd raw.lxc 'lxc.init.cmd = /bin/bash'
diff --git a/doc/howto/network_bridge_resolved.md b/doc/howto/network_bridge_resolved.md
@@ -11,9 +11,9 @@ If the system that runs LXD uses `systemd-resolved` to perform DNS lookups, you
 To do so, add the DNS servers and domains provided by a LXD network bridge to the `resolved` configuration.
 
 ```{note}
-The `dns.mode` option (see {ref}`network-bridge-options`) must be set to `managed` or `dynamic` if you want to use this feature.
+The {config:option}`network-bridge-network-conf:dns.mode` option must be set to `managed` or `dynamic` if you want to use this feature.
 
-Depending on the configured `dns.domain`, you might need to disable DNSSEC in `resolved` to allow for DNS resolution.
+Depending on the configured {config:option}`network-bridge-network-conf:dns.domain`, you might need to disable DNSSEC in `resolved` to allow for DNS resolution.
 This can be done through the `DNSSEC` option in `resolved.conf`.
 ```
 
diff --git a/doc/howto/network_zones.md b/doc/howto/network_zones.md
@@ -63,7 +63,7 @@ For example: `lxc network zone set lxd.example.net peers.whatever.address=192.0.
 ```{note}
 It is not enough for the address to be of the same machine that `dig` is calling from; it needs to
 match as a string with what the DNS server in `lxd` thinks is the exact remote address. `dig` binds to
-`0.0.0.0`, therefore the address you need is most likely the same that you provided to `core.dns_address`.
+`0.0.0.0`, therefore the address you need is most likely the same that you provided to {config:option}`server-core:core.dns_address`.
 ```
 
 For example, running `dig @<DNS_server_IP> -p <DNS_server_PORT> axfr lxd.example.net` might give the following output:
diff --git a/doc/howto/projects_work.md b/doc/howto/projects_work.md
@@ -74,7 +74,7 @@ For example, to move the instance `my-instance` from the `default` project to `m
 
 ### Copy a profile to another project
 
-If you create a project with the default settings, profiles are isolated in the project ([`features.profiles`](project-features) is set to `true`).
+If you create a project with the default settings, profiles are isolated in the project ({config:option}`project-features:features.profiles` is set to `true`).
 Therefore, the project does not have access to the default profile (which is part of the `default` project), and you will see an error similar to the following when trying to create an instance:
 
 ```{terminal}
diff --git a/doc/reference/devices_disk.md b/doc/reference/devices_disk.md
@@ -75,7 +75,7 @@ Initial volume configuration allows setting specific configurations for the root
 These settings are prefixed with `initial.` and are only applied when the instance is created.
 This method allows creating instances that have unique configurations, independent of the default storage pool settings.
 
-For example, you can add an initial volume configuration for `zfs.block_mode` to an existing profile, and this
+For example, you can add an initial volume configuration for {config:option}`storage-zfs-volume-conf:zfs.block_mode` to an existing profile, and this
 will then take effect for each new instance you create using this profile:
 
     lxc profile device set <profile_name> <device_name> initial.zfs.block_mode=true
diff --git a/doc/reference/devices_nic.md b/doc/reference/devices_nic.md
@@ -463,7 +463,7 @@ A bridge also lets you use MAC filtering and I/O limits, which cannot be applied
 
 If you're using MAAS to manage the physical network under your LXD host and want to attach your instances directly to a MAAS-managed network, LXD can be configured to interact with MAAS so that it can track your instances.
 
-At the daemon level, you must configure `maas.api.url` and `maas.api.key`, and then set the `maas.subnet.ipv4` and/or `maas.subnet.ipv6` keys on the instance or profile's `nic` entry.
+At the daemon level, you must configure {config:option}`server-miscellaneous:maas.api.url` and {config:option}`server-miscellaneous:maas.api.key`, and then set the NIC-specific `maas.subnet.ipv4` and/or `maas.subnet.ipv6` keys on the instance or profile's `nic` entry.
 
 With this configuration, LXD registers all your instances with MAAS, giving them proper DHCP leases and DNS records.
 
diff --git a/doc/reference/instance_options.md b/doc/reference/instance_options.md
@@ -93,21 +93,21 @@ See {ref}`instance-options-limits-kernel` for more information.
 
 You have different options to limit CPU usage:
 
-- Set `limits.cpu` to restrict which CPUs the instance can see and use.
+- Set {config:option}`instance-resource-limits:limits.cpu` to restrict which CPUs the instance can see and use.
   See {ref}`instance-options-limits-cpu` for how to set this option.
-- Set `limits.cpu.allowance` to restrict the load an instance can put on the available CPUs.
+- Set {config:option}`instance-resource-limits:limits.cpu.allowance` to restrict the load an instance can put on the available CPUs.
   This option is available only for containers.
   See {ref}`instance-options-limits-cpu-container` for how to set this option.
 
 It is possible to set both options at the same time to restrict both which CPUs are visible to the instance and the allowed usage of those instances.
-However, if you use `limits.cpu.allowance` with a time limit, you should avoid using `limits.cpu` in addition, because that puts a lot of constraints on the scheduler and might lead to less efficient allocations.
+However, if you use {config:option}`instance-resource-limits:limits.cpu.allowance` with a time limit, you should avoid using {config:option}`instance-resource-limits:limits.cpu` in addition, because that puts a lot of constraints on the scheduler and might lead to less efficient allocations.
 
 The CPU limits are implemented through a mix of the `cpuset` and `cpu` cgroup controllers.
 
 (instance-options-limits-cpu)=
 #### CPU pinning
 
-`limits.cpu` results in CPU pinning through the `cpuset` controller.
+{config:option}`instance-resource-limits:limits.cpu` results in CPU pinning through the `cpuset` controller.
 You can specify either which CPUs or how many CPUs are visible and available to the instance:
 
 - To specify which CPUs to use, set `limits.cpu` to either a set of CPUs (for example, `1,2,3`) or a CPU range (for example, `0-3`).
@@ -119,18 +119,18 @@ You can specify either which CPUs or how many CPUs are visible and available to
 ##### CPU limits for virtual machines
 
 ```{note}
-LXD supports live-updating the `limits.cpu` option.
+LXD supports live-updating the {config:option}`instance-resource-limits:limits.cpu` option.
 However, for virtual machines, this only means that the respective CPUs are hotplugged.
 Depending on the guest operating system, you might need to either restart the instance or complete some manual actions to bring the new CPUs online.
 ```
 
 LXD virtual machines default to having just one vCPU allocated, which shows up as matching the host CPU vendor and type, but has a single core and no threads.
 
-When `limits.cpu` is set to a single integer, LXD allocates multiple vCPUs and exposes them to the guest as full cores.
+When {config:option}`instance-resource-limits:limits.cpu` is set to a single integer, LXD allocates multiple vCPUs and exposes them to the guest as full cores.
 Those vCPUs are not pinned to specific physical cores on the host.
 The number of vCPUs can be updated while the VM is running.
 
-When `limits.cpu` is set to a range or comma-separated list of CPU IDs (as provided by [`lxc info --resources`](lxc_info.md)), the vCPUs are pinned to those physical cores.
+When {config:option}`instance-resource-limits:limits.cpu` is set to a range or comma-separated list of CPU IDs (as provided by [`lxc info --resources`](lxc_info.md)), the vCPUs are pinned to those physical cores.
 In this scenario, LXD checks whether the CPU configuration lines up with a realistic hardware topology and if it does, it replicates that topology in the guest.
 When doing CPU pinning, it is not possible to change the configuration while the VM is running.
 
@@ -144,24 +144,24 @@ All this allows for very high performance operations in the guest as the guest s
 (instance-options-limits-cpu-container)=
 #### Allowance and priority (container only)
 
-`limits.cpu.allowance` drives either the CFS scheduler quotas when passed a time constraint, or the generic CPU shares mechanism when passed a percentage value:
+{config:option}`instance-resource-limits:limits.cpu.allowance` drives either the CFS scheduler quotas when passed a time constraint, or the generic CPU shares mechanism when passed a percentage value:
 
 - The time constraint (for example, `20ms/50ms`) is a hard limit.
-  For example, if you want to allow the container to use a maximum of one CPU, set `limits.cpu.allowance` to a value like `100ms/100ms`.
+  For example, if you want to allow the container to use a maximum of one CPU, set {config:option}`instance-resource-limits:limits.cpu.allowance` to a value like `100ms/100ms`.
   The value is relative to one CPU worth of time, so to restrict to two CPUs worth of time, use something like `100ms/50ms` or `200ms/100ms`.
 - When using a percentage value, the limit is a soft limit that is applied only when under load.
   It is used to calculate the scheduler priority for the instance, relative to any other instance that is using the same CPU or CPUs.
-  For example, to limit the CPU usage of the container to one CPU when under load, set `limits.cpu.allowance` to `100%`.
+  For example, to limit the CPU usage of the container to one CPU when under load, set {config:option}`instance-resource-limits:limits.cpu.allowance` to `100%`.
 
-`limits.cpu.nodes` can be used to restrict the CPUs that the instance can use to a specific set of NUMA nodes.
-To specify which NUMA nodes to use, set `limits.cpu.nodes` to either a set of NUMA node IDs (for example, `0,1`) or a set of NUMA node ranges (for example, `0-1,2-4`).
+{config:option}`instance-resource-limits:limits.cpu.nodes` can be used to restrict the CPUs that the instance can use to a specific set of NUMA nodes.
+To specify which NUMA nodes to use, set {config:option}`instance-resource-limits:limits.cpu.nodes` to either a set of NUMA node IDs (for example, `0,1`) or a set of NUMA node ranges (for example, `0-1,2-4`).
 
-`limits.cpu.priority` is another factor that is used to compute the scheduler priority score when a number of instances sharing a set of CPUs have the same percentage of CPU assigned to them.
+{config:option}`instance-resource-limits:limits.cpu.priority` is another factor that is used to compute the scheduler priority score when a number of instances sharing a set of CPUs have the same percentage of CPU assigned to them.
 
 (instance-options-limits-hugepages)=
 ### Huge page limits
 
-LXD allows to limit the number of huge pages available to a container through the `limits.hugepage.[size]` key.
+LXD allows to limit the number of huge pages available to a container through the `limits.hugepage.[size]` key (for example, {config:option}`instance-resource-limits:limits.hugepages.1MB`).
 
 Architectures often expose multiple huge-page sizes.
 The available huge-page sizes depend on the architecture.
@@ -176,7 +176,7 @@ Limiting huge pages is done through the `hugetlb` cgroup controller, which means
 (instance-options-limits-kernel)=
 ### Kernel resource limits
 
-For container instances, LXD exposes a generic namespaced key `limits.kernel.*` that can be used to set resource limits.
+For container instances, LXD exposes a generic namespaced key {config:option}`instance-resource-limits:limits.kernel.*` that can be used to set resource limits.
 
 It is generic in the sense that LXD does not perform any validation on the resource that is specified following the `limits.kernel.*` prefix.
 LXD cannot know about all the possible resources that a given kernel supports.
@@ -266,7 +266,7 @@ For example:
 - To add devices that are not supported by LXD before the machines boots.
 - To remove devices that conflict with the guest OS.
 
-To override the configuration, set the `raw.qemu.conf` option.
+To override the configuration, set the {config:option}`instance-raw:raw.qemu.conf` option.
 It supports a format similar to `qemu.conf`, with some additions.
 Since it is a multi-line configuration option, you can use it to modify multiple sections or keys.
 
diff --git a/doc/reference/storage_drivers.md b/doc/reference/storage_drivers.md
@@ -45,9 +45,9 @@ Available on `lxd init`                     | yes       | yes   | yes     | yes
 Object storage                              | yes       | yes   | yes     | yes     | no       | no     | yes         | no
 
 [^1]: Volumes of type `block` will fall back to non-optimized transfer when migrating to an older LXD server that doesn't yet support the `RBD_AND_RSYNC` migration type.
-[^2]: Requires [`lvm.use_thinpool`](storage-lvm-pool-config) to be enabled. Only when refreshing local volumes.
+[^2]: Requires {config:option}`storage-lvm-pool-conf:lvm.use_thinpool` to be enabled. Only when refreshing local volumes.
 [^3]: Only for volumes of type `block`.
-[^4]: Requires [`zfs.delegate`](storage-zfs-vol-config) to be enabled.
+[^4]: Requires {config:option}`storage-zfs-volume-conf:zfs.delegate` to be enabled.
 [^5]: % Include content from [storage_dir.md](storage_dir.md)
 
       ```{include} storage_dir.md
diff --git a/doc/syscall-interception.md b/doc/syscall-interception.md
diff --git a/doc/userns-idmap.md b/doc/userns-idmap.md
