gian/incus-mirror
1
0
Fork 0
mirror of https://github.com/lxc/incus synced 2026-08-02 05:26:46 +00:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

doc: s/LXD/Incus/g

Browse Source 
Signed-off-by: Stéphane Graber <stgraber@stgraber.org>
This commit is contained in:
Stéphane Graber 2023-10-06 12:35:35 -04:00
parent 8433436e99
commit fd6de29f56
No known key found for this signature in database
GPG Key ID: C638974D64792D67
112 changed files with 819 additions and 819 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/README.md
View File

@ -1,6 +1,6 @@
# LXD documentation
# Incus documentation
The LXD documentation is available at: <https://documentation.ubuntu.com/lxd/en/latest/>
The Incus documentation is available at: <https://documentation.ubuntu.com/lxd/en/latest/>
GitHub provides a basic rendering of the documentation as well, but important features like includes and clickable links are missing. Therefore, we recommend reading the [published documentation](https://documentation.ubuntu.com/lxd/en/latest/).
@ -10,7 +10,7 @@ GitHub provides a basic rendering of the documentation as well, but important fe
### Documentation framework
LXD's documentation is built with [Sphinx](https://www.sphinx-doc.org/en/master/index.html).
Incus's documentation is built with [Sphinx](https://www.sphinx-doc.org/en/master/index.html).
It is written in [Markdown](https://commonmark.org/) with [MyST](https://myst-parser.readthedocs.io/) extensions.
For syntax help and guidelines, see the [documentation cheat sheet](https://documentation.ubuntu.com/lxd/en/latest/doc-cheat-sheet/) ([source](https://raw.githubusercontent.com/canonical/lxd/main/doc/doc-cheat-sheet.md)).

126
doc/api-extensions.md
View File

@ -1,6 +1,6 @@
# API extensions
The changes below were introduced to the LXD API after the 1.0 API was finalized.
The changes below were introduced to the Incus API after the 1.0 API was finalized.
They are all backward compatible and can be detected by client tools by
looking at the `api_extensions` field in `GET /1.0`.
@ -9,7 +9,7 @@ looking at the `api_extensions` field in `GET /1.0`.
A `storage.zfs_remove_snapshots` daemon configuration key was introduced.
It's a Boolean that defaults to `false` and that when set to `true` instructs LXD
It's a Boolean that defaults to `false` and that when set to `true` instructs Incus
to remove any needed snapshot when attempting to restore another.
This is needed as ZFS will only let you restore the latest snapshot.
@ -18,10 +18,10 @@ This is needed as ZFS will only let you restore the latest snapshot.
A `boot.host_shutdown_timeout` container configuration key was introduced.
It's an integer which indicates how long LXD should wait for the container
It's an integer which indicates how long Incus should wait for the container
to stop before killing it.
Its value is only used on clean LXD daemon shutdown. It defaults to 30s.
Its value is only used on clean Incus daemon shutdown. It defaults to 30s.
## `container_stop_priority`
@ -73,8 +73,8 @@ And adds support for the following HTTP header on PUT requests:
* If-Match (ETag value retrieved through previous GET)
This makes it possible to GET a LXD object, modify it and PUT it without
risking to hit a race condition where LXD or another client modified the
This makes it possible to GET a Incus object, modify it and PUT it without
risking to hit a race condition where Incus or another client modified the
object in the meantime.
## `patch`
@ -89,7 +89,7 @@ Add support for USB hotplug.
## `https_allowed_credentials`
To use LXD API with all Web Browsers (via SPAs) you must send credentials
To use Incus API with all Web Browsers (via SPAs) you must send credentials
(certificate) with each XHR (in order for this to happen, you should set
[`withCredentials=true`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials)
flag to each XHR Request).
@ -106,8 +106,8 @@ Setting this property overrides the server default value (`images.compression_al
## `directory_manipulation`
This allows for creating and listing directories via the LXD API, and exports
the file type via the X-LXD-type header, which can be either `file` or
This allows for creating and listing directories via the Incus API, and exports
the file type via the X-Incus-type header, which can be either `file` or
`directory` right now.
## `container_cpu_time`
@ -116,9 +116,9 @@ This adds support for retrieving CPU time for a running container.
## `storage_zfs_use_refquota`
Introduces a new server property `storage.zfs_use_refquota` which instructs LXD
Introduces a new server property `storage.zfs_use_refquota` which instructs Incus
to set the `refquota` property instead of `quota` when setting a size limit
on a container. LXD will also then use `usedbydataset` in place of `used`
on a container. Incus will also then use `usedbydataset` in place of `used`
when being queried about disk utilization.
This effectively controls whether disk usage by snapshots should be
@ -132,7 +132,7 @@ options for the file system used by the LVM LV.
## `network`
Network management API for LXD.
Network management API for Incus.
This includes:
@ -214,11 +214,11 @@ Rules necessary for `dnsmasq` to work (DHCP/DNS) will always be applied if
## `network_routes`
Introduces `ipv4.routes` and `ipv6.routes` which allow routing additional subnets to a LXD bridge.
Introduces `ipv4.routes` and `ipv6.routes` which allow routing additional subnets to a Incus bridge.
## `storage`
Storage management API for LXD.
Storage management API for Incus.
This includes:
@ -250,7 +250,7 @@ Implements `DELETE` in `/1.0/containers/<name>/files`
## `file_append`
Implements the `X-LXD-write` header which can be one of `overwrite` or `append`.
Implements the `X-Incus-write` header which can be one of `overwrite` or `append`.
## `network_dhcp_expiry`
@ -268,7 +268,7 @@ Introduces the ability to rename a thin pool name by setting `storage.thinpool_n
This adds a new `vlan` property to `macvlan` network devices.
When set, this will instruct LXD to attach to the specified VLAN. LXD
When set, this will instruct Incus to attach to the specified VLAN. Incus
will look for an existing interface for that VLAN on the host. If one
can't be found it will create one itself and then use that as the
macvlan parent.
@ -281,7 +281,7 @@ be set at image creation/import time.
## `container_stateless_copy`
This introduces a new `live` attribute in `POST /1.0/containers/<name>`.
Setting it to `false` tells LXD not to attempt running state transfer.
Setting it to `false` tells Incus not to attempt running state transfer.
## `container_only_migration`
@ -347,21 +347,21 @@ UID/GID to use as the base.
## `file_symlinks`
This adds support for transferring symlinks through the file API.
X-LXD-type can now be `symlink` with the request content being the target path.
X-Incus-type can now be `symlink` with the request content being the target path.
## `container_push_target`
This adds the `target` field to `POST /1.0/containers/<name>` which can be
used to have the source LXD host connect to the target during migration.
used to have the source Incus host connect to the target during migration.
## `network_vlan_physical`
Allows use of `vlan` property with `physical` network devices.
When set, this will instruct LXD to attach to the specified VLAN on the `parent` interface.
LXD will look for an existing interface for that `parent` and VLAN on the host.
When set, this will instruct Incus to attach to the specified VLAN on the `parent` interface.
Incus will look for an existing interface for that `parent` and VLAN on the host.
If one can't be found it will create one itself.
Then, LXD will directly attach this interface to the container.
Then, Incus will directly attach this interface to the container.
## `storage_images_delete`
@ -389,17 +389,17 @@ This adds the ability to specify the Ceph user.
## `instance_types`
This adds the `instance_type` field to the container creation request.
Its value is expanded to LXD resource limits.
Its value is expanded to Incus resource limits.
## `storage_volatile_initial_source`
This records the actual source passed to LXD during storage pool creation.
This records the actual source passed to Incus during storage pool creation.
## `storage_ceph_force_osd_reuse`
This introduces the `ceph.osd.force_reuse` property for the Ceph storage
driver. When set to `true` LXD will reuse an OSD storage pool that is already in
use by another LXD instance.
driver. When set to `true` Incus will reuse an OSD storage pool that is already in
use by another Incus instance.
## `storage_block_filesystem_btrfs`
@ -408,7 +408,7 @@ and `xfs`.
## `resources`
This adds support for querying a LXD daemon for the system resources it has
This adds support for querying a Incus daemon for the system resources it has
available.
## `kernel_limits`
@ -432,7 +432,7 @@ This adds support to interact with the container console device and console log.
A new `security.devlxd` container configuration key was introduced.
The key controls whether the `/dev/lxd` interface is made available to the container.
If set to `false`, this effectively prevents the container from interacting with the LXD daemon.
If set to `false`, this effectively prevents the container from interacting with the Incus daemon.
## `migration_pre_copy`
@ -465,7 +465,7 @@ This makes it possible to retrieve symlinks using the file API.
## `network_leases`
Adds a new `/1.0/networks/NAME/leases` API endpoint to query the lease database on
bridges which run a LXD-managed DHCP server.
bridges which run a Incus-managed DHCP server.
## `unix_device_hotplug`
@ -482,7 +482,7 @@ Adds a `description` field to all operations.
## `clustering`
Clustering API for LXD.
Clustering API for Incus.
This includes the following new endpoints (see [RESTful API](rest-api.md) for details):
@ -551,12 +551,12 @@ The following existing endpoint has been modified:
Adds a `security.devlxd.images` configuration option for containers which
controls the availability of a `/1.0/images/FINGERPRINT/export` API over
`devlxd`. This can be used by a container running nested LXD to access raw
`devlxd`. This can be used by a container running nested Incus to access raw
images from the host.
## `container_local_cross_pool_handling`
This enables copying or moving containers between storage pools on the same LXD
This enables copying or moving containers between storage pools on the same Incus
instance.
## `proxy_unix`
@ -648,8 +648,8 @@ will be done via `iptables` instead of proxy devices.
## `network_nat_order`
This introduces the `ipv4.nat.order` and `ipv6.nat.order` configuration keys for LXD bridges.
Those keys control whether to put the LXD rules before or after any pre-existing rules in the chain.
This introduces the `ipv4.nat.order` and `ipv6.nat.order` configuration keys for Incus bridges.
Those keys control whether to put the Incus rules before or after any pre-existing rules in the chain.
## `container_full`
@ -702,7 +702,7 @@ attaching it to the container which requires write access.
Add a new project API, supporting creation, update and deletion of projects.
Projects can hold containers, profiles or images at this point and let
you get a separate view of your LXD resources by switching to it.
you get a separate view of your Incus resources by switching to it.
## `network_vxlan_ttl`
@ -832,7 +832,7 @@ This allows migrating storage volumes including their snapshots.
## `network_nat_address`
This introduces the `ipv4.nat.address` and `ipv6.nat.address` configuration keys for LXD bridges.
This introduces the `ipv4.nat.address` and `ipv6.nat.address` configuration keys for Incus bridges.
Those keys control the source address used for outbound traffic from the bridge.
## `container_nic_routes`
@ -843,13 +843,13 @@ This allows adding static routes on host to container's NIC.
## `cluster_internal_copy`
This makes it possible to do a normal `POST /1.0/containers` to copy a
container between cluster nodes with LXD internally detecting whether a
container between cluster nodes with Incus internally detecting whether a
migration is required.
## `seccomp_notify`
If the kernel supports `seccomp`-based syscall interception LXD can be notified
by a container that a registered syscall has been performed. LXD can then
If the kernel supports `seccomp`-based syscall interception Incus can be notified
by a container that a registered syscall has been performed. Incus can then
decide to trigger various actions.
## `lxc_features`
@ -904,7 +904,7 @@ Adds support for specifying `User`, `Group` and `Cwd` during `POST /1.0/containe
## `container_syscall_intercept`
Adds the `security.syscalls.intercept.*` configuration keys to control
what system calls will be intercepted by LXD and processed with
what system calls will be intercepted by Incus and processed with
elevated permissions.
## `container_disk_shift`
@ -981,7 +981,7 @@ in the pool specified by `pool_name`.
Adds the `security.syscalls.intercept.mount`,
`security.syscalls.intercept.mount.allowed`, and
`security.syscalls.intercept.mount.shift` configuration keys to control whether
and how the `mount` system call will be intercepted by LXD and processed with
and how the `mount` system call will be intercepted by Incus and processed with
elevated permissions.
## `compression_squashfs`
@ -1004,7 +1004,7 @@ redirect file-system mounts to their fuse implementation. To this end, set e.g.
## `container_disk_ceph`
This allows for existing a Ceph RBD or CephFS to be directly connected to a LXD container.
This allows for existing a Ceph RBD or CephFS to be directly connected to a Incus container.
## `virtual-machines`
@ -1057,14 +1057,14 @@ Adds the `Firewall` property to the `ServerEnvironment` struct indicating the fi
## `storage_lvm_vg_force_reuse`
Introduces the ability to create a storage pool from an existing non-empty volume group.
This option should be used with care, as LXD can then not guarantee that volume name conflicts won't occur
with non-LXD created volumes in the same volume group.
This could also potentially lead to LXD deleting a non-LXD volume should name conflicts occur.
This option should be used with care, as Incus can then not guarantee that volume name conflicts won't occur
with non-Incus created volumes in the same volume group.
This could also potentially lead to Incus deleting a non-Incus volume should name conflicts occur.
## `container_syscall_intercept_hugetlbfs`
When mount syscall interception is enabled and `hugetlbfs` is specified as an
allowed file system type LXD will mount a separate `hugetlbfs` instance for the
allowed file system type Incus will mount a separate `hugetlbfs` instance for the
container with the UID and GID mount options set to the container's root UID
and GID. This ensures that processes in the container can use huge pages.
@ -1396,7 +1396,7 @@ This introduces the `tpm` device type.
## `storage_zfs_clone_copy_rebase`
This introduces `rebase` as a value for `zfs.clone_copy` causing LXD to
This introduces `rebase` as a value for `zfs.clone_copy` causing Incus to
track down any `image` dataset in the ancestry line and then perform
send/receive on top of that.
@ -1536,7 +1536,7 @@ to specify what cluster member to place a workload on or the ability to move a w
## `images_default_architecture`
Adds new `images.default_architecture` global configuration key and matching per-project key which lets user tell LXD
Adds new `images.default_architecture` global configuration key and matching per-project key which lets user tell Incus
what architecture to go with when no specific one is specified as part of the image request.
## `network_ovn_acl_defaults`
@ -1562,7 +1562,7 @@ specifying the default behavior for unmatched traffic.
## `warnings`
Warning API for LXD.
Warning API for Incus.
This includes the following endpoints (see [Restful API](rest-api.md) for details):
@ -1588,7 +1588,7 @@ Adds an editable description to the cluster members.
## `server_trusted_proxy`
This introduces support for `core.https_trusted_proxy` which has LXD
This introduces support for `core.https_trusted_proxy` which has Incus
parse a HAProxy style connection header on such connections and if
present, will rewrite the request's source address to that provided by
the proxy server.
@ -1605,7 +1605,7 @@ This adds support for copy/move custom storage volumes between projects.
## `server_instance_driver_operational`
This modifies the `driver` output for the `/1.0` endpoint to only include drivers which are actually supported and
operational on the server (as opposed to being included in LXD but not operational on the server).
operational on the server (as opposed to being included in Incus but not operational on the server).
## `server_supported_storage_drivers`
@ -1626,13 +1626,13 @@ It also adds the configuration keys `cluster.evacuate` and `volatile.evacuate.or
## `network_ovn_nat_address`
This introduces the `ipv4.nat.address` and `ipv6.nat.address` configuration keys for LXD `ovn` networks.
This introduces the `ipv4.nat.address` and `ipv6.nat.address` configuration keys for Incus `ovn` networks.
Those keys control the source address used for outbound traffic from the OVN virtual network.
These keys can only be specified when the OVN network's uplink network has `ovn.ingress_mode=routed`.
## `network_bgp`
This introduces support for LXD acting as a BGP router to advertise
This introduces support for Incus acting as a BGP router to advertise
routes to `bridge` and `ovn` networks.
This comes with the addition to global configuration of:
@ -1672,7 +1672,7 @@ This adds the received and sent errors as well as inbound and outbound dropped p
## `metrics`
This adds metrics to LXD. It returns metrics of running instances using the OpenMetrics format.
This adds metrics to Incus. It returns metrics of running instances using the OpenMetrics format.
This includes the following endpoints:
@ -1698,7 +1698,7 @@ within containers.
## `network_dns`
Introduces a built-in DNS server and zones API to provide DNS records for LXD instances.
Introduces a built-in DNS server and zones API to provide DNS records for Incus instances.
This introduces the following server configuration key:
@ -1752,7 +1752,7 @@ This adds a new `cloud-init` configuration key namespace which contains the foll
This introduces `network.nat` as a configuration option on network zones (DNS).
It defaults to the current behavior of generating records for all
instances NICs but if set to `false`, it will instruct LXD to only
instances NICs but if set to `false`, it will instruct Incus to only
generate records for externally reachable addresses.
## `database_leader`
@ -1860,7 +1860,7 @@ Introduces a new `zfs.blocksize` property for ZFS storage volumes which allows t
## `metrics_cpu_seconds`
This is used to detect whether LXD was fixed to output used CPU time in seconds rather than as milliseconds.
This is used to detect whether Incus was fixed to output used CPU time in seconds rather than as milliseconds.
## `instance_snapshot_never`
@ -1968,7 +1968,7 @@ IP addresses that can be forwarded to one or more internal IP(s) inside their re
## `vsock_api`
This introduces a bidirectional `vsock` interface which allows the `lxd-agent` and the LXD server to communicate better.
This introduces a bidirectional `vsock` interface which allows the `lxd-agent` and the Incus server to communicate better.
## `instance_ready_state`
@ -2101,13 +2101,13 @@ Adds `GET /1.0/cluster/members/<member>/state` API endpoint and associated `Clus
## `instances_placement_scriptlet`
Adds support for a Starlark scriptlet to be provided to LXD to allow customized logic that controls placement of new instances in a cluster.
Adds support for a Starlark scriptlet to be provided to Incus to allow customized logic that controls placement of new instances in a cluster.
The Starlark scriptlet is provided to LXD via the new global configuration option `instances.placement.scriptlet`.
The Starlark scriptlet is provided to Incus via the new global configuration option `instances.placement.scriptlet`.
## `storage_pool_source_wipe`
Adds support for a `source.wipe` Boolean on the storage pool, indicating
that LXD should wipe partition headers off the requested disk rather
that Incus should wipe partition headers off the requested disk rather
than potentially fail due to pre-existing file systems.
## `zfs_block_mode`
@ -2204,7 +2204,7 @@ This introduces:
## `security_csm`
Introduce a new `security.csm` configuration key to control the use of
`CSM` (Compatibility Support Module) to allow legacy operating systems to
be run in LXD VMs.
be run in Incus VMs.
## `instances_rebuild`
This extension adds the ability to rebuild an instance with the same origin image, alternate image or as empty. A new `POST /1.0/instances/<name>/rebuild?project=<project>` API endpoint has been added as well as a new CLI command [`incus rebuild`](incus_rebuild.md).
@ -2222,7 +2222,7 @@ This adds the possibility to import ISO images as custom storage volumes.
This adds the `--type` flag to [`incus storage volume import`](incus_storage_volume_import.md).
## `network_allocations`
This adds the possibility to list a LXD deployment's network allocations.
This adds the possibility to list a Incus deployment's network allocations.
Through the [`incus network list-allocations`](incus_network_list-allocations.md) command and the `--project <PROJECT> | --all-projects` flags,
you can list all the used IP addresses, hardware addresses (for instances), resource URIs and whether it uses NAT for

8
doc/architectures.md
View File

@ -1,9 +1,9 @@
(architectures)=
# Architectures
LXD can run on just about any architecture that is supported by the Linux kernel and by Go.
Incus can run on just about any architecture that is supported by the Linux kernel and by Go.
Some entities in LXD are tied to an architecture, for example, the instances, instance snapshots and images.
Some entities in Incus are tied to an architecture, for example, the instances, instance snapshots and images.
The following table lists all supported architectures including their unique identifier and the name used to refer to them.
The architecture names are typically aligned with the Linux kernel architecture names.
@ -24,8 +24,8 @@ ID | Name | Notes | Personalities
12 | `riscv64` | 64bit RISC-V little-endian |
```{note}
LXD cares only about the kernel architecture, not the particular userspace flavor as determined by the toolchain.
Incus cares only about the kernel architecture, not the particular userspace flavor as determined by the toolchain.
That means that LXD considers ARMv7 hard-float to be the same as ARMv7 soft-float and refers to both as `armv7`.
That means that Incus considers ARMv7 hard-float to be the same as ARMv7 soft-float and refers to both as `armv7`.
If useful to the user, the exact userspace ABI may be set as an image and container property, allowing easy query.
```

42
doc/authentication.md
View File

@ -6,9 +6,9 @@ relatedlinks: https://www.youtube.com/watch?v=6O0q3rSWr8A
(authentication)=
# Remote API authentication
Remote communications with the LXD daemon happen using JSON over HTTPS.
Remote communications with the Incus daemon happen using JSON over HTTPS.
To be able to access the remote API, clients must authenticate with the LXD server.
To be able to access the remote API, clients must authenticate with the Incus server.
The following authentication methods are supported:
- {ref}`authentication-tls-certs`
@ -21,7 +21,7 @@ The following authentication methods are supported:
```
When using {abbr}`TLS (Transport Layer Security)` client certificates for authentication, both the client and the server will generate a key pair the first time they're launched.
The server will use that key pair for all HTTPS connections to the LXD socket.
The server will use that key pair for all HTTPS connections to the Incus socket.
The client will use its certificate as a client certificate for any client-server communication.
To cause certificates to be regenerated, simply remove the old ones.
@ -31,7 +31,7 @@ On the next connection, a new certificate is generated.
The supported protocol must be TLS 1.3 or better.
It's possible to force LXD to accept TLS 1.2 by setting the `LXD_INSECURE_TLS` environment variable on both client and server.
It's possible to force Incus to accept TLS 1.2 by setting the `Incus_INSECURE_TLS` environment variable on both client and server.
However this isn't a supported setup and should only ever be used when forced to use an outdated corporate proxy.
All communications must use perfect forward secrecy, and ciphers must be limited to strong elliptic curve ones (such as ECDHE-RSA or ECDHE-ECDSA).
@ -45,7 +45,7 @@ any backward compatibility to broken protocol or ciphers.
(authentication-trusted-clients)=
### Trusted TLS clients
You can obtain the list of TLS certificates trusted by a LXD server with [`incus config trust list`](incus_config_trust_list.md).
You can obtain the list of TLS certificates trusted by a Incus server with [`incus config trust list`](incus_config_trust_list.md).
Trusted clients can be added in either of the following ways:
@ -89,13 +89,13 @@ The clients can then add their certificates to the server's trust store by provi
<!-- Include start NAT authentication -->
```{note}
If your LXD server is behind NAT, you must specify its external public address when adding it as a remote for a client:
If your Incus server is behind NAT, you must specify its external public address when adding it as a remote for a client:
incus remote add <name> <IP_address>
When you are prompted for the admin password, specify the generated token.
When generating the token on the server, LXD includes a list of IP addresses that the client can use to access the server.
When generating the token on the server, Incus includes a list of IP addresses that the client can use to access the server.
However, if the server is behind NAT, these addresses might be local addresses that the client cannot connect to.
In this case, you must specify the external address manually.
```
@ -106,7 +106,7 @@ Alternatively, the clients can provide the token directly when adding the remote
### Using a PKI system
In a {abbr}`PKI (Public key infrastructure)` setup, a system administrator manages a central PKI that issues client certificates for all the LXD clients and server certificates for all the LXD daemons.
In a {abbr}`PKI (Public key infrastructure)` setup, a system administrator manages a central PKI that issues client certificates for all the Incus clients and server certificates for all the Incus daemons.
To enable PKI mode, complete the following steps:
@ -117,7 +117,7 @@ To enable PKI mode, complete the following steps:
1. Place the certificates issued by the CA on the clients and the server, replacing the automatically generated ones.
1. Restart the server.
In that mode, any connection to a LXD daemon will be done using the
In that mode, any connection to a Incus daemon will be done using the
pre-seeded CA certificate.
If the server certificate isn't signed by the CA, the connection will simply go through the normal authentication mechanism.
@ -128,38 +128,38 @@ Note that the generated certificates are not automatically trusted. You must sti
(authentication-openid)=
## OpenID Connect authentication
LXD supports using [OpenID Connect](https://openid.net/connect/) to authenticate users through an {abbr}`OIDC (OpenID Connect)` Identity Provider.
Incus supports using [OpenID Connect](https://openid.net/connect/) to authenticate users through an {abbr}`OIDC (OpenID Connect)` Identity Provider.
```{note}
OpenID Connect authentication is currently under development.
Starting with LXD 5.13, authentication through OpenID Connect is supported, but there is no user role handling in place so far.
Any user that authenticates through the configured OIDC Identity Provider gets full access to LXD.
Starting with Incus 5.13, authentication through OpenID Connect is supported, but there is no user role handling in place so far.
Any user that authenticates through the configured OIDC Identity Provider gets full access to Incus.
```
To configure LXD to use OIDC authentication, set the [`oidc.*`](server-options-oidc) server configuration options.
To configure Incus to use OIDC authentication, set the [`oidc.*`](server-options-oidc) server configuration options.
Your OIDC provider must be configured to enable the [Device Authorization Grant](https://oauth.net/2/device-flow/) type.
To add a remote pointing to a LXD server configured with OIDC authentication, run [`incus remote add <remote_name> <remote_address>`](incus_remote_add.md).
You are then prompted to authenticate through your web browser, where you must confirm the device code that LXD uses.
The LXD client then retrieves and stores the access and refresh tokens and provides those to LXD for all interactions.
To add a remote pointing to a Incus server configured with OIDC authentication, run [`incus remote add <remote_name> <remote_address>`](incus_remote_add.md).
You are then prompted to authenticate through your web browser, where you must confirm the device code that Incus uses.
The Incus client then retrieves and stores the access and refresh tokens and provides those to Incus for all interactions.
(authentication-server-certificate)=
## TLS server certificate
LXD supports issuing server certificates using {abbr}`ACME (Automatic Certificate Management Environment)` services, for example, [Let's Encrypt](https://letsencrypt.org/).
Incus supports issuing server certificates using {abbr}`ACME (Automatic Certificate Management Environment)` services, for example, [Let's Encrypt](https://letsencrypt.org/).
To enable this feature, set the following server configuration:
- {config:option}`server-acme:acme.domain`: The domain for which the certificate should be issued.
- {config:option}`server-acme:acme.email`: The email address used for the account of the ACME service.
- {config:option}`server-acme:acme.agree_tos`: Must be set to `true` to agree to the ACME service's terms of service.
- {config:option}`server-acme:acme.ca_url`: The directory URL of the ACME service. By default, LXD uses "Let's Encrypt".
- {config:option}`server-acme:acme.ca_url`: The directory URL of the ACME service. By default, Incus uses "Let's Encrypt".
For this feature to work, LXD must be reachable from port 80.
For this feature to work, Incus must be reachable from port 80.
This can be achieved by using a reverse proxy such as [HAProxy](http://www.haproxy.org/).
Here's a minimal HAProxy configuration that uses `lxd.example.net` as the domain.
After the certificate has been issued, LXD will be reachable from `https://lxd.example.net/`.
After the certificate has been issued, Incus will be reachable from `https://lxd.example.net/`.
```
# Global configuration
@ -223,7 +223,7 @@ frontend sni-dispatcher
default_backend http-403
use_backend lxd-nodes if { req.ssl_sni -i lxd.example.net }
# LXD nodes
# Incus nodes
backend lxd-nodes
mode tcp

34
doc/backup.md
View File

@ -1,19 +1,19 @@
(backups)=
# How to back up a LXD server
# How to back up a Incus server
```{youtube} https://www.youtube.com/watch?v=IFOZpAxckPo
```
In a production setup, you should always back up the contents of your LXD server.
In a production setup, you should always back up the contents of your Incus server.
The LXD server contains a variety of different entities, and when choosing your backup strategy, you must decide which of these entities you want to back up and how frequently you want to save them.
The Incus server contains a variety of different entities, and when choosing your backup strategy, you must decide which of these entities you want to back up and how frequently you want to save them.
## What to back up
The various contents of your LXD server are located on your file system and, in addition, recorded in the {ref}`LXD database <database>`.
The various contents of your Incus server are located on your file system and, in addition, recorded in the {ref}`Incus database <database>`.
Therefore, only backing up the database or only backing up the files on disk does not give you a full functional backup.
Your LXD server contains the following entities:
Your Incus server contains the following entities:
- Instances (database records and file systems)
- Images (database records, image files, and file systems)
@ -27,14 +27,14 @@ If you use only the `default` profile, or only the standard `lxdbr0` network bri
## Full backup
To create a full backup of all contents of your LXD server, back up the `/var/snap/lxd/common/lxd` (for snap users) or `/var/lib/lxd` (otherwise) directory.
To create a full backup of all contents of your Incus server, back up the `/var/snap/lxd/common/lxd` (for snap users) or `/var/lib/lxd` (otherwise) directory.
This directory contains your local storage, the LXD database, and your configuration.
This directory contains your local storage, the Incus database, and your configuration.
It does not contain separate storage devices, however.
That means that whether the directory also contains the data of your instances depends on the storage drivers that you use.
```{important}
If your LXD server uses any external storage (for example, LVM volume groups, ZFS zpools, or any other resource that isn't directly self-contained to LXD), you must back this up separately.
If your Incus server uses any external storage (for example, LVM volume groups, ZFS zpools, or any other resource that isn't directly self-contained to Incus), you must back this up separately.
See {ref}`howto-storage-backup-volume` for instructions.
```
@ -45,16 +45,16 @@ Restoring them avoids needless shifting of instance file systems.
To restore your data, complete the following steps:
1. Stop LXD on your server (for example, with `sudo snap stop lxd`).
1. Stop Incus on your server (for example, with `sudo snap stop lxd`).
1. Delete the directory (`/var/snap/lxd/common/lxd` for snap users or `/var/lib/lxd` otherwise).
1. Restore the directory from the backup.
1. Delete and restore any external storage devices.
1. If you are not using the snap, restore the `/etc/subuid` and `/etc/subgid` files.
1. Restart LXD (for example, with `sudo snap start lxd` or by restarting your machine).
1. Restart Incus (for example, with `sudo snap start lxd` or by restarting your machine).
### Export a snapshot
If you are using the LXD snap, you can also create a full backup by exporting a snapshot of the snap:
If you are using the Incus snap, you can also create a full backup by exporting a snapshot of the snap:
1. Create a snapshot:
@ -71,7 +71,7 @@ See [Snapshots](https://snapcraft.io/docs/snapshots) in the Snapcraft documentat
If you decide to only back up specific entities, you have different options for how to do this.
You should consider doing some of these partial backups even if you are doing full backups in addition.
It can be easier and safer to, for example, restore a single instance or reconfigure a profile than to restore the full LXD server.
It can be easier and safer to, for example, restore a single instance or reconfigure a profile than to restore the full Incus server.
### Back up instances and volumes
@ -80,15 +80,15 @@ Instances and storage volumes are backed up in a very similar way (because when
See {ref}`instances-backup` and {ref}`howto-storage-backup-volume` for detailed information.
The following sections give a brief summary of the options you have for backing up instances and volumes.
#### Secondary backup LXD server
#### Secondary backup Incus server
LXD supports copying and moving instances and storage volumes between two hosts.
Incus supports copying and moving instances and storage volumes between two hosts.
See {ref}`move-instances` and {ref}`howto-storage-move-volume` for instructions.
So if you have a spare server, you can regularly copy your instances and storage volumes to that secondary server to back them up.
If needed, you can either switch over to the secondary server or copy your instances or storage volumes back from it.
If you use the secondary server as a pure storage server, it doesn't need to be as powerful as your main LXD server.
If you use the secondary server as a pure storage server, it doesn't need to be as powerful as your main Incus server.
#### Export tarballs
@ -111,7 +111,7 @@ See {ref}`instances-snapshots` and {ref}`storage-backup-snapshots` for more info
(backup-database)=
### Back up the database
While there is no trivial method to restore the contents of the {ref}`LXD database <database>`, it can still be very convenient to keep a backup of its content.
While there is no trivial method to restore the contents of the {ref}`Incus database <database>`, it can still be very convenient to keep a backup of its content.
Such a backup can make it much easier to re-create, for example, networks or profiles if the need arises.
Use the following command to dump the content of the local database to a file:
@ -122,4 +122,4 @@ Use the following command to dump the content of the global database to a file:
incus admin sql global .dump > <output_file>
You should include these two commands in your regular LXD backup.
You should include these two commands in your regular Incus backup.

6
doc/cloud-init.md
View File

@ -38,7 +38,7 @@ To use `cloud-init`, you must base your instance on an image that has `cloud-ini
## Configuration options
LXD supports two different sets of configuration options for configuring `cloud-init`: `cloud-init.*` and `user.*`.
Incus supports two different sets of configuration options for configuring `cloud-init`: `cloud-init.*` and `user.*`.
Which of these sets you must use depends on the `cloud-init` support in the image that you use.
As a rule of thumb, newer images support the `cloud-init.*` configuration options, while older images support `user.*`.
However, there might be exceptions to that rule.
@ -49,7 +49,7 @@ The following configuration options are supported:
* `cloud-init.user-data` or `user.user-data` (see {ref}`cloud-init:user_data_formats`)
* `cloud-init.network-config` or `user.network-config` (see {ref}`cloud-init:network_config`)
For more information about the configuration options, see the [`cloud-init` instance options](instance-options-cloud-init), and the documentation for the {ref}`LXD data source <cloud-init:datasource_lxd>` in the `cloud-init` documentation.
For more information about the configuration options, see the [`cloud-init` instance options](instance-options-cloud-init), and the documentation for the {ref}`Incus data source <cloud-init:datasource_lxd>` in the `cloud-init` documentation.
### Vendor data and user data
@ -57,7 +57,7 @@ Both `vendor-data` and `user-data` are used to provide {ref}`cloud configuration
The main idea is that `vendor-data` is used for the general default configuration, while `user-data` is used for instance-specific configuration.
This means that you should specify `vendor-data` in a profile and `user-data` in the instance configuration.
LXD does not enforce this method, but allows using both `vendor-data` and `user-data` in profiles and in the instance configuration.
Incus does not enforce this method, but allows using both `vendor-data` and `user-data` in profiles and in the instance configuration.
If both `vendor-data` and `user-data` are supplied for an instance, `cloud-init` merges the two configurations.
However, if you use the same keys in both configurations, merging might not be possible.

14
doc/container-environment.md
View File

@ -1,13 +1,13 @@
(container-runtime-environment)=
# Container runtime environment
LXD attempts to present a consistent environment to all containers it runs.
Incus attempts to present a consistent environment to all containers it runs.
The exact environment will differ slightly based on kernel features and user configuration, but otherwise, it is identical for all containers.
## File system
LXD assumes that any image it uses to create a new container comes with at least the following root-level directories:
Incus assumes that any image it uses to create a new container comes with at least the following root-level directories:
- `/dev` (empty)
- `/proc` (empty)
@ -16,7 +16,7 @@ LXD assumes that any image it uses to create a new container comes with at least
## Devices
LXD containers have a minimal and ephemeral `/dev` based on a `tmpfs` file system.
Incus containers have a minimal and ephemeral `/dev` based on a `tmpfs` file system.
Since this is a `tmpfs` and not a `devtmpfs` file system, device nodes appear only if manually created.
The following standard set of device nodes is set up automatically:
@ -43,12 +43,12 @@ In addition to the standard set of devices, the following devices are also set u
### Network
LXD containers may have any number of network devices attached to them.
Incus containers may have any number of network devices attached to them.
The naming for those (unless overridden by the user) is `ethX`, where `X` is an incrementing number.
### Container-to-host communication
LXD sets up a socket at `/dev/lxd/sock` that the root user in the container can use to communicate with LXD on the host.
Incus sets up a socket at `/dev/lxd/sock` that the root user in the container can use to communicate with Incus on the host.
See {doc}`dev-incus` for the API documentation.
@ -83,10 +83,10 @@ On older kernels, a virtual version of `/sys/fs/cgroup` might also be set up by
## PID1
LXD spawns whatever is located at `/sbin/init` as the initial process of the container (PID 1).
Incus spawns whatever is located at `/sbin/init` as the initial process of the container (PID 1).
This binary should act as a proper init system, including handling re-parented processes.
LXD's communication with PID1 in the container is limited to two signals:
Incus's communication with PID1 in the container is limited to two signals:
- `SIGINT` to trigger a reboot of the container
- `SIGPWR` (or alternatively `SIGRTMIN`+3) to trigger a clean shutdown of the container

20
doc/contributing.md
View File

@ -9,9 +9,9 @@ relatedlinks: https://www.youtube.com/watch?v=pqV0Z1qwbkg
## Contribute to the code
Follow the steps below to set up your development environment to get started working on new features for LXD.
Follow the steps below to set up your development environment to get started working on new features for Incus.
### Install LXD from source
### Install Incus from source
To build the dependencies, follow the instructions in {ref}`installing_from_source`.
@ -26,7 +26,7 @@ Then switch to it:
git checkout myfork/main
### Build LXD
### Build Incus
Finally, you should be able to run `make` inside the repository and build your fork of the project.
@ -37,20 +37,20 @@ git checkout -b [name_of_your_new_branch]
git push myfork [name_of_your_new_branch]
```
### Important notes for new LXD contributors
### Important notes for new Incus contributors
- Persistent data is stored in the `LXD_DIR` directory, which is generated by `incus admin init`.
The `LXD_DIR` defaults to `/var/lib/lxd`, or `/var/snap/lxd/common/lxd` for snap users.
- As you develop, you may want to change the `LXD_DIR` for your fork of LXD so as to avoid version conflicts.
- Persistent data is stored in the `Incus_DIR` directory, which is generated by `incus admin init`.
The `Incus_DIR` defaults to `/var/lib/lxd`, or `/var/snap/lxd/common/lxd` for snap users.
- As you develop, you may want to change the `Incus_DIR` for your fork of Incus so as to avoid version conflicts.
- Binaries compiled from your source will be generated in the `$(go env GOPATH)/bin` directory by default.
- You will need to explicitly invoke these binaries (not the global `lxd` you may have installed) when testing your changes.
- You may choose to create an alias in your `~/.bashrc` to call these binaries with the appropriate flags more conveniently.
- If you have a `systemd` service configured to run the LXD daemon from a previous installation of LXD, you may want to disable it to avoid version conflicts.
- If you have a `systemd` service configured to run the Incus daemon from a previous installation of Incus, you may want to disable it to avoid version conflicts.
## Contribute to the documentation
We want LXD to be as easy and straight-forward to use as possible.
Therefore, we aim to provide documentation that contains the information that users need to work with LXD, that covers all common use cases, and that answers typical questions.
We want Incus to be as easy and straight-forward to use as possible.
Therefore, we aim to provide documentation that contains the information that users need to work with Incus, that covers all common use cases, and that answers typical questions.
You can contribute to the documentation in various different ways.
We appreciate your contributions!

16
doc/daemon-behavior.md
View File

@ -5,34 +5,34 @@ This specification covers some of the Incus daemon's behavior.
## Startup
On every start, LXD checks that its directory structure exists. If it
On every start, Incus checks that its directory structure exists. If it
doesn't, it creates the required directories, generates a key pair and
initializes the database.
Once the daemon is ready for work, LXD scans the instances table
Once the daemon is ready for work, Incus scans the instances table
for any instance for which the stored power state differs from the
current one. If an instance's power state was recorded as running and the
instance isn't running, LXD starts it.
instance isn't running, Incus starts it.
## Signal handling
### `SIGINT`, `SIGQUIT`, `SIGTERM`
For those signals, LXD assumes that it's being temporarily stopped and
For those signals, Incus assumes that it's being temporarily stopped and
will be restarted at a later time to continue handling the instances.
The instances will keep running and LXD will close all connections and
The instances will keep running and Incus will close all connections and
exit cleanly.
### `SIGPWR`
Indicates to LXD that the host is going down.
Indicates to Incus that the host is going down.
LXD will attempt a clean shutdown of all the instances. After 30 seconds, it
Incus will attempt a clean shutdown of all the instances. After 30 seconds, it
kills any remaining instance.
The instance `power_state` in the instances table is kept as it was so
that LXD can restore the instances as they were after the host is done rebooting.
that Incus can restore the instances as they were after the host is done rebooting.
### `SIGUSR1`

18
doc/database.md
View File

@ -3,9 +3,9 @@ relatedlinks: "[Canonical&#32;Dqlite](https://dqlite.io/), https://github.com/ca
---
(database)=
# About the LXD database
# About the Incus database
LXD uses a distributed database to store the server configuration and state, which allows for quicker queries than if the configuration was stored inside each instance's directory (as it is done by LXC, for example).
Incus uses a distributed database to store the server configuration and state, which allows for quicker queries than if the configuration was stored inside each instance's directory (as it is done by LXC, for example).
To understand the advantages, consider a query against the configuration of all instances, like "what instances are using `br0`?".
To answer that question without a database, you would have to iterate through every single instance, load and parse its configuration, and then check which network devices are defined in there.
@ -13,20 +13,20 @@ With a database, you can run a simple query on the database to retrieve this inf
## Dqlite
In a LXD cluster, all members of the cluster must share the same database state.
Therefore, LXD uses [Dqlite](https://dqlite.io/), a distributed version of SQLite.
In a Incus cluster, all members of the cluster must share the same database state.
Therefore, Incus uses [Dqlite](https://dqlite.io/), a distributed version of SQLite.
Dqlite provides replication, fault-tolerance, and automatic failover without the need of external database processes.
When using LXD as a single machine and not as a cluster, the Dqlite database effectively behaves like a regular SQLite database.
When using Incus as a single machine and not as a cluster, the Dqlite database effectively behaves like a regular SQLite database.
## File location
The database files are stored in the `database` sub-directory of your LXD data directory (thus `/var/snap/lxd/common/lxd/database/` if you use the snap, or `/var/lib/lxd/database/` otherwise).
The database files are stored in the `database` sub-directory of your Incus data directory (thus `/var/snap/lxd/common/lxd/database/` if you use the snap, or `/var/lib/lxd/database/` otherwise).
Upgrading LXD to a newer version might require updating the database schema.
In this case, LXD automatically stores a backup of the database and then runs the update.
Upgrading Incus to a newer version might require updating the database schema.
In this case, Incus automatically stores a backup of the database and then runs the update.
See {ref}`installing-upgrade` for more information.
## Backup
See {ref}`backup-database` for instructions on how to back up the contents of the LXD database.
See {ref}`backup-database` for instructions on how to back up the contents of the Incus database.

22
doc/debugging.md
View File

@ -1,4 +1,4 @@
# How to debug LXD
# How to debug Incus
For information on debugging instance issues, see {ref}`instances-troubleshoot`.
@ -20,7 +20,7 @@ This command will monitor messages as they appear on remote server.
## REST API through local socket
On server side the most easy way is to communicate with LXD through
On server side the most easy way is to communicate with Incus through
local socket. This command accesses `GET /1.0` and formats JSON into
human readable form using [jq](https://stedolan.github.io/jq/tutorial/)
utility:
@ -39,7 +39,7 @@ See the [RESTful API](rest-api.md) for available API.
## REST API through HTTPS
{ref}`HTTPS connection to LXD <security>` requires valid
{ref}`HTTPS connection to Incus <security>` requires valid
client certificate that is generated on first [`incus remote add`](incus_remote_add.md). This
certificate should be passed to connection tools for authentication
and encryption.
@ -68,7 +68,7 @@ wget --no-check-certificate --certificate=$HOME/snap/lxd/common/config/client.cr
### With browser
Some browser plugins provide convenient interface to create, modify
and replay web requests. To authenticate against LXD server, convert
and replay web requests. To authenticate against Incus server, convert
`lxc` client certificate into importable format and import it into
browser.
@ -80,14 +80,14 @@ openssl pkcs12 -clcerts -inkey client.key -in client.crt -export -out client.pfx
After that, opening [`https://127.0.0.1:8443/1.0`](https://127.0.0.1:8443/1.0) should work as expected.
## Debug the LXD database
## Debug the Incus database
The files of the global {ref}`database <database>` are stored under the `./database/global`
sub-directory of your LXD data directory (e.g. `/var/lib/lxd/database/global` or
sub-directory of your Incus data directory (e.g. `/var/lib/lxd/database/global` or
`/var/snap/lxd/common/lxd/database/global` for snap users).
Since each member of the cluster also needs to keep some data which is specific
to that member, LXD also uses a plain SQLite database (the "local" database),
to that member, Incus also uses a plain SQLite database (the "local" database),
which you can find in `./database/local.db`.
Backups of the global database directory and of the local database file are made
@ -108,13 +108,13 @@ against the local or global database, you can use the `incus admin sql` command
`incus admin sql --help` for details).
You should only need to do that in order to recover from broken updates or bugs.
Please consult the LXD team first (creating a [GitHub
Please consult the Incus team first (creating a [GitHub
issue](https://github.com/canonical/lxd/issues/new) or
[forum](https://discourse.ubuntu.com/c/lxd/) post).
### Running custom queries at LXD daemon startup
### Running custom queries at Incus daemon startup
In case the LXD daemon fails to start after an upgrade because of SQL data
In case the Incus daemon fails to start after an upgrade because of SQL data
migration bugs or similar problems, it's possible to recover the situation by
creating `.sql` files containing queries that repair the broken update.
@ -126,7 +126,7 @@ Those files will be loaded very early in the daemon startup sequence and deleted
if the queries were successful (if they fail, no state will change as they are
run in a SQL transaction).
As above, please consult the LXD team first.
As above, please consult the Incus team first.
### Syncing the cluster database to disk

16
doc/dev-incus.md
View File

@ -7,8 +7,8 @@
Communication between the hosted workload (instance) and its host while
not strictly needed is a pretty useful feature.
In LXD, this feature is implemented through a `/dev/lxd/sock` node which is
created and set up for all LXD instances.
In Incus, this feature is implemented through a `/dev/lxd/sock` node which is
created and set up for all Incus instances.
This file is a Unix socket which processes inside the instance can
connect to. It's multi-threaded so multiple clients can be connected at the
@ -20,29 +20,29 @@ same time.
## Implementation details
LXD on the host binds `/var/lib/lxd/devlxd/sock` and starts listening for new
Incus on the host binds `/var/lib/lxd/devlxd/sock` and starts listening for new
connections on it.
This socket is then exposed into every single instance started by
LXD at `/dev/lxd/sock`.
Incus at `/dev/lxd/sock`.
The single socket is required so we can exceed 4096 instances, otherwise,
LXD would have to bind a different socket for every instance, quickly
Incus would have to bind a different socket for every instance, quickly
reaching the FD limit.
## Authentication
Queries on `/dev/lxd/sock` will only return information related to the
requesting instance. To figure out where a request comes from, LXD will
requesting instance. To figure out where a request comes from, Incus will
extract the initial socket's user credentials and compare that to the list of
instances it manages.
## Protocol
The protocol on `/dev/lxd/sock` is plain-text HTTP with JSON messaging, so very
similar to the local version of the LXD protocol.
similar to the local version of the Incus protocol.
Unlike the main LXD API, there is no background operation and no
Unlike the main Incus API, there is no background operation and no
authentication support in the `/dev/lxd/sock` API.
## REST-API

16
doc/doc-cheat-sheet.md
View File

@ -153,8 +153,8 @@ For external links, use only the URL, or Markdown syntax if you want to override
- Output
* - `https://ubuntu.com/lxd`
- [{spellexception}`https://ubuntu.com/lxd`](https://ubuntu.com/lxd)
* - `[LXD](https://ubuntu.com/lxd)`
- [LXD](https://ubuntu.com/lxd)
* - `[Incus](https://ubuntu.com/lxd)`
- [Incus](https://ubuntu.com/lxd)
```
To display a URL as text and prevent it from being linked, add a `<span></span>`:
@ -192,13 +192,13 @@ To reference a documentation page, use MyST syntax to automatically extract the
- [](index)
-
- Do not use.
* - `[LXD documentation](index)`
- [LXD documentation](index)
- [LXD documentation](index)
* - `[Incus documentation](index)`
- [Incus documentation](index)
- [Incus documentation](index)
- Preferred when overriding the link text.
* - `` {doc}`LXD documentation <index>` ``
- {doc}`LXD documentation <index>`
- {doc}<span></span>`LXD documentation <index>`
* - `` {doc}`Incus documentation <index>` ``
- {doc}`Incus documentation <index>`
- {doc}<span></span>`Incus documentation <index>`
- Alternative when overriding the link text.
```

6
doc/events.md
View File

@ -2,16 +2,16 @@
## Introduction
Events are messages about actions that have occurred over LXD. Using the API endpoint `/1.0/events` directly or via
Events are messages about actions that have occurred over Incus. Using the API endpoint `/1.0/events` directly or via
[`incus monitor`](incus_monitor.md) will connect to a WebSocket through which logs and life-cycle messages will be streamed.
## Event types
LXD Currently supports three event types.
Incus Currently supports three event types.
- `logging`: Shows all logging messages regardless of the server logging level.
- `operation`: Shows all ongoing operations from creation to completion (including updates to their state and progress metadata).
- `lifecycle`: Shows an audit trail for specific actions occurring over LXD.
- `lifecycle`: Shows an audit trail for specific actions occurring over Incus.
## Event structure

52
doc/explanation/clustering.md
View File

@ -8,20 +8,20 @@ discourse: 15728
```{youtube} https://www.youtube.com/watch?v=nrOR6yaO_MY
```
To spread the total workload over several servers, LXD can be run in clustering mode.
In this scenario, any number of LXD servers share the same distributed database that holds the configuration for the cluster members and their instances.
The LXD cluster can be managed uniformly using the [`lxc`](incus.md) client or the REST API.
To spread the total workload over several servers, Incus can be run in clustering mode.
In this scenario, any number of Incus servers share the same distributed database that holds the configuration for the cluster members and their instances.
The Incus cluster can be managed uniformly using the [`lxc`](incus.md) client or the REST API.
This feature was introduced as part of the [`clustering`](../api-extensions.md#clustering) API extension and is available since LXD 3.0.
This feature was introduced as part of the [`clustering`](../api-extensions.md#clustering) API extension and is available since Incus 3.0.
```{tip}
If you want to quickly set up a basic LXD cluster, check out [MicroCloud](https://microcloud.is).
If you want to quickly set up a basic Incus cluster, check out [MicroCloud](https://microcloud.is).
```
(clustering-members)=
## Cluster members
A LXD cluster consists of one bootstrap server and at least two further cluster members.
A Incus cluster consists of one bootstrap server and at least two further cluster members.
It stores its state in a [distributed database](../database.md), which is a [Dqlite](https://dqlite.io/) database replicated using the Raft algorithm.
While you could create a cluster with only two members, it is strongly recommended that the number of cluster members be at least three.
@ -46,15 +46,15 @@ If the cluster leader goes offline, one of the voters is elected as the new lead
If a voter member goes offline, a stand-by member is automatically promoted to voter.
The database (and hence the cluster) remains available as long as a majority of voters is online.
The following roles can be assigned to LXD cluster members.
Automatic roles are assigned by LXD itself and cannot be modified by the user.
The following roles can be assigned to Incus cluster members.
Automatic roles are assigned by Incus itself and cannot be modified by the user.
| Role | Automatic | Description |
| :--- | :-------- | :---------- |
| `database` | yes | Voting member of the distributed database |
| `database-leader` | yes | Current leader of the distributed database |
| `database-standby` | yes | Stand-by (non-voting) member of the distributed database |
| `event-hub` | no | Exchange point (hub) for the internal LXD events (requires at least two) |
| `event-hub` | no | Exchange point (hub) for the internal Incus events (requires at least two) |
| `ovn-chassis` | no | Uplink gateway candidate for OVN networks |
The default number of voter members ({config:option}`server-cluster:cluster.max_voters`) is three.
@ -86,15 +86,15 @@ See {ref}`cluster-recover` for more information.
#### Failure domains
You can use failure domains to indicate which cluster members should be given preference when assigning roles to a cluster member that has gone offline.
For example, if a cluster member that currently has the database role gets shut down, LXD tries to assign its database role to another cluster member in the same failure domain, if one is available.
For example, if a cluster member that currently has the database role gets shut down, Incus tries to assign its database role to another cluster member in the same failure domain, if one is available.
To update the failure domain of a cluster member, use the [`incus cluster edit <member>`](incus_cluster_edit.md) command and change the `failure_domain` property from `default` to another string.
(clustering-member-config)=
### Member configuration
LXD cluster members are generally assumed to be identical systems.
This means that all LXD servers joining a cluster must have an identical configuration to the bootstrap server, in terms of storage pools and networks.
Incus cluster members are generally assumed to be identical systems.
This means that all Incus servers joining a cluster must have an identical configuration to the bootstrap server, in terms of storage pools and networks.
To accommodate things like slightly different disk ordering or network interface naming, there is an exception for some configuration options related to storage and networks, which are member-specific.
@ -115,7 +115,7 @@ This can be done through `incus query /1.0/cluster` or through other API clients
## Images
By default, LXD replicates images on as many cluster members as there are database members.
By default, Incus replicates images on as many cluster members as there are database members.
This typically means up to three copies within the cluster.
You can increase that number to improve fault tolerance and the likelihood of the image being locally available.
@ -125,7 +125,7 @@ The special value of `-1` can be used to have the image copied to all cluster me
(cluster-groups)=
## Cluster groups
In a LXD cluster, you can add members to cluster groups.
In a Incus cluster, you can add members to cluster groups.
You can use these cluster groups to launch instances on a cluster member that belongs to a subset of all available members.
For example, you could create a cluster group for all members that have a GPU and then launch all instances that require a GPU on this cluster group.
@ -137,7 +137,7 @@ See {ref}`howto-cluster-groups` and {ref}`cluster-target-instance` for more info
## Automatic placement of instances
In a cluster setup, each instance lives on one of the cluster members.
When you launch an instance, you can target it to a specific cluster member, to a cluster group or have LXD automatically assign it to a cluster member.
When you launch an instance, you can target it to a specific cluster member, to a cluster group or have Incus automatically assign it to a cluster member.
By default, the automatic assignment picks the cluster member that has the lowest number of instances.
If several members have the same amount of instances, one of the members is chosen at random.
@ -162,11 +162,11 @@ However, you can control this behavior with the {config:option}`cluster-cluster:
(clustering-instance-placement-scriptlet)=
### Instance placement scriptlet
LXD supports using custom logic to control automatic instance placement by using an embedded script (scriptlet).
Incus supports using custom logic to control automatic instance placement by using an embedded script (scriptlet).
This method provides more flexibility than the built-in instance placement functionality.
The instance placement scriptlet must be written in the [Starlark language](https://github.com/bazelbuild/starlark) (which is a subset of Python).
The scriptlet is invoked each time LXD needs to know where to place an instance.
The scriptlet is invoked each time Incus needs to know where to place an instance.
The scriptlet receives information about the instance that is being placed and the candidate cluster members that could host the instance.
It is also possible for the scriptlet to request information about each candidate cluster member's state and the hardware resources available.
@ -181,12 +181,12 @@ For example:
```python
def instance_placement(request, candidate_members):
# Example of logging info, this will appear in LXD's log.
# Example of logging info, this will appear in Incus's log.
log_info("instance placement started: ", request)
# Example of applying logic based on the instance request.
if request.name == "foo":
# Example of logging an error, this will appear in LXD's log.
# Example of logging an error, this will appear in Incus's log.
log_error("Invalid name supplied: ", request.name)
fail("Invalid name") # Exit with an error to reject instance placement.
@ -197,20 +197,20 @@ 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 Incus by storing it in the `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:
For example, if the scriptlet is saved inside a file called `instance_placement.star`, then it can be applied to Incus with the following command:
cat instance_placement.star | incus config set instances.placement.scriptlet=-
To see the current scriptlet applied to LXD, use the `incus config get instances.placement.scriptlet` command.
To see the current scriptlet applied to Incus, use the `incus config get instances.placement.scriptlet` command.
The following functions are available to the scriptlet (in addition to those provided by Starlark):
- `log_info(*messages)`: Add a log entry to LXD's log at `info` level. `messages` is one or more message arguments.
- `log_warn(*messages)`: Add a log entry to LXD's log at `warn` level. `messages` is one or more message arguments.
- `log_error(*messages)`: Add a log entry to LXD's log at `error` level. `messages` is one or more message arguments.
- `set_cluster_member_target(member_name)`: Set the cluster member where the instance should be created. `member_name` is the name of the cluster member the instance should be created on. If this function is not called, then LXD will use its built-in instance placement logic.
- `log_info(*messages)`: Add a log entry to Incus's log at `info` level. `messages` is one or more message arguments.
- `log_warn(*messages)`: Add a log entry to Incus's log at `warn` level. `messages` is one or more message arguments.
- `log_error(*messages)`: Add a log entry to Incus's log at `error` level. `messages` is one or more message arguments.
- `set_cluster_member_target(member_name)`: Set the cluster member where the instance should be created. `member_name` is the name of the cluster member the instance should be created on. If this function is not called, then Incus will use its built-in instance placement logic.
- `get_cluster_member_state(member_name)`: Get the cluster member's state. Returns an object with the cluster member's state in the form of [`api.ClusterMemberState`](https://pkg.go.dev/github.com/canonical/lxd/shared/api#ClusterMemberState). `member_name` is the name of the cluster member to get the state for.
- `get_cluster_member_resources(member_name)`: Get information about resources on the cluster member. Returns an object with the resource information in the form of [`api.Resources`](https://pkg.go.dev/github.com/canonical/lxd/shared/api#Resources). `member_name` is the name of the cluster member to get the resource information for.
- `get_instance_resources()`: Get information about the resources the instance will require. Returns an object with the resource information in the form of [`scriptlet.InstanceResources`](https://pkg.go.dev/github.com/canonical/lxd/shared/api/scriptlet/#InstanceResources).

8
doc/explanation/containers_and_vms.md
View File

@ -1,11 +1,11 @@
(containers-and-vms)=
# About containers and VMs
LXD provides support for two different types of {ref}`instances <expl-instances>`: *system containers* and *virtual machines*.
Incus provides support for two different types of {ref}`instances <expl-instances>`: *system containers* and *virtual machines*.
When running a system container, LXD simulates a virtual version of a full operating system. To do this, it uses the functionality provided by the kernel running on the host system.
When running a system container, Incus simulates a virtual version of a full operating system. To do this, it uses the functionality provided by the kernel running on the host system.
When running a virtual machine, LXD uses the hardware of the host system, but the kernel is provided by the virtual machine. Therefore, virtual machines can be used to run, for example, a different operating system.
When running a virtual machine, Incus uses the hardware of the host system, but the kernel is provided by the virtual machine. Therefore, virtual machines can be used to run, for example, a different operating system.
## Application containers vs. system containers
@ -19,6 +19,6 @@ Therefore, application containers are suitable to provide separate components, w
Virtual machines emulate a physical machine, using the hardware of the host system from a full and completely isolated operating system. System containers, on the other hand, use the OS kernel of the host system instead of creating their own environment. If you run several system containers, they all share the same kernel, which makes them faster and more light-weight than virtual machines.
With LXD, you can create both system containers and virtual machines. You should use a system container to leverage the smaller size and increased performance if all functionality you require is compatible with the kernel of your host operating system. If you need functionality that is not supported by the OS kernel of your host system or you want to run a completely different OS, use a virtual machine.
With Incus, you can create both system containers and virtual machines. You should use a system container to leverage the smaller size and increased performance if all functionality you require is compatible with the kernel of your host operating system. If you need functionality that is not supported by the OS kernel of your host system or you want to run a completely different OS, use a virtual machine.
![Virtual machines and system containers](/images/virtual-machines-vs-system-containers.svg "Virtual machines and system containers")

8
doc/explanation/instances.md
View File

@ -6,19 +6,19 @@ relatedlinks: https://ubuntu.com/blog/lxd-virtual-machines-an-overview
(expl-instances)=
# About instances
LXD supports the following types of instances:
Incus supports the following types of instances:
Containers
: Containers are the default type for instances.
They are currently the most complete implementation of LXD instances and support more features than virtual machines.
They are currently the most complete implementation of Incus instances and support more features than virtual machines.
Containers are implemented through the use of `liblxc` (LXC).
Virtual machines
: {abbr}`Virtual machines (VMs)` are natively supported since version 4.0 of LXD.
: {abbr}`Virtual machines (VMs)` are natively supported since version 4.0 of Incus.
Thanks to a built-in agent, they can be used almost like containers.
LXD uses `qemu` to provide the VM functionality.
Incus uses `qemu` to provide the VM functionality.
```{note}
Currently, virtual machines support fewer features than containers, but the plan is to support the same set of features for both instance types in the future.

34
doc/explanation/networks.md
View File

@ -1,22 +1,22 @@
(networks)=
# About networking
There are different ways to connect your instances to the Internet. The easiest method is to have LXD create a network bridge during initialization and use this bridge for all instances, but LXD supports many different and advanced setups for networking.
There are different ways to connect your instances to the Internet. The easiest method is to have Incus create a network bridge during initialization and use this bridge for all instances, but Incus supports many different and advanced setups for networking.
## Network devices
To grant direct network access to an instance, you must assign it at least one network device, also called {abbr}`NIC (Network Interface Controller)`.
You can configure the network device in one of the following ways:
- Use the default network bridge that you set up during the LXD initialization.
- Use the default network bridge that you set up during the Incus initialization.
Check the default profile to see the default configuration:
incus profile show default
This method is used if you do not specify a network device for your instance.
- Use an existing network interface by adding it as a network device to your instance.
This network interface is outside of LXD control.
Therefore, you must specify all information that LXD needs to use the network interface.
This network interface is outside of Incus control.
Therefore, you must specify all information that Incus needs to use the network interface.
Use a command similar to the following:
@ -28,7 +28,7 @@ You can configure the network device in one of the following ways:
incus config device add <instance_name> eth0 nic nictype=bridged parent=br0
- {doc}`Create a managed network </howto/network_create>` and add it as a network device to your instance.
With this method, LXD has all required information about the configured network, and you can directly attach it to your instance as a device:
With this method, Incus has all required information about the configured network, and you can directly attach it to your instance as a device:
incus network attach <network_name> <instance_name> <device_name>
@ -37,18 +37,18 @@ You can configure the network device in one of the following ways:
(managed-networks)=
## Managed networks
Managed networks in LXD are created and configured with the `incus network [create|edit|set]` command.
Managed networks in Incus are created and configured with the `incus network [create|edit|set]` command.
Depending on the network type, LXD either fully controls the network or just manages an external network interface.
Depending on the network type, Incus either fully controls the network or just manages an external network interface.
Note that not all {ref}`NIC types <devices-nic>` are supported as network types.
LXD can only set up some of the types as managed networks.
Incus can only set up some of the types as managed networks.
### Fully controlled networks
Fully controlled networks create network interfaces and provide most functionality, including, for example, the ability to do IP management.
LXD supports the following network types:
Incus supports the following network types:
{ref}`network-bridge`
: % Include content from [../reference/network_bridge.md](../reference/network_bridge.md)
@ -57,7 +57,7 @@ LXD supports the following network types:
:end-before: <!-- Include end bridge intro -->
```
In LXD context, the `bridge` network type creates an L2 bridge that connects the instances that use it together into a single network L2 segment.
In Incus context, the `bridge` network type creates an L2 bridge that connects the instances that use it together into a single network L2 segment.
This makes it possible to pass traffic between the instances.
The bridge can also provide local DHCP and DNS.
@ -70,10 +70,10 @@ LXD supports the following network types:
:end-before: <!-- Include end OVN intro -->
```
In LXD context, the `ovn` network type creates a logical network.
In Incus context, the `ovn` network type creates a logical network.
To set it up, you must install and configure the OVN tools.
In addition, you must create an uplink network that provides the network connection for OVN.
As the uplink network, you should use one of the external network types or a managed LXD bridge.
As the uplink network, you should use one of the external network types or a managed Incus bridge.
```{tip}
Unlike the other network types, you can create and manage an OVN network inside a {ref}`project <projects>`.
@ -95,7 +95,7 @@ LXD supports the following network types:
:end-before: <!-- Include end macvlan intro -->
```
In LXD context, the `macvlan` network type provides a preset configuration to use when connecting instances to a parent macvlan interface.
In Incus context, the `macvlan` network type provides a preset configuration to use when connecting instances to a parent macvlan interface.
{ref}`network-sriov`
: % Include content from [../reference/network_sriov.md](../reference/network_sriov.md)
@ -104,7 +104,7 @@ LXD supports the following network types:
:end-before: <!-- Include end SR-IOV intro -->
```
In LXD context, the `sriov` network type provides a preset configuration to use when connecting instances to a parent SR-IOV interface.
In Incus context, the `sriov` network type provides a preset configuration to use when connecting instances to a parent SR-IOV interface.
{ref}`network-physical`
: % Include content from [../reference/network_physical.md](../reference/network_physical.md)
@ -124,12 +124,12 @@ If you choose a fully controlled network, it provides more functionality than us
As a general recommendation:
- If you are running LXD on a single system or in a public cloud, use a {ref}`network-bridge`.
- If you are running LXD in your own private cloud, use an {ref}`network-ovn`.
- If you are running Incus on a single system or in a public cloud, use a {ref}`network-bridge`.
- If you are running Incus in your own private cloud, use an {ref}`network-ovn`.
```{note}
OVN requires a shared L2 uplink network for proper operation.
Therefore, using OVN is usually not possible if you run LXD in a public cloud.
Therefore, using OVN is usually not possible if you run Incus in a public cloud.
```
- To connect an instance NIC to a managed network, use the `network` property rather than the `parent` property, if possible.

10
doc/explanation/performance_tuning.md
View File

@ -5,15 +5,15 @@ relatedlinks: https://www.youtube.com/watch?v=QyXOOE_4cm0
(performance-tuning)=
# About performance tuning
When you are ready to move your LXD setup to production, you should take some time to optimize the performance of your system.
When you are ready to move your Incus setup to production, you should take some time to optimize the performance of your system.
There are different aspects that impact performance.
The following steps help you to determine the choices and settings that you should tune to improve your LXD setup.
The following steps help you to determine the choices and settings that you should tune to improve your Incus setup.
## Run benchmarks
LXD provides a benchmarking tool to evaluate the performance of your system.
Incus provides a benchmarking tool to evaluate the performance of your system.
You can use the tool to initialize or launch a number of containers and measure the time it takes for the system to create the containers.
By running the tool repeatedly with different LXD configurations, system settings or even hardware setups, you can compare the performance and evaluate which is the ideal configuration.
By running the tool repeatedly with different Incus configurations, system settings or even hardware setups, you can compare the performance and evaluate which is the ideal configuration.
See {ref}`benchmark-performance` for instructions on running the tool.
@ -46,7 +46,7 @@ See {ref}`server-settings` for a list of relevant server settings and suggested
## Tune the network bandwidth
If you have a lot of local activity between instances or between the LXD host and the instances, or if you have a fast internet connection, you should consider increasing the network bandwidth of your LXD setup.
If you have a lot of local activity between instances or between the Incus host and the instances, or if you have a fast internet connection, you should consider increasing the network bandwidth of your Incus setup.
You can do this by increasing the transmit and receive queue lengths.
See {ref}`network-increase-bandwidth` for instructions.

26
doc/explanation/projects.md
View File

@ -4,7 +4,7 @@
```{youtube} https://www.youtube.com/watch?v=cUHkgg6TovM
```
You can use projects to keep your LXD server clean by grouping related instances together.
You can use projects to keep your Incus server clean by grouping related instances together.
In addition to isolated instances, each project can also have specific images, profiles, networks, and storage.
For example, projects can be useful in the following scenarios:
@ -13,15 +13,15 @@ For example, projects can be useful in the following scenarios:
You want to keep these instances separate to make it easier to locate and maintain them, and you might want to reuse the same instance names in each customer project for consistency reasons.
Each instance in a customer project should use the same base configuration (for example, networks and storage), but the configuration might differ between customer projects.
In this case, you can create a LXD project for each customer project (thus each group of instances) and use different profiles, networks, and storage for each LXD project.
- Your LXD server is shared between multiple users.
In this case, you can create a Incus project for each customer project (thus each group of instances) and use different profiles, networks, and storage for each Incus project.
- Your Incus server is shared between multiple users.
Each user runs their own instances, and might want to configure their own profiles.
You want to keep the user instances confined, so that each user can interact only with their own instances and cannot see the instances created by other users.
In addition, you want to be able to limit resources for each user and make sure that the instances of different users cannot interfere with one another.
In this case, you can set up a multi-user environment with confined projects.
LXD comes with a `default` project.
Incus comes with a `default` project.
See {ref}`projects-create` for instructions on how to add projects.
(projects-isolation)=
@ -49,14 +49,14 @@ New features that are added in an upgrade are disabled for existing projects.
(projects-confined)=
## Confined projects in a multi-user environment
If your LXD server is used by multiple users (for example, in a lab environment), you can use projects to confine the activities of each user.
If your Incus server is used by multiple users (for example, in a lab environment), you can use projects to confine the activities of each user.
This method isolates the instances and other entities (depending on the feature configuration), as described in {ref}`projects-isolation`.
It also confines users to their own user space and prevents them from gaining access to other users' instances or data.
Any changes that affect the LXD server and its configuration, for example, adding or removing storage, are not permitted.
Any changes that affect the Incus server and its configuration, for example, adding or removing storage, are not permitted.
In addition, this method allows users to work with LXD without being a member of the `lxd` group (see {ref}`security-daemon-access`).
Members of the `lxd` group have full access to LXD, including permission to attach file system paths and tweak the security features of an instance, which makes it possible to gain root access to the host system.
Using confined projects limits what users can do in LXD, but it also prevents users from gaining root access.
In addition, this method allows users to work with Incus without being a member of the `lxd` group (see {ref}`security-daemon-access`).
Members of the `lxd` group have full access to Incus, including permission to attach file system paths and tweak the security features of an instance, which makes it possible to gain root access to the host system.
Using confined projects limits what users can do in Incus, but it also prevents users from gaining root access.
### Authentication methods for projects
@ -67,11 +67,11 @@ Client certificates
The projects must exist before you can restrict access to them.
A client that connects using a restricted certificate can see only the project or projects that the client has been granted access to.
Multi-user LXD daemon
: The LXD snap contains a multi-user LXD daemon that allows dynamic project creation on a per-user basis.
You can configure a specific user group other than the `lxd` group to give restricted LXD access to every user in the group.
Multi-user Incus daemon
: The Incus snap contains a multi-user Incus daemon that allows dynamic project creation on a per-user basis.
You can configure a specific user group other than the `lxd` group to give restricted Incus access to every user in the group.
When a user that is a member of this group starts using LXD, LXD automatically creates a confined project for this user.
When a user that is a member of this group starts using Incus, Incus automatically creates a confined project for this user.
If you're not using the snap, you can still use this feature if your distribution supports it.

36
doc/explanation/security.md
View File

@ -12,11 +12,11 @@
See the following sections for detailed information.
If you discover a security issue, see the [LXD security policy](https://github.com/canonical/lxd/blob/main/SECURITY.md) for information on how to report the issue.
If you discover a security issue, see the [Incus security policy](https://github.com/canonical/lxd/blob/main/SECURITY.md) for information on how to report the issue.
## Supported versions
Never use unsupported LXD versions in a production environment.
Never use unsupported Incus versions in a production environment.
% Include content from [../../SECURITY.md](../../SECURITY.md)
```{include} ../../SECURITY.md
@ -25,17 +25,17 @@ Never use unsupported LXD versions in a production environment.
```
(security-daemon-access)=
## Access to the LXD daemon
## Access to the Incus daemon
LXD is a daemon that can be accessed locally over a Unix socket or, if configured, remotely over a {abbr}`TLS (Transport Layer Security)` socket.
Anyone with access to the socket can fully control LXD, which includes the ability to attach host devices and file systems or to tweak the security features for all instances.
Incus is a daemon that can be accessed locally over a Unix socket or, if configured, remotely over a {abbr}`TLS (Transport Layer Security)` socket.
Anyone with access to the socket can fully control Incus, which includes the ability to attach host devices and file systems or to tweak the security features for all instances.
Therefore, make sure to restrict the access to the daemon to trusted users.
### Local access to the LXD daemon
### Local access to the Incus daemon
The LXD daemon runs as root and provides a Unix socket for local communication.
Access control for LXD is based on group membership.
The Incus daemon runs as root and provides a Unix socket for local communication.
Access control for Incus is based on group membership.
The root user and all members of the `lxd` group can interact with the local daemon.
````{important}
@ -52,24 +52,24 @@ The root user and all members of the `lxd` group can interact with the local dae
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.
See {ref}`server-expose` for instructions.
Remote clients can then connect to LXD and access any image that is marked for public use.
Remote clients can then connect to Incus 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 addition, you should set firewall rules to allow access to the LXD port only from authorized hosts/subnets.
In addition, you should set firewall rules to allow access to the Incus port only from authorized hosts/subnets.
(container-security)=
## Container security
LXD containers can use a wide range of features for security.
Incus containers can use a wide range of features for security.
By default, containers are *unprivileged*, meaning that they operate inside a user namespace, restricting the abilities of users in the container to that of regular users on the host with limited privileges on the devices that the container owns.
If data sharing between containers isn't needed, you can enable {config:option}`instance-security:security.idmap.isolated`, which will use non-overlapping UID/GID maps for each container, preventing potential {abbr}`DoS (Denial of Service)` attacks on other containers.
LXD can also run *privileged* containers.
Incus can also run *privileged* containers.
Note, however, that those aren't root safe, and a user with root access in such a container will be able to DoS the host as well as find ways to escape confinement.
More details on container security and the kernel features we use can be found on the
@ -92,7 +92,7 @@ Which aspects you should consider depends on the networking mode you decide to u
### Bridged NIC security
The default networking mode in LXD is to provide a "managed" private network bridge that each instance connects to.
The default networking mode in Incus is to provide a "managed" private network bridge that each instance connects to.
In this mode, there is an interface on the host called `lxdbr0` that acts as the bridge for the instances.
The host runs an instance of `dnsmasq` for each managed bridge, which is responsible for allocating IP addresses and providing both authoritative and recursive DNS services.
@ -107,10 +107,10 @@ This assumes that the instances are not using any IPv6 privacy extensions when g
In this default configuration, whilst DNS names cannot not be spoofed, the instance is connected to an Ethernet bridge and can transmit any layer 2 traffic that it wishes, which means an instance that is not trusted can effectively do MAC or IP spoofing on the bridge.
In the default configuration, it is also possible for instances connected to the bridge to modify the LXD host's IPv6 routing table by sending (potentially malicious) IPv6 router advertisements to the bridge.
This is because the `lxdbr0` interface is created with `/proc/sys/net/ipv6/conf/lxdbr0/accept_ra` set to `2`, meaning that the LXD host will accept router advertisements even though `forwarding` is enabled (see [`/proc/sys/net/ipv4/*` Variables](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt) for more information).
In the default configuration, it is also possible for instances connected to the bridge to modify the Incus host's IPv6 routing table by sending (potentially malicious) IPv6 router advertisements to the bridge.
This is because the `lxdbr0` interface is created with `/proc/sys/net/ipv6/conf/lxdbr0/accept_ra` set to `2`, meaning that the Incus host will accept router advertisements even though `forwarding` is enabled (see [`/proc/sys/net/ipv4/*` Variables](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt) for more information).
However, LXD offers several bridged {abbr}`NIC (Network interface controller)` security features that can be used to control the type of traffic that an instance is allowed to send onto the network.
However, Incus offers several bridged {abbr}`NIC (Network interface controller)` security features that can be used to control the type of traffic that an instance is allowed to send onto the network.
These NIC settings should be added to the profile that the instance is using, or they can be added to individual instances, as shown below.
The following security features are available for bridged NICs:
@ -145,7 +145,7 @@ This prevents stacked VLAN Q-in-Q (802.1ad) frames from bypassing the IP filteri
An alternative networking mode is available called "routed".
It provides a virtual Ethernet device pair between container and host.
In this networking mode, the LXD host functions as a router, and static routes are added to the host directing traffic for the container's IPs towards the container's `veth` interface.
In this networking mode, the Incus host functions as a router, and static routes are added to the host directing traffic for the container's IPs towards the container's `veth` interface.
By default, the `veth` interface created on the host has its `accept_ra` setting disabled to prevent router advertisements from the container modifying the IPv6 routing table on the LXD host.
By default, the `veth` interface created on the host has its `accept_ra` setting disabled to prevent router advertisements from the container modifying the IPv6 routing table on the Incus host.
In addition to that, the `rp_filter` on the host is set to `1` to prevent source address spoofing for IPs that the host does not know the container has.

26
doc/explanation/storage.md
View File

@ -1,7 +1,7 @@
(exp-storage)=
# About storage pools, volumes and buckets
LXD stores its data in storage pools, divided into storage volumes of different content types (like images or instances).
Incus stores its data in storage pools, divided into storage volumes of different content types (like images or instances).
You could think of a storage pool as the disk that is used to store data, while storage volumes are different partitions on this disk that are used for specific purposes.
In addition to storage volumes, there are storage buckets, which use the [Amazon {abbr}`S3 (Simple Storage Service)`](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html) protocol.
@ -10,7 +10,7 @@ Like storage volumes, storage buckets are part of a storage pool.
(storage-pools)=
## Storage pools
During initialization, LXD prompts you to create a first storage pool.
During initialization, Incus prompts you to create a first storage pool.
If required, you can create additional storage pools later (see {ref}`storage-create-pool`).
Each storage pool uses a storage driver.
@ -32,8 +32,8 @@ See the following how-to guides for additional information:
(storage-location)=
### Data storage location
Where the LXD data is stored depends on the configuration and the selected storage driver.
Depending on the storage driver that is used, LXD can either share the file system with its host or keep its data separate.
Where the Incus data is stored depends on the configuration and the selected storage driver.
Depending on the storage driver that is used, Incus can either share the file system with its host or keep its data separate.
Storage location | Directory | Btrfs | LVM | ZFS | Ceph (all) |
:--- | :-: | :-: | :-: | :-: | :-: |
@ -44,20 +44,20 @@ Remote storage | - | - | - | - | &#x2713;
#### Shared with the host
Sharing the file system with the host is usually the most space-efficient way to run LXD.
Sharing the file system with the host is usually the most space-efficient way to run Incus.
In most cases, it is also the easiest to manage.
This option is supported for the `dir` driver, the `btrfs` driver (if the host is Btrfs and you point LXD to a dedicated sub-volume) and the `zfs` driver (if the host is ZFS and you point LXD to a dedicated dataset on your zpool).
This option is supported for the `dir` driver, the `btrfs` driver (if the host is Btrfs and you point Incus to a dedicated sub-volume) and the `zfs` driver (if the host is ZFS and you point Incus to a dedicated dataset on your zpool).
#### Dedicated disk or partition
Having LXD use an empty partition on your main disk or a full dedicated disk keeps its storage completely independent from the host.
Having Incus use an empty partition on your main disk or a full dedicated disk keeps its storage completely independent from the host.
This option is supported for the `btrfs` driver, the `lvm` driver and the `zfs` driver.
#### Loop disk
LXD can create a loop file on your main drive and have the selected storage driver use that.
Incus can create a loop file on your main drive and have the selected storage driver use that.
This method is functionally similar to using a disk or partition, but it uses a large file on your main drive instead.
This means that every write must go through the storage driver and your main drive's file system, which leads to decreased performance.
@ -74,11 +74,11 @@ The `ceph`, `cephfs` and `cephobject` drivers store the data in a completely ind
(storage-default-pool)=
### Default storage pool
There is no concept of a default storage pool in LXD.
There is no concept of a default storage pool in Incus.
When you create a storage volume, you must specify the storage pool to use.
When LXD automatically creates a storage volume during instance creation, it uses the storage pool that is configured for the instance.
When Incus automatically creates a storage volume during instance creation, it uses the storage pool that is configured for the instance.
This configuration can be set in either of the following ways:
- Directly on an instance: [`incus launch <image> <instance_name> --storage <storage_pool>`](incus_launch.md)
@ -102,7 +102,7 @@ In the default profile, this pool is set to the storage pool that was created du
```{youtube} https://www.youtube.com/watch?v=dvQ111pbqtk
```
When you create an instance, LXD automatically creates the required storage volumes for it.
When you create an instance, Incus automatically creates the required storage volumes for it.
You can create additional storage volumes.
See the following how-to guides for additional information:
@ -117,14 +117,14 @@ See the following how-to guides for additional information:
Storage volumes can be of the following types:
`container`/`virtual-machine`
: LXD automatically creates one of these storage volumes when you launch an instance.
: Incus automatically creates one of these storage volumes when you launch an instance.
It is used as the root disk for the instance, and it is destroyed when the instance is deleted.
This storage volume is created in the storage pool that is specified in the profile used when launching the instance (or the default profile, if no profile is specified).
The storage pool can be explicitly specified by providing the `--storage` flag to the launch command.
`image`
: LXD automatically creates one of these storage volumes when it unpacks an image to launch one or more instances from it.
: Incus automatically creates one of these storage volumes when it unpacks an image to launch one or more instances from it.
You can delete it after the instance has been created.
If you do not delete it manually, it is deleted automatically ten days after it was last used to launch an instance.

30
doc/faq.md
View File

@ -12,18 +12,18 @@ They explain how to resolve common issues and point you to more detailed informa
Most likely, your firewall blocks network access for your instances.
See {ref}`network-bridge-firewall` for more information about the problem and how to fix it.
Another frequent reason for connectivity issues is running LXD and Docker on the same host.
Another frequent reason for connectivity issues is running Incus and Docker on the same host.
See {ref}`network-lxd-docker` for instructions on how to fix such issues.
## How to enable the LXD server for remote access?
## How to enable the Incus server for remote access?
By default, the LXD server is not accessible from the network, because it only listens on a local Unix socket.
By default, the Incus server is not accessible from the network, because it only listens on a local Unix socket.
You can enable it for remote access by following the instructions in {ref}`server-expose`.
## When I do a `incus remote add`, it asks for a token?
To be able to access the remote API, clients must authenticate with the LXD server.
To be able to access the remote API, clients must authenticate with the Incus server.
See {ref}`server-authenticate` for instructions on how to authenticate using a trust token.
@ -51,23 +51,23 @@ Use either of the following methods to grant the required permissions:
Privileged containers do not have this issue because all UID/GID in the container are the same as outside.
But that's also the cause of most of the security issues with such privileged containers.
## How can I run Docker inside a LXD container?
## How can I run Docker inside a Incus container?
```{youtube} https://www.youtube.com/watch?v=_fCSSEyiGro
```
To run Docker inside a LXD container, set the {config:option}`instance-security:security.nesting` property of the container to `true`:
To run Docker inside a Incus container, set the {config:option}`instance-security:security.nesting` property of the container to `true`:
incus config set <container> security.nesting true
Note that LXD containers cannot load kernel modules, so depending on your Docker configuration, you might need to have extra kernel modules loaded by the host.
Note that Incus containers cannot load kernel modules, so depending on your Docker configuration, you might need to have extra kernel modules loaded by the host.
You can do so by setting a comma-separated list of kernel modules that your container needs:
incus config set <container_name> linux.kernel_modules <modules>
In addition, creating a `/.dockerenv` file in your container can help Docker ignore some errors it's getting due to running in a nested environment.
## Where does the LXD client (`lxc`) store its configuration?
## Where does the Incus client (`lxc`) store its configuration?
The [`lxc`](incus.md) command stores its configuration under `~/.config/lxc`, or in `~/snap/lxd/common/config` for snap users.
@ -78,17 +78,17 @@ Various configuration files are stored in that directory, for example:
- `config.yml`: configuration file (info about `remotes`, `aliases`, etc.)
- `servercerts/`: directory with server certificates belonging to `remotes`
## Why can I not ping my LXD instance from another host?
## Why can I not ping my Incus instance from another host?
Many switches do not allow MAC address changes, and will either drop traffic with an incorrect MAC or disable the port totally.
If you can ping a LXD instance from the host, but are not able to ping it from a different host, this could be the cause.
If you can ping a Incus instance from the host, but are not able to ping it from a different host, this could be the cause.
The way to diagnose this problem is to run a `tcpdump` on the uplink and you will see either ``ARP Who has `xx.xx.xx.xx` tell `yy.yy.yy.yy` ``, with you sending responses but them not getting acknowledged, or ICMP packets going in and out successfully, but never being received by the other host.
(faq-monitor)=
## How can I monitor what LXD is doing?
## How can I monitor what Incus is doing?
To see detailed information about what LXD is doing and what processes it is running, use the [`incus monitor`](incus_monitor.md) command.
To see detailed information about what Incus is doing and what processes it is running, use the [`incus monitor`](incus_monitor.md) command.
For example, to show a human-readable output of all types of messages, enter the following command:
@ -96,10 +96,10 @@ For example, to show a human-readable output of all types of messages, enter the
See [`incus monitor --help`](incus_monitor.md) for all options, and {doc}`debugging` for more information.
## Why does LXD stall when creating an instance?
## Why does Incus stall when creating an instance?
Check if your storage pool is out of space (by running [`incus storage info <pool_name>`](incus_storage_info.md)).
In that case, LXD cannot finish unpacking the image, and the instance that you're trying to create shows up as stopped.
In that case, Incus cannot finish unpacking the image, and the instance that you're trying to create shows up as stopped.
To get more insight into what is happening, run [`incus monitor`](incus_monitor.md) (see {ref}`faq-monitor`), and check `sudo dmesg` for any I/O errors.
@ -108,7 +108,7 @@ To get more insight into what is happening, run [`incus monitor`](incus_monitor.
If starting containers suddenly fails with a cgroup-related error message (`Failed to mount "/sys/fs/cgroup"`), this might be due to running a VPN client on the host.
This is a known issue for both [Mullvad VPN](https://github.com/mullvad/mullvadvpn-app/issues/3651) and [Private Internet Access VPN](https://github.com/pia-foss/desktop/issues/50), but might occur for other VPN clients as well.
The problem is that the VPN client mounts the `net_cls` cgroup1 over cgroup2 (which LXD uses).
The problem is that the VPN client mounts the `net_cls` cgroup1 over cgroup2 (which Incus uses).
The easiest fix for this problem is to stop the VPN client and unmount the `net_cls` cgroup1 with the following command:

8
doc/getting_started.md
View File

@ -4,18 +4,18 @@ relatedlinks: https://www.youtube.com/watch?v=QyXOOE_4cm0
# Getting started
See the following sections for information on how to get started with LXD:
See the following sections for information on how to get started with Incus:
```{toctree}
:maxdepth: 1
Access the documentation </howto/access_documentation>
Access the UI </howto/access_ui>
Contribute to LXD </contributing>
Contribute to Incus </contributing>
Get support </support>
Initialize LXD </howto/initialize>
Initialize Incus </howto/initialize>
Requirements </requirements>
Install LXD </installing>
Install Incus </installing>
Difference between containers and virtual machines </explanation/containers_and_vms>
First steps </tutorial/first_steps>
Frequently asked </faq>

14
doc/howto/access_documentation.md
View File

@ -1,17 +1,17 @@
(access-documentation)=
# How to access the local LXD documentation
# How to access the local Incus documentation
The latest version of the LXD documentation is available at [`documentation.ubuntu.com/lxd`](https://documentation.ubuntu.com/lxd/).
The latest version of the Incus documentation is available at [`documentation.ubuntu.com/lxd`](https://documentation.ubuntu.com/lxd/).
Alternatively, you can access a local version of the LXD documentation that is embedded in the LXD snap.
This version of the documentation exactly matches the version of your LXD deployment, but might be missing additions, fixes, or clarifications that were added after the release of the snap.
Alternatively, you can access a local version of the Incus documentation that is embedded in the Incus snap.
This version of the documentation exactly matches the version of your Incus deployment, but might be missing additions, fixes, or clarifications that were added after the release of the snap.
Complete the following steps to access the local LXD documentation:
Complete the following steps to access the local Incus documentation:
1. Make sure that your LXD server is {ref}`exposed to the network <server-expose>`.
1. Make sure that your Incus server is {ref}`exposed to the network <server-expose>`.
You can expose the server during {ref}`initialization <initialize>`, or afterwards by setting the {config:option}`server-core:core.https_address` server configuration option.
1. Access the documentation in your browser by entering the server address followed by `/documentation/` (for example, `https://192.0.2.10:8443/documentation/`).
If you have not set up a secure {ref}`authentication-server-certificate`, LXD uses a self-signed certificate, which will cause a security warning in your browser.
If you have not set up a secure {ref}`authentication-server-certificate`, Incus uses a self-signed certificate, which will cause a security warning in your browser.
Use your browser's mechanism to continue despite the security warning.

20
doc/howto/access_ui.md
View File

@ -1,39 +1,39 @@
(access-ui)=
# How to access the LXD web UI
# How to access the Incus web UI
```{note}
Starting with LXD 5.14, the LXD web UI is available as part of the LXD snap.
Starting with Incus 5.14, the Incus web UI is available as part of the Incus snap.
See the [LXD-UI GitHub repository](https://github.com/canonical/lxd-ui) for the source code.
See the [Incus-UI GitHub repository](https://github.com/canonical/lxd-ui) for the source code.
```
![Graphical console of an instance in the LXD web UI](../images/ui_console.png)
![Graphical console of an instance in the Incus web UI](../images/ui_console.png)
```{youtube} https://www.youtube.com/watch?v=wqEH_d8LC1k
```
The LXD web UI provides you with a graphical interface to manage your LXD server and instances.
It is currently in an early stage and does not provide full functionality yet, but eventually, it will be an alternative to the LXD command-line client.
The Incus web UI provides you with a graphical interface to manage your Incus server and instances.
It is currently in an early stage and does not provide full functionality yet, but eventually, it will be an alternative to the Incus command-line client.
Complete the following steps to access the LXD web UI:
Complete the following steps to access the Incus web UI:
1. Enable the UI in the snap:
snap set lxd ui.enable=true
sudo systemctl reload snap.lxd.daemon
1. Make sure that your LXD server is {ref}`exposed to the network <server-expose>`.
1. Make sure that your Incus server is {ref}`exposed to the network <server-expose>`.
You can expose the server during {ref}`initialization <initialize>`, or afterwards by setting the {config:option}`server-core:core.https_address` server configuration option.
1. Access the UI in your browser by entering the server address (for example, `https://192.0.2.10:8443`).
If you have not set up a secure {ref}`authentication-server-certificate`, LXD uses a self-signed certificate, which will cause a security warning in your browser.
If you have not set up a secure {ref}`authentication-server-certificate`, Incus uses a self-signed certificate, which will cause a security warning in your browser.
Use your browser's mechanism to continue despite the security warning.
![Example for a security warning in Chrome](../images/ui_security_warning.png
)
1. Set up the certificates that are required for the UI client to authenticate with the LXD server by following the steps presented in the UI.
1. Set up the certificates that are required for the UI client to authenticate with the Incus server by following the steps presented in the UI.
These steps include creating a set of certificates, adding the private key to your browser, and adding the public key to the server's trust store.
See {ref}`authentication` for more information.

10
doc/howto/benchmark_performance.md
View File

@ -4,11 +4,11 @@
```{youtube} https://www.youtube.com/watch?v=z_OKwO5TskA
```
The performance of your LXD server or cluster depends on a lot of different factors, ranging from the hardware, the server configuration, the selected storage driver and the network bandwidth to the overall usage patterns.
The performance of your Incus server or cluster depends on a lot of different factors, ranging from the hardware, the server configuration, the selected storage driver and the network bandwidth to the overall usage patterns.
To find the optimal configuration, you should run benchmark tests to evaluate different setups.
LXD provides a benchmarking tool for this purpose.
Incus provides a benchmarking tool for this purpose.
This tool allows you to initialize or launch a number of containers and measure the time it takes for the system to create the containers.
If you run this tool repeatedly with different configurations, you can compare the performance and evaluate which is the ideal configuration.
@ -17,17 +17,17 @@ If you run this tool repeatedly with different configurations, you can compare t
If you’re using the snap, the benchmarking tool is automatically installed.
It is available as `lxd.benchmark`.
Otherwise, if you have installed LXD through your distribution's package manager or built from source, the tool should be available as `lxd-benchmark`.
Otherwise, if you have installed Incus through your distribution's package manager or built from source, the tool should be available as `lxd-benchmark`.
If it isn't, make sure that you have `go` (version 1.18 or later) installed and install the tool with the following command:
go install github.com/canonical/lxd/lxd-benchmark@latest
## Run the tool
Run `lxd.benchmark [action]` to measure the performance of your LXD setup.
Run `lxd.benchmark [action]` to measure the performance of your Incus setup.
(This command assumes that you are using the snap; otherwise, replace `lxd.benchmark` with `lxd-benchmark`, also in the following examples.)
The benchmarking tool uses the current LXD configuration.
The benchmarking tool uses the current Incus configuration.
If you want to use a different project, specify it with `--project`.
For all actions, you can specify the number of parallel threads to use (default is to use a dynamic batch size).

2
doc/howto/cluster_config_storage.md
View File

@ -5,7 +5,7 @@ All members of a cluster must have identical storage pools.
The only configuration keys that may differ between pools on different members are [`source`](storage-drivers), [`size`](storage-drivers), [`zfs.pool_name`](storage-zfs-pool-config), [`lvm.thinpool_name`](storage-lvm-pool-config) and [`lvm.vg_name`](storage-lvm-pool-config).
See {ref}`clustering-member-config` for more information.
LXD creates a default `local` storage pool for each cluster member during initialization.
Incus creates a default `local` storage pool for each cluster member during initialization.
Creating additional storage pools is a two-step process:

26
doc/howto/cluster_form.md
View File

@ -5,15 +5,15 @@ discourse: 15871
(cluster-form)=
# How to form a cluster
When forming a LXD cluster, you start with a bootstrap server.
This bootstrap server can be an existing LXD server or a newly installed one.
When forming a Incus cluster, you start with a bootstrap server.
This bootstrap server can be an existing Incus server or a newly installed one.
After initializing the bootstrap server, you can join additional servers to the cluster.
See {ref}`clustering-members` for more information.
You can form the LXD cluster interactively by providing configuration information during the initialization process or by using preseed files that contain the full configuration.
You can form the Incus cluster interactively by providing configuration information during the initialization process or by using preseed files that contain the full configuration.
To quickly and automatically set up a basic LXD cluster, you can use MicroCloud.
To quickly and automatically set up a basic Incus cluster, you can use MicroCloud.
Note, however, that this project is still in an early phase.
## Configure the cluster interactively
@ -28,7 +28,7 @@ To initialize the bootstrap server, run `incus admin init` and answer the questi
You can accept the default values for most questions, but make sure to answer the following questions accordingly:
- `Would you like to use LXD clustering?`
- `Would you like to use Incus clustering?`
Select **yes**.
- `What IP address or DNS name should be used to reach this server?`
@ -44,7 +44,7 @@ You can accept the default values for most questions, but make sure to answer th
```{terminal}
:input: incus admin init
Would you like to use LXD clustering? (yes/no) [default=no]: yes
Would you like to use Incus clustering? (yes/no) [default=no]: yes
What IP address or DNS name should be used to reach this server? [default=192.0.2.101]:
Are you joining an existing cluster? (yes/no) [default=no]: no
What member name should be used to identify this server in the cluster? [default=server1]:
@ -55,7 +55,7 @@ Create a new ZFS pool? (yes/no) [default=yes]:
Would you like to use an existing empty block device (e.g. a disk or partition)? (yes/no) [default=no]:
Size in GiB of the new loop device (1GiB minimum) [default=9GiB]:
Do you want to configure a new remote storage pool? (yes/no) [default=no]:
Would you like to configure LXD to use an existing bridge or host interface? (yes/no) [default=no]:
Would you like to configure Incus to use an existing bridge or host interface? (yes/no) [default=no]:
Would you like stale cached images to be updated automatically? (yes/no) [default=yes]:
Would you like a YAML "incus admin init" preseed to be printed? (yes/no) [default=no]:
```
@ -70,7 +70,7 @@ You can check this with [`incus cluster list`](incus_cluster_list.md).
You can now join further servers to the cluster.
```{note}
The servers that you add should be newly installed LXD servers.
The servers that you add should be newly installed Incus servers.
If you are using existing servers, make sure to clear their contents before joining them, because any existing data on them will be lost.
```
@ -83,7 +83,7 @@ Basically, the initialization process consists of the following steps:
Answer the first questions that `incus admin init` asks accordingly:
- `Would you like to use LXD clustering?`
- `Would you like to use Incus clustering?`
Select **yes**.
- `What IP address or DNS name should be used to reach this server?`
@ -129,7 +129,7 @@ Basically, the initialization process consists of the following steps:
```{terminal}
:input: sudo incus admin init
Would you like to use LXD clustering? (yes/no) [default=no]: yes
Would you like to use Incus clustering? (yes/no) [default=no]: yes
What IP address or DNS name should be used to reach this server? [default=192.0.2.102]:
Are you joining an existing cluster? (yes/no) [default=no]: yes
Do you have a join token? (yes/no/[token]) [default=no]: yes
@ -147,7 +147,7 @@ Would you like a YAML "incus admin init" preseed to be printed? (yes/no) [defaul
```{terminal}
:input: sudo incus admin init
Would you like to use LXD clustering? (yes/no) [default=no]: yes
Would you like to use Incus clustering? (yes/no) [default=no]: yes
What IP address or DNS name should be used to reach this server? [default=192.0.2.102]:
Are you joining an existing cluster? (yes/no) [default=no]: yes
Do you have a join token? (yes/no/[token]) [default=no]: no
@ -282,7 +282,7 @@ cluster:
```{youtube} https://www.youtube.com/watch?v=iWZYUU8lX5A
```
Instead of setting up your LXD cluster manually, you can use [MicroCloud](https://microcloud.is/) to get a fully highly available LXD cluster with OVN and with Ceph storage up and running.
Instead of setting up your Incus cluster manually, you can use [MicroCloud](https://microcloud.is/) to get a fully highly available Incus cluster with OVN and with Ceph storage up and running.
To install the required snaps, run the following command:
@ -294,6 +294,6 @@ Then start the bootstrapping process with the following command:
During the initialization process, MicroCloud detects the other servers, sets up OVN networking and prompts you to add disks to Ceph.
When the initialization is complete, you’ll have an OVN cluster, a Ceph cluster and a LXD cluster, and LXD itself will have been configured with both networking and storage suitable for use in a cluster.
When the initialization is complete, you’ll have an OVN cluster, a Ceph cluster and a Incus cluster, and Incus itself will have been configured with both networking and storage suitable for use in a cluster.
See the [MicroCloud documentation](https://canonical-microcloud.readthedocs-hosted.com/en/latest/) for more information.

14
doc/howto/cluster_manage.md
View File

@ -58,7 +58,7 @@ For example:
incus cluster role add server1 event-hub
```{note}
You can add or remove only those roles that are not assigned automatically by LXD.
You can add or remove only those roles that are not assigned automatically by Incus.
```
### Edit the cluster member configuration
@ -108,13 +108,13 @@ To force-remove a cluster member, enter the following command on one of the clus
```{caution}
Force-removing a cluster member will leave the member's database in an inconsistent state (for example, the storage pool on the member will not be removed).
As a result, it will not be possible to re-initialize LXD later, and the server must be fully reinstalled.
As a result, it will not be possible to re-initialize Incus later, and the server must be fully reinstalled.
```
## Upgrade cluster members
To upgrade a cluster, you must upgrade all of its members.
All members must be upgraded to the same version of LXD.
All members must be upgraded to the same version of Incus.
```{caution}
Do not attempt to upgrade your cluster if any of its members are offline.
@ -123,13 +123,13 @@ Offline members cannot be upgraded, and your cluster will end up in a blocked st
Also note that if you are using the snap, upgrades might happen automatically, so to prevent any issues you should always recover or remove offline members immediately.
```
To upgrade a single member, simply upgrade the LXD package on the host and restart the LXD daemon.
For example, if you are using the snap then refresh to the latest version and cohort in the current channel (also reloads LXD):
To upgrade a single member, simply upgrade the Incus package on the host and restart the Incus daemon.
For example, if you are using the snap then refresh to the latest version and cohort in the current channel (also reloads Incus):
sudo snap refresh lxd --cohort="+"
If the new version of the daemon has database schema or API changes, the upgraded member might transition into a "blocked" state.
In this case, the member does not serve any LXD API requests (which means that `lxc` commands don't work on that member anymore), but any running instances will continue to run.
In this case, the member does not serve any Incus API requests (which means that `lxc` commands don't work on that member anymore), but any running instances will continue to run.
This happens if there are other cluster members that have not been upgraded and are therefore running an older version.
Run [`incus cluster list`](incus_cluster_list.md) on a cluster member that is not blocked to see if any members are blocked.
@ -139,7 +139,7 @@ When you upgrade the last member, the blocked members will notice that all serve
## Update the cluster certificate
In a LXD cluster, the API on all servers responds with the same shared certificate, which is usually a standard self-signed certificate with an expiry set to ten years.
In a Incus cluster, the API on all servers responds with the same shared certificate, which is usually a standard self-signed certificate with an expiry set to ten years.
The certificate is stored at `/var/snap/lxd/common/lxd/cluster.crt` (if you use the snap) or `/var/lib/lxd/cluster.crt` (otherwise) and is the same on all cluster members.

16
doc/howto/cluster_recover.md
View File

@ -10,15 +10,15 @@ If this is not possible, there are a few ways to recover the cluster, depending
See the following sections for details.
```{note}
When your cluster is in a state that needs recovery, most `lxc` commands do not work, because the LXD client cannot connect to the LXD daemon.
When your cluster is in a state that needs recovery, most `lxc` commands do not work, because the Incus client cannot connect to the Incus daemon.
Therefore, the commands to recover the cluster are provided directly by the LXD daemon (`lxd`).
Therefore, the commands to recover the cluster are provided directly by the Incus daemon (`lxd`).
Run `incus admin cluster --help` for an overview of all available commands.
```
## Recover from quorum loss
Every LXD cluster has a specific number of members (configured through {config:option}`server-cluster:cluster.max_voters`) that serve as voting members of the distributed database.
Every Incus cluster has a specific number of members (configured through {config:option}`server-cluster:cluster.max_voters`) that serve as voting members of the distributed database.
If you permanently lose a majority of these cluster members (for example, you have a three-member cluster and you lose two members), the cluster loses quorum and becomes unavailable.
However, if at least one database member survives, it is possible to recover the cluster.
@ -31,17 +31,17 @@ To do so, complete the following steps:
This command shows which cluster members have one of the database roles.
1. Pick one of the listed database members that is still online as the new leader.
Log on to the machine (if it differs from the one you are already logged on to).
1. Make sure that the LXD daemon is not running on the machine.
1. Make sure that the Incus daemon is not running on the machine.
For example, if you're using the snap:
sudo snap stop lxd
1. Log on to all other cluster members that are still online and stop the LXD daemon.
1. Log on to all other cluster members that are still online and stop the Incus daemon.
1. On the server that you picked as the new leader, run the following command:
sudo incus admin cluster recover-from-quorum-loss
1. Start the LXD daemon again on all machines, starting with the new leader.
1. Start the Incus daemon again on all machines, starting with the new leader.
For example, if you're using the snap:
sudo snap start lxd
@ -69,7 +69,7 @@ You can edit the {ref}`clustering-member-roles` of the different members, but wi
Log on to each cluster member and complete the following steps:
1. Stop the LXD daemon.
1. Stop the Incus daemon.
For example, if you're using the snap:
sudo snap stop lxd
@ -100,7 +100,7 @@ Log on to each cluster member and complete the following steps:
You can edit the addresses and the roles.
After doing the changes on all cluster members, start the LXD daemon on all members again.
After doing the changes on all cluster members, start the Incus daemon on all members again.
For example, if you're using the snap:
sudo snap start lxd

8
doc/howto/disaster_recovery.md
View File

@ -8,7 +8,7 @@ discourse: 11296
```{youtube} https://youtu.be/IFOZpAxckPo?t=796
```
LXD provides a tool for disaster recovery in case the {ref}`LXD database <database>` is corrupted or otherwise lost.
Incus provides a tool for disaster recovery in case the {ref}`Incus database <database>` is corrupted or otherwise lost.
The tool scans the storage pools for instances and imports the instances that it finds back into the database.
You need to re-create the required entities that are missing (usually profiles, projects, and networks).
@ -27,8 +27,8 @@ The tool is available through the `incus admin recover` command (note the `lxd`
When you run the tool, it scans all storage pools that still exist in the database, looking for missing volumes that can be recovered.
You can also specify the details of any unknown storage pools (those that exist on disk but do not exist in the database), and the tool attempts to scan those too.
After mounting the specified storage pools (if not already mounted), the tool scans them for unknown volumes that look like they are associated with LXD.
LXD maintains a `backup.yaml` file in each instance's storage volume, which contains all necessary information to recover a given instance (including instance configuration, attached devices, storage volume, and pool configuration).
After mounting the specified storage pools (if not already mounted), the tool scans them for unknown volumes that look like they are associated with Incus.
Incus maintains a `backup.yaml` file in each instance's storage volume, which contains all necessary information to recover a given instance (including instance configuration, attached devices, storage volume, and pool configuration).
This data can be used to rebuild the instance, storage volume, and storage pool database records.
Before recovering an instance, the tool performs some consistency checks to compare what is in the `backup.yaml` file with what is actually on disk (such as matching snapshots).
If all checks out, the database records are re-created.
@ -48,7 +48,7 @@ This is how a recovery process could look:
```{terminal}
:input: incus admin recover
This LXD server currently has the following storage pools:
This Incus server currently has the following storage pools:
Would you like to recover another storage pool? (yes/no) [default=no]: yes
Name of the storage pool: default
Name of the storage backend (btrfs, ceph, cephfs, cephobject, dir, lvm, zfs): zfs

16
doc/howto/images_copy.md
View File

@ -57,7 +57,7 @@ See [`incus image import --help`](incus_image_import.md) for all available flags
### Import from a file on a remote web server
You can import image files from a remote web server by URL.
This method is an alternative to running a LXD server for the sole purpose of distributing an image to users.
This method is an alternative to running a Incus server for the sole purpose of distributing an image to users.
It only requires a basic web server with support for custom headers (see {ref}`images-copy-http-headers`).
The image files must be provided as unified images (see {ref}`image-format-unified`).
@ -71,18 +71,18 @@ You can assign an alias to the local image with the `--alias` flag.
(images-copy-http-headers)=
#### Custom HTTP headers
LXD requires the following custom HTTP headers to be set by the web server:
Incus requires the following custom HTTP headers to be set by the web server:
`LXD-Image-Hash`
`Incus-Image-Hash`
: The SHA256 of the image that is being downloaded.
`LXD-Image-URL`
`Incus-Image-URL`
: The URL from which to download the image.
LXD sets the following headers when querying the server:
Incus sets the following headers when querying the server:
`LXD-Server-Architectures`
`Incus-Server-Architectures`
: A comma-separated list of architectures that the client supports.
`LXD-Server-Version`
: The version of LXD in use.
`Incus-Server-Version`
: The version of Incus in use.

2
doc/howto/images_create.md
View File

@ -26,7 +26,7 @@ If an image with the same name already exists, add the `--reuse` flag to overwri
See [`incus publish --help`](incus_publish.md) for a full list of available flags.
The publishing process can take quite a while because it generates a tarball from the instance or snapshot and then compresses it.
As this can be particularly I/O and CPU intensive, publish operations are serialized by LXD.
As this can be particularly I/O and CPU intensive, publish operations are serialized by Incus.
### Prepare the instance for publishing

4
doc/howto/images_manage.md
View File

@ -60,7 +60,7 @@ To set a specific image property that is located under the `properties` key, ent
```{note}
These properties can be used to convey information about the image.
They do not configure LXD's behavior in any way.
They do not configure Incus's behavior in any way.
```
To edit the full image properties, including the top-level properties, enter the following command:
@ -95,7 +95,7 @@ If you want to keep the alias name, but point the alias to a different image (fo
(images-manage-export)=
## Export an image to a file
Images are located in the image store of your local server or a remote LXD server.
Images are located in the image store of your local server or a remote Incus server.
You can export them to a file though.
This method can be useful to back up image files or to transfer them to an air-gapped environment.

6
doc/howto/images_remote.md
View File

@ -12,7 +12,7 @@ To see all configured remote servers, enter the following command:
incus remote list
Remote servers that use the [simple streams format](https://git.launchpad.net/simplestreams/tree/) are pure image servers.
Servers that use the `lxd` format are LXD servers, which either serve solely as image servers or might provide some images in addition to serving as regular LXD servers.
Servers that use the `lxd` format are Incus servers, which either serve solely as image servers or might provide some images in addition to serving as regular Incus servers.
See {ref}`remote-image-server-types` for more information.
<!-- Include end list remotes -->
@ -37,10 +37,10 @@ To add a simple streams server as a remote, enter the following command:
The URL must use HTTPS.
### Add a remote LXD server
### Add a remote Incus server
<!-- Include start add remotes -->
To add a LXD server as a remote, enter the following command:
To add a Incus server as a remote, enter the following command:
incus remote add <remote_name> <IP|FQDN|URL> [flags]

28
doc/howto/import_machines_to_instances.md
View File

@ -3,15 +3,15 @@ discourse: 14345
---
(import-machines-to-instances)=
# How to import physical or virtual machines to LXD instances
# How to import physical or virtual machines to Incus instances
```{youtube} https://www.youtube.com/watch?v=F9GALjHtnUU
```
LXD provides a tool (`lxd-migrate`) to create a LXD instance based on an existing disk or image.
Incus provides a tool (`lxd-migrate`) to create a Incus instance based on an existing disk or image.
You can run the tool on any Linux machine.
It connects to a LXD server and creates a blank instance, which you can configure during or after the migration.
It connects to a Incus server and creates a blank instance, which you can configure during or after the migration.
The tool then copies the data from the disk or image that you provide to the instance.
```{note}
@ -45,7 +45,7 @@ The tool can create both containers and virtual machines:
1. Install the `virtio-win` package, or download the [`virtio-win.iso`](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso) image and put it into the `/usr/share/virtio-win` folder.
1. You might also need to install [`rhsrvany`](https://github.com/rwmjones/rhsrvany).
Now you can use `virt-v2v` to convert images from a foreign hypervisor to `raw` images for LXD and include the required drivers:
Now you can use `virt-v2v` to convert images from a foreign hypervisor to `raw` images for Incus and include the required drivers:
```
# Example 1. Convert a vmdk disk image to a raw image suitable for lxd-migrate
@ -58,9 +58,9 @@ The tool can create both containers and virtual machines:
</details>
````
Complete the following steps to migrate an existing machine to a LXD instance:
Complete the following steps to migrate an existing machine to a Incus instance:
1. Download the `bin.linux.lxd-migrate` tool from the **Assets** section of the latest [LXD release](https://github.com/canonical/lxd/releases).
1. Download the `bin.linux.lxd-migrate` tool from the **Assets** section of the latest [Incus release](https://github.com/canonical/lxd/releases).
1. Place the tool on the machine that you want to use to create the instance.
Make it executable (usually by running `chmod u+x bin.linux.lxd-migrate`).
1. Make sure that the machine has `rsync` installed.
@ -76,18 +76,18 @@ Complete the following steps to migrate an existing machine to a LXD instance:
See `./bin.linux.lxd-migrate --help` for more information.
```
1. Specify the LXD server URL, either as an IP address or as a DNS name.
1. Specify the Incus server URL, either as an IP address or as a DNS name.
```{note}
The LXD server must be {ref}`exposed to the network <server-expose>`.
If you want to import to a local LXD server, you must still expose it to the network.
The Incus server must be {ref}`exposed to the network <server-expose>`.
If you want to import to a local Incus server, you must still expose it to the network.
You can then specify `127.0.0.1` as the IP address to access the local server.
```
1. Check and confirm the certificate fingerprint.
1. Choose a method for authentication (see {ref}`authentication`).
For example, if you choose using a certificate token, log on to the LXD server and create a token for the machine on which you are running the migration tool with [`incus config trust add`](incus_config_trust_add.md).
For example, if you choose using a certificate token, log on to the Incus server and create a token for the machine on which you are running the migration tool with [`incus config trust add`](incus_config_trust_add.md).
Then use the generated token to authenticate the tool.
1. Choose whether to create a container or a virtual machine.
See {ref}`containers-and-vms`.
@ -107,7 +107,7 @@ Complete the following steps to migrate an existing machine to a LXD instance:
```{terminal}
:input: sudo ./bin.linux.lxd-migrate
Please provide LXD server URL: https://192.0.2.7:8443
Please provide Incus server URL: https://192.0.2.7:8443
Certificate fingerprint: xxxxxxxxxxxxxxxxx
ok (y/n)? y
@ -117,7 +117,7 @@ Complete the following steps to migrate an existing machine to a LXD instance:
Please pick an authentication mechanism above: 1
Please provide the certificate token: xxxxxxxxxxxxxxxx
Remote LXD server:
Remote Incus server:
Hostname: bar
Version: 5.4
@ -211,7 +211,7 @@ Complete the following steps to migrate an existing machine to a LXD instance:
```{terminal}
:input: sudo ./bin.linux.lxd-migrate
Please provide LXD server URL: https://192.0.2.7:8443
Please provide Incus server URL: https://192.0.2.7:8443
Certificate fingerprint: xxxxxxxxxxxxxxxxx
ok (y/n)? y
@ -221,7 +221,7 @@ Complete the following steps to migrate an existing machine to a LXD instance:
Please pick an authentication mechanism above: 1
Please provide the certificate token: xxxxxxxxxxxxxxxx
Remote LXD server:
Remote Incus server:
Hostname: bar
Version: 5.4

26
doc/howto/initialize.md
View File

@ -1,7 +1,7 @@
(initialize)=
# How to initialize LXD
# How to initialize Incus
Before you can create a LXD instance, you must configure and initialize LXD.
Before you can create a Incus instance, you must configure and initialize Incus.
## Interactive configuration
@ -20,8 +20,8 @@ The questions are dynamically adapted to the answers that you give.
They cover the following areas:
Clustering (see {ref}`exp-clustering` and {ref}`cluster-form`)
: A cluster combines several LXD servers.
The cluster members share the same distributed database and can be managed uniformly using the LXD client ([`lxc`](incus.md)) or the REST API.
: A cluster combines several Incus servers.
The cluster members share the same distributed database and can be managed uniformly using the Incus client ([`lxc`](incus.md)) or the REST API.
The default answer is `no`, which means clustering is not enabled.
If you answer `yes`, you can either connect to an existing cluster or create one.
@ -29,7 +29,7 @@ Clustering (see {ref}`exp-clustering` and {ref}`cluster-form`)
Networking (see {ref}`networks` and {ref}`Network devices <devices-nic>`)
: Provides network access for the instances.
You can let LXD create a new bridge (recommended) or use an existing network bridge or interface.
You can let Incus create a new bridge (recommended) or use an existing network bridge or interface.
You can create additional bridges and assign them to instances later.
@ -55,7 +55,7 @@ Automatic image update (see {ref}`about-images`)
: You can download images from image servers.
In this case, images can be updated automatically.
The default answer is `yes`, which means that LXD will update the downloaded images regularly.
The default answer is `yes`, which means that Incus will update the downloaded images regularly.
YAML `incus admin init` preseed (see {ref}`initialize-preseed`)
: If you answer `yes`, the command displays a summary of your chosen configuration options in the terminal.
@ -76,9 +76,9 @@ If you want to use an optimized setup, go through the interactive configuration
(initialize-preseed)=
## Non-interactive configuration
The `incus admin init` command supports a `--preseed` command line flag that makes it possible to fully configure the LXD daemon settings, storage pools, network devices and profiles, in a non-interactive way through a preseed YAML file.
The `incus admin init` command supports a `--preseed` command line flag that makes it possible to fully configure the Incus daemon settings, storage pools, network devices and profiles, in a non-interactive way through a preseed YAML file.
For example, starting from a brand new LXD installation, you could configure LXD with the following command:
For example, starting from a brand new Incus installation, you could configure Incus with the following command:
```bash
cat <<EOF | incus admin init --preseed
@ -94,14 +94,14 @@ networks:
EOF
```
This preseed configuration initializes the LXD daemon to listen for HTTPS connections on port 9999 of the 192.0.2.1 address, to automatically update images every 15 hours and to create a network bridge device named `lxdbr0`, which gets assigned an IPv4 address automatically.
This preseed configuration initializes the Incus daemon to listen for HTTPS connections on port 9999 of the 192.0.2.1 address, to automatically update images every 15 hours and to create a network bridge device named `lxdbr0`, which gets assigned an IPv4 address automatically.
### Re-configuring an existing LXD installation
### Re-configuring an existing Incus installation
If you are configuring a new LXD installation, the preseed command applies the configuration as specified (as long as the given YAML contains valid keys and values).
If you are configuring a new Incus installation, the preseed command applies the configuration as specified (as long as the given YAML contains valid keys and values).
There is no existing state that might conflict with the specified configuration.
However, if you are re-configuring an existing LXD installation using the preseed command, the provided YAML configuration might conflict with the existing configuration.
However, if you are re-configuring an existing Incus installation using the preseed command, the provided YAML configuration might conflict with the existing configuration.
To avoid such conflicts, the following rules are in place:
- The provided YAML configuration overwrites existing entities.
@ -120,7 +120,7 @@ Failure modes when overwriting entities are the same as for the `PUT` requests i
```{note}
The rollback process might potentially fail, although rarely (typically due to backend bugs or limitations).
You should therefore be careful when trying to reconfigure a LXD daemon via preseed.
You should therefore be careful when trying to reconfigure a Incus daemon via preseed.
```
### Default profile

4
doc/howto/instances_access_files.md
View File

@ -1,11 +1,11 @@
(instances-access-files)=
# How to access files in an instance
You can manage files inside an instance using the LXD client without needing to access the instance through the network.
You can manage files inside an instance using the Incus client without needing to access the instance through the network.
Files can be individually edited or deleted, pushed from or pulled to the local machine.
Alternatively, you can mount the instance's file system onto the local machine.
For containers, these file operations always work and are handled directly by LXD.
For containers, these file operations always work and are handled directly by Incus.
For virtual machines, the `lxd-agent` process must be running inside of the virtual machine for them to work.
## Edit instance files

2
doc/howto/instances_configure.md
View File

@ -109,7 +109,7 @@ See [`PATCH /1.0/instances/{name}`](swagger:/instances/instance_patch) and [`PUT
```
```{group-tab} UI
The LXD UI does not distinguish between instance options and instance properties.
The Incus UI does not distinguish between instance options and instance properties.
Therefore, you can configure instance properties in the same way as you {ref}`configure instance options <instances-configure-options>`.
```
````

6
doc/howto/instances_create.md
View File

@ -11,14 +11,14 @@ Enter the following command to create a container:
incus launch|init <image_server>:<image_name> <instance_name> [flags]
Image
: Images contain a basic operating system (for example, a Linux distribution) and some LXD-related information.
: Images contain a basic operating system (for example, a Linux distribution) and some Incus-related information.
Images for various operating systems are available on the built-in remote image servers.
See {ref}`images` for more information.
Unless the image is available locally, you must specify the name of the image server and the name of the image (for example, `ubuntu:22.04` for the official 22.04 Ubuntu image).
Instance name
: Instance names must be unique within a LXD deployment (also within a cluster).
: Instance names must be unique within a Incus deployment (also within a cluster).
See {ref}`instance-properties` for additional requirements.
Flags
@ -78,7 +78,7 @@ To launch a virtual machine on the cluster member `server2`, enter the following
### Launch a container with a specific instance type
LXD supports simple instance types for clouds.
Incus supports simple instance types for clouds.
Those are represented as a string that can be passed at instance creation time.
The syntax allows the three following forms:

10
doc/howto/instances_troubleshoot.md
View File

@ -22,12 +22,12 @@ To troubleshoot the problem, complete the following steps:
incus console <instance_name> --show-log
Detailed server information
: The LXD snap includes a tool that collects the relevant server information for debugging.
: The Incus snap includes a tool that collects the relevant server information for debugging.
Enter the following command to run it:
sudo lxd.buginfo
1. Reboot the machine that runs your LXD server.
1. Reboot the machine that runs your Incus server.
1. Try starting your instance again.
If the error occurs again, compare the logs to check if it is the same error.
@ -51,10 +51,10 @@ Failed to mount proc at /proc: Operation not permitted
```
The errors here say that `/sys` and `/proc` cannot be mounted - which is correct in an unprivileged container.
However, LXD mounts these file systems automatically if it can.
However, Incus mounts these file systems automatically if it can.
The {doc}`container requirements <../container-environment>` specify that every container must come with an empty `/dev`, `/proc` and `/sys` directory, and that `/sbin/init` must exist.
If those directories don't exist, LXD cannot mount them, and `systemd` will then try to do so.
If those directories don't exist, Incus 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.
@ -89,5 +89,5 @@ sys
[root@systemd /]# exit
```
Because LXD tries to auto-heal, it created some of the directories when it was starting up.
Because Incus tries to auto-heal, it created some of the directories when it was starting up.
Shutting down and restarting the container fixes the problem, but the original cause is still there - the template does not contain the required files.

2
doc/howto/lxc_alias.md
View File

@ -1,7 +1,7 @@
(lxc-alias)=
# How to add command aliases
The LXD command-line client supports adding aliases for commands that you use frequently.
The Incus command-line client supports adding aliases for commands that you use frequently.
You can use aliases as shortcuts for longer commands, or to automatically add flags to existing commands.
To manage command aliases, you use the [`incus alias`](incus_alias.md) command.

16
doc/howto/migrate_from_lxc.md
View File

@ -1,16 +1,16 @@
(migrate-from-lxc)=
# How to migrate containers from LXC to LXD
# How to migrate containers from LXC to Incus
```{youtube} https://www.youtube.com/watch?v=F9GALjHtnUU
```
LXD provides a tool (`lxc-to-lxd`) that you can use to import LXC containers into your LXD server.
The LXC containers must exist on the same machine as the LXD server.
Incus provides a tool (`lxc-to-lxd`) that you can use to import LXC containers into your Incus server.
The LXC containers must exist on the same machine as the Incus server.
The tool analyzes the LXC containers and migrates both their data and their configuration into new LXD containers.
The tool analyzes the LXC containers and migrates both their data and their configuration into new Incus containers.
```{note}
Alternatively, you can use the `lxd-migrate` tool within a LXC container to migrate it to LXD (see {ref}`import-machines-to-instances`).
Alternatively, you can use the `lxd-migrate` tool within a LXC container to migrate it to Incus (see {ref}`import-machines-to-instances`).
However, this tool does not migrate any of the LXC container configuration.
```
@ -29,7 +29,7 @@ You can migrate one container at a time or all of your LXC containers at the sam
```{note}
Migrated containers use the same name as the original containers.
You cannot migrate containers with a name that already exists as an instance name in LXD.
You cannot migrate containers with a name that already exists as an instance name in Incus.
Therefore, rename any LXC containers that might cause name conflicts before you start the migration process.
```
@ -49,7 +49,7 @@ To migrate only the `lxc1` container:
sudo lxc-to-incus --containers lxc1
To migrate two containers (`lxc1` and `lxc2`) and use the `my-storage` storage pool in LXD:
To migrate two containers (`lxc1` and `lxc2`) and use the `my-storage` storage pool in Incus:
sudo lxc-to-incus --containers lxc1,lxc2 --storage my-storage
@ -96,4 +96,4 @@ Transferring container: lxc1: ...
Container 'lxc1' successfully created
```
After the migration process is complete, you can check and, if necessary, update the configuration in LXD before you start the migrated LXD container.
After the migration process is complete, you can check and, if necessary, update the configuration in Incus before you start the migrated Incus container.

10
doc/howto/move_instances.md
View File

@ -3,9 +3,9 @@ discourse: 16635
---
(move-instances)=
# How to move existing LXD instances between servers
# How to move existing Incus instances between servers
To move an instance from one LXD server to another, use the [`incus move`](incus_move.md) command:
To move an instance from one Incus server to another, use the [`incus move`](incus_move.md) command:
incus move [<source_remote>:]<source_instance_name> <target_remote>:[<target_instance_name>]
@ -71,7 +71,7 @@ If you are using the snap, use the following commands to enable CRIU:
Otherwise, make sure you have CRIU installed on both systems.
To optimize the memory transfer for a container, set the {config:option}`instance-migration:migration.incremental.memory` property to `true` to make use of the pre-copy features in CRIU.
With this configuration, LXD instructs CRIU to perform a series of memory dumps for the container.
After each dump, LXD sends the memory dump to the specified remote.
With this configuration, Incus instructs CRIU to perform a series of memory dumps for the container.
After each dump, Incus sends the memory dump to the specified remote.
In an ideal scenario, each memory dump will decrease the delta to the previous memory dump, thereby increasing the percentage of memory that is already synced.
When the percentage of synced memory is equal to or greater than the threshold specified via {config:option}`instance-migration:migration.incremental.memory.goal`, or the maximum number of allowed iterations specified via {config:option}`instance-migration:migration.incremental.memory.iterations` is reached, LXD instructs CRIU to perform a final memory dump and transfers it.
When the percentage of synced memory is equal to or greater than the threshold specified via {config:option}`instance-migration:migration.incremental.memory.goal`, or the maximum number of allowed iterations specified via {config:option}`instance-migration:migration.incremental.memory.iterations` is reached, Incus instructs CRIU to perform a final memory dump and transfers it.

4
doc/howto/network_acls.md
View File

@ -80,7 +80,7 @@ Rules are provided as lists.
However, the order of the rules in the list is not important and does not affect
filtering.
LXD automatically orders the rules based on the `action` property as follows:
Incus automatically orders the rules based on the `action` property as follows:
- `drop`
- `reject`
@ -216,7 +216,7 @@ incus config device set <instance_name> <device_name> security.acls.default.ingr
When using network ACLs with a bridge network, be aware of the following limitations:
- Unlike OVN ACLs, bridge ACLs are applied only on the boundary between the bridge and the LXD host.
- Unlike OVN ACLs, bridge ACLs are applied only on the boundary between the bridge and the Incus host.
This means they can only be used to apply network policies for traffic going to or from external networks.
They cannot be used for to create {spellexception}`intra-bridge` firewalls, thus firewalls that control traffic between instances connected to the same bridge.
- {ref}`ACL groups and network selectors <network-acls-selectors>` are not supported.

12
doc/howto/network_bgp.md
View File

@ -3,7 +3,7 @@ discourse: 11567
---
(network-bgp)=
# How to configure LXD as a BGP server
# How to configure Incus as a BGP server
```{note}
The BGP server feature is available for the {ref}`network-bridge` and the {ref}`network-physical`.
@ -14,11 +14,11 @@ The BGP server feature is available for the {ref}`network-bridge` and the {ref}`
{abbr}`BGP (Border Gateway Protocol)` is a protocol that allows exchanging routing information between autonomous systems.
If you want to directly route external addresses to specific LXD servers or instances, you can configure LXD as a BGP server.
LXD will then act as a BGP peer and advertise relevant routes and next hops to external routers, for example, your network router.
If you want to directly route external addresses to specific Incus servers or instances, you can configure Incus as a BGP server.
Incus will then act as a BGP peer and advertise relevant routes and next hops to external routers, for example, your network router.
It automatically establishes sessions with upstream BGP routers and announces the addresses and subnets that it's using.
The BGP server feature can be used to allow a LXD server or cluster to directly use internal/external address space by getting the specific subnets or addresses routed to the correct host.
The BGP server feature can be used to allow a Incus server or cluster to directly use internal/external address space by getting the specific subnets or addresses routed to the correct host.
This way, traffic can be forwarded to the target instance.
For bridge networks, the following addresses and networks are being advertised:
@ -41,7 +41,7 @@ If you need this, filter prefixes on the upstream routers.
## Configure the BGP server
To configure LXD as a BGP server, set the following server configuration options on all cluster members:
To configure Incus as a BGP server, set the following server configuration options on all cluster members:
- {config:option}`server-core:core.bgp_address` - the IP address for the BGP server
- {config:option}`server-core:core.bgp_asn` - the {abbr}`ASN (Autonomous System Number)` for the local server
@ -55,7 +55,7 @@ incus config set core.bgp_asn=65536
incus config set core.bgp_routerid=192.0.2.50
```
Once these configuration options are set, LXD starts listening for BGP sessions.
Once these configuration options are set, Incus starts listening for BGP sessions.
### Configure next-hop (`bridge` only)

56
doc/howto/network_bridge_firewalld.md
View File

@ -6,13 +6,13 @@ discourse: 10034,9953
# How to configure your firewall
Linux firewalls are based on `netfilter`.
LXD uses the same subsystem, which can lead to connectivity issues.
Incus uses the same subsystem, which can lead to connectivity issues.
If you run a firewall on your system, you might need to configure it to allow network traffic between the managed LXD bridge and the host.
If you run a firewall on your system, you might need to configure it to allow network traffic between the managed Incus bridge and the host.
Otherwise, some network functionality (DHCP, DNS and external network access) might not work as expected.
You might also see conflicts between the rules defined by your firewall (or another application) and the firewall rules that LXD adds.
For example, your firewall might erase LXD rules if it is started after the LXD daemon, which might interrupt network connectivity to the instance.
You might also see conflicts between the rules defined by your firewall (or another application) and the firewall rules that Incus adds.
For example, your firewall might erase Incus rules if it is started after the Incus daemon, which might interrupt network connectivity to the instance.
## `xtables` vs. `nftables`
@ -21,36 +21,36 @@ There are different userspace commands to add rules to `netfilter`: `xtables` (`
`xtables` provides an ordered list of rules, which might cause issues if multiple systems add and remove entries from the list.
`nftables` adds the ability to separate rules into namespaces, which helps to separate rules from different applications.
However, if a packet is blocked in one namespace, it is not possible for another namespace to allow it.
Therefore, rules in one namespace can still affect rules in another namespace, and firewall applications can still impact LXD network functionality.
Therefore, rules in one namespace can still affect rules in another namespace, and firewall applications can still impact Incus network functionality.
If your system supports and uses `nftables`, LXD detects this and switches to `nftables` mode.
In this mode, LXD adds its rules into the `nftables`, using its own `nftables` namespace.
If your system supports and uses `nftables`, Incus detects this and switches to `nftables` mode.
In this mode, Incus adds its rules into the `nftables`, using its own `nftables` namespace.
## Use LXD's firewall
## Use Incus's firewall
By default, managed LXD bridges add firewall rules to ensure full functionality.
If you do not run another firewall on your system, you can let LXD manage its firewall rules.
By default, managed Incus bridges add firewall rules to ensure full functionality.
If you do not run another firewall on your system, you can let Incus manage its firewall rules.
To enable or disable this behavior, use the `ipv4.firewall` or `ipv6.firewall` {ref}`configuration options <network-bridge-options>`.
## Use another firewall
Firewall rules added by other applications might interfere with the firewall rules that LXD adds.
Therefore, if you use another firewall, you should disable LXD's firewall rules.
You must also configure your firewall to allow network traffic between the instances and the LXD bridge, so that the LXD instances can access the DHCP and DNS server that LXD runs on the host.
Firewall rules added by other applications might interfere with the firewall rules that Incus adds.
Therefore, if you use another firewall, you should disable Incus's firewall rules.
You must also configure your firewall to allow network traffic between the instances and the Incus bridge, so that the Incus instances can access the DHCP and DNS server that Incus runs on the host.
See the following sections for instructions on how to disable LXD's firewall rules and how to properly configure `firewalld` and UFW, respectively.
See the following sections for instructions on how to disable Incus's firewall rules and how to properly configure `firewalld` and UFW, respectively.
### Disable LXD's firewall rules
### Disable Incus's firewall rules
Run the following commands to prevent LXD from setting firewall rules for a specific network bridge (for example, `lxdbr0`):
Run the following commands to prevent Incus from setting firewall rules for a specific network bridge (for example, `lxdbr0`):
incus network set <network_bridge> ipv6.firewall false
incus network set <network_bridge> ipv4.firewall false
### `firewalld`: Add the bridge to the trusted zone
To allow traffic to and from the LXD bridge in `firewalld`, add the bridge interface to the `trusted` zone.
To allow traffic to and from the Incus bridge in `firewalld`, add the bridge interface to the `trusted` zone.
To do this permanently (so that it persists after a reboot), run the following commands:
sudo firewall-cmd --zone=trusted --change-interface=<network_bridge> --permanent
@ -72,7 +72,7 @@ Depending on your use case, you might need more advanced rules and the example c
### UFW: Add rules for the bridge
If UFW has a rule to drop all unrecognized traffic, it blocks the traffic to and from the LXD bridge.
If UFW has a rule to drop all unrecognized traffic, it blocks the traffic to and from the Incus bridge.
In this case, you must add rules to allow traffic to and from the bridge, as well as allowing traffic forwarded to it.
To do so, run the following commands:
@ -94,24 +94,24 @@ For example:
```
(network-lxd-docker)=
## Prevent connectivity issues with LXD and Docker
## Prevent connectivity issues with Incus and Docker
Running LXD and Docker on the same host can cause connectivity issues.
A common reason for these issues is that Docker sets the global FORWARD policy to `drop`, which prevents LXD from forwarding traffic and thus causes the instances to lose network connectivity.
Running Incus and Docker on the same host can cause connectivity issues.
A common reason for these issues is that Docker sets the global FORWARD policy to `drop`, which prevents Incus from forwarding traffic and thus causes the instances to lose network connectivity.
See [Docker on a router](https://docs.docker.com/network/iptables/#docker-on-a-router) for detailed information.
There are different ways of working around this problem:
Uninstall Docker
: The easiest way to prevent such issues is to uninstall Docker from the system that runs LXD and restart the system.
You can run Docker inside a LXD container or virtual machine instead.
: The easiest way to prevent such issues is to uninstall Docker from the system that runs Incus and restart the system.
You can run Docker inside a Incus container or virtual machine instead.
See [Running Docker inside of a LXD container](https://www.youtube.com/watch?v=_fCSSEyiGro) for detailed information.
See [Running Docker inside of a Incus container](https://www.youtube.com/watch?v=_fCSSEyiGro) for detailed information.
Enable IPv4 forwarding
: If uninstalling Docker is not an option, enabling IPv4 forwarding before the Docker service starts will prevent Docker from modifying the global FORWARD policy.
LXD bridge networks enable this setting normally.
However, if LXD starts after Docker, then Docker will already have modified the global FORWARD policy.
Incus bridge networks enable this setting normally.
However, if Incus starts after Docker, then Docker will already have modified the global FORWARD policy.
```{warning}
Enabling IPv4 forwarding can cause your Docker container ports to be reachable from any machine on your local network.
@ -136,12 +136,12 @@ Enable IPv4 forwarding
Allow egress network traffic flows
: If you do not want the Docker container ports to be potentially reachable from any machine on your local network, you can apply a more complex solution provided by Docker.
Use the following commands to explicitly allow egress network traffic flows from your LXD managed bridge interface:
Use the following commands to explicitly allow egress network traffic flows from your Incus managed bridge interface:
iptables -I DOCKER-USER -i <network_bridge> -j ACCEPT
iptables -I DOCKER-USER -o <network_bridge> -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
For example, if your LXD managed bridge is called `lxdbr0`, you can allow egress traffic to flow using the following commands:
For example, if your Incus managed bridge is called `lxdbr0`, you can allow egress traffic to flow using the following commands:
iptables -I DOCKER-USER -i lxdbr0 -j ACCEPT
iptables -I DOCKER-USER -o lxdbr0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT

14
doc/howto/network_bridge_resolved.md
View File

@ -1,8 +1,8 @@
(network-bridge-resolved)=
# How to integrate with `systemd-resolved`
If the system that runs LXD uses `systemd-resolved` to perform DNS lookups, you should notify `resolved` of the domains that LXD can resolve.
To do so, add the DNS servers and domains provided by a LXD network bridge to the `resolved` configuration.
If the system that runs Incus uses `systemd-resolved` to perform DNS lookups, you should notify `resolved` of the domains that Incus can resolve.
To do so, add the DNS servers and domains provided by a Incus 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.
@ -60,17 +60,17 @@ This command has been deprecated in newer releases of `systemd`, but it is still
```
The `resolved` configuration persists as long as the bridge exists.
You must repeat the commands after each reboot and after LXD is restarted, or make it persistent as described below.
You must repeat the commands after each reboot and after Incus is restarted, or make it persistent as described below.
## Make the `resolved` configuration persistent
You can automate the `systemd-resolved` DNS configuration, so that it is applied on system start and takes effect when LXD creates the network interface.
You can automate the `systemd-resolved` DNS configuration, so that it is applied on system start and takes effect when Incus creates the network interface.
To do so, create a `systemd` unit file named `/etc/systemd/system/lxd-dns-<network_bridge>.service` with the following content:
```
[Unit]
Description=LXD per-link DNS configuration for <network_bridge>
Description=Incus per-link DNS configuration for <network_bridge>
BindsTo=sys-subsystem-net-devices-<network_bridge>.device
After=sys-subsystem-net-devices-<network_bridge>.device
@ -93,7 +93,7 @@ Then enable and start the service with the following commands:
sudo systemctl daemon-reload
sudo systemctl enable --now lxd-dns-<network_bridge>
If the respective bridge already exists (because LXD is already running), you can use the following command to check that the new service has started:
If the respective bridge already exists (because Incus is already running), you can use the following command to check that the new service has started:
sudo systemctl status lxd-dns-<network_bridge>.service
@ -102,7 +102,7 @@ You should see output similar to the following:
```{terminal}
:input: sudo systemctl status lxd-dns-lxdbr0.service
● lxd-dns-lxdbr0.service - LXD per-link DNS configuration for lxdbr0
● lxd-dns-lxdbr0.service - Incus per-link DNS configuration for lxdbr0
Loaded: loaded (/etc/systemd/system/lxd-dns-lxdbr0.service; enabled; vendor preset: enabled)
Active: inactive (dead) since Mon 2021-06-14 17:03:12 BST; 1min 2s ago
Process: 9433 ExecStart=/usr/bin/resolvectl dns lxdbr0 n.n.n.n (code=exited, status=0/SUCCESS)

6
doc/howto/network_create.md
View File

@ -47,7 +47,7 @@ If you do not specify a `--type` argument, the default type of `bridge` is used.
(network-create-cluster)=
### Create a network in a cluster
If you are running a LXD cluster and want to create a network, you must create the network for each cluster member separately.
If you are running a Incus cluster and want to create a network, you must create the network for each cluster member separately.
The reason for this is that the network configuration, for example, the name of the parent network interface, might be different between cluster members.
Therefore, you must first create a pending network on each member with the `--target=<cluster_member>` flag and the appropriate configuration for the member.
@ -80,8 +80,8 @@ To do so, use the following command:
incus network attach <network_name> <instance_name> [<device_name>] [<interface_name>]
The device name and the interface name are optional, but we recommend specifying at least the device name.
If not specified, LXD uses the network name as the device name, which might be confusing and cause problems.
For example, LXD images perform IP auto-configuration on the `eth0` interface, which does not work if the interface is called differently.
If not specified, Incus uses the network name as the device name, which might be confusing and cause problems.
For example, Incus images perform IP auto-configuration on the `eth0` interface, which does not work if the interface is called differently.
For example, to attach the network `my-network` to the instance `my-instance` as `eth0` device, enter the following command:

14
doc/howto/network_increase_bandwidth.md
View File

@ -1,11 +1,11 @@
(network-increase-bandwidth)=
# How to increase the network bandwidth
You can increase the network bandwidth of your LXD setup by configuring the transmit queue length (`txqueuelen`).
You can increase the network bandwidth of your Incus setup by configuring the transmit queue length (`txqueuelen`).
This change makes sense in the following scenarios:
- You have a NIC with 1 GbE or higher on a LXD host with a lot of local activity (instance-instance connections or host-instance connections).
- You have an internet connection with 1 GbE or higher on your LXD host.
- You have a NIC with 1 GbE or higher on a Incus host with a lot of local activity (instance-instance connections or host-instance connections).
- You have an internet connection with 1 GbE or higher on your Incus host.
The more instances you use, the more you can benefit from this tweak.
@ -17,11 +17,11 @@ In general, you should use small `txqueuelen` values with slow devices with a hi
For the `net.core.netdev_max_backlog` value, a good guideline is to use the minimum value of the `net.ipv4.tcp_mem` configuration.
```
## Increase the network bandwidth on the LXD host
## Increase the network bandwidth on the Incus host
Complete the following steps to increase the network bandwidth on the LXD host:
Complete the following steps to increase the network bandwidth on the Incus host:
1. Increase the transmit queue length (`txqueuelen`) of both the real NIC and the LXD NIC (for example, `lxdbr0`).
1. Increase the transmit queue length (`txqueuelen`) of both the real NIC and the Incus NIC (for example, `lxdbr0`).
You can do this temporarily for testing with the following command:
ifconfig <interface> txqueuelen 10000
@ -44,5 +44,5 @@ Complete the following steps to increase the network bandwidth on the LXD host:
You must also change the `txqueuelen` value for all Ethernet interfaces in your instances.
To do this, use one of the following methods:
- Apply the same changes as described above for the LXD host.
- Apply the same changes as described above for the Incus host.
- Set the `queue.tx.length` device option on the instance profile or configuration.

8
doc/howto/network_ipam.md
View File

@ -1,9 +1,9 @@
(network-ipam)=
# How to display IPAM information of a LXD deployment
# How to display IPAM information of a Incus deployment
{abbr}`IPAM (IP Address Management)` is a method used to plan, track, and manage the information associated with a computer network's IP address space. In essence, it's a way of organizing, monitoring, and manipulating the IP space in a network.
Checking the IPAM information for your LXD setup can help you debug networking issues. You can see which IP addresses are used for instances, network interfaces, forwards, and load balancers and use this information to track down where traffic is lost.
Checking the IPAM information for your Incus setup can help you debug networking issues. You can see which IP addresses are used for instances, network interfaces, forwards, and load balancers and use this information to track down where traffic is lost.
To display IPAM information, enter the following command:
@ -31,7 +31,7 @@ The resulting output will look something like this:
...
```
Each listed entry lists the IP address (in CIDR notation) of one of the following LXD entities: `network`, `network-forward`, `network-load-balancer`, and `instance`.
Each listed entry lists the IP address (in CIDR notation) of one of the following Incus entities: `network`, `network-forward`, `network-load-balancer`, and `instance`.
An entry contains an IP address using the CIDR notation.
It also contains a LXD resource URI, the type of the entity, whether it is in NAT mode, and the hardware address (only for the `instance` entity).
It also contains a Incus resource URI, the type of the entity, whether it is in NAT mode, and the hardware address (only for the `instance` entity).

2
doc/howto/network_ovn_peers.md
View File

@ -9,7 +9,7 @@ By default, traffic between two OVN networks goes through the uplink network.
This path is inefficient, however, because packets must leave the OVN subsystem and transit through the host's networking stack (and, potentially, an external network) and back into the OVN subsystem of the target network.
Depending on how the host's networking is configured, this might limit the available bandwidth (if the OVN overlay network is on a higher bandwidth network than the host's external network).
Therefore, LXD allows creating peer routing relationships between two OVN networks.
Therefore, Incus allows creating peer routing relationships between two OVN networks.
Using this method, traffic between the two networks can go directly from one OVN network to the other and thus stays within the OVN subsystem, rather than transiting through the uplink network.
## Create a routing relationship between networks

26
doc/howto/network_ovn_setup.md
View File

@ -1,11 +1,11 @@
(network-ovn-setup)=
# How to set up OVN with LXD
# How to set up OVN with Incus
See the following sections for how to set up a basic OVN network, either as a standalone network or to host a small LXD cluster.
See the following sections for how to set up a basic OVN network, either as a standalone network or to host a small Incus cluster.
## Set up a standalone OVN network
Complete the following steps to create a standalone OVN network that is connected to a managed LXD parent bridge network (for example, `lxdbr0`) for outbound connectivity.
Complete the following steps to create a standalone OVN network that is connected to a managed Incus parent bridge network (for example, `lxdbr0`) for outbound connectivity.
1. Install the OVN tools on the local server:
@ -42,16 +42,16 @@ Complete the following steps to create a standalone OVN network that is connecte
+------+---------+---------------------+----------------------------------------------+-----------+-----------+
```
## Set up a LXD cluster on OVN
## Set up a Incus cluster on OVN
```{youtube} https://www.youtube.com/watch?v=1M__Rm9iZb8
```
Complete the following steps to set up a LXD cluster that uses an OVN network.
Complete the following steps to set up a Incus cluster that uses an OVN network.
Just like LXD, the distributed database for OVN must be run on a cluster that consists of an odd number of members.
Just like Incus, the distributed database for OVN must be run on a cluster that consists of an odd number of members.
The following instructions use the minimum of three servers, which run both the distributed database for OVN and the OVN controller.
In addition, you can add any number of servers to the LXD cluster that run only the OVN controller.
In addition, you can add any number of servers to the Incus cluster that run only the OVN controller.
See the linked YouTube video for the complete tutorial using four machines.
1. Complete the following steps on the three machines that you want to run the distributed database for OVN:
@ -123,9 +123,9 @@ See the linked YouTube video for the complete tutorial using four machines.
external_ids:ovn-encap-type=geneve \
external_ids:ovn-encap-ip=<local>
1. Create a LXD cluster by running `incus admin init` on all machines.
1. Create a Incus cluster by running `incus admin init` on all machines.
On the first machine, create the cluster.
Then join the other machines with tokens by running [`incus cluster add <machine_name>`](incus_cluster_add.md) on the first machine and specifying the token when initializing LXD on the other machine.
Then join the other machines with tokens by running [`incus cluster add <machine_name>`](incus_cluster_add.md) on the first machine and specifying the token when initializing Incus on the other machine.
1. On the first machine, create and configure the uplink network:
incus network create UPLINK --type=physical parent=<uplink_interface> --target=<machine_name_1>
@ -157,8 +157,8 @@ See the linked YouTube video for the complete tutorial using four machines.
IP ranges
: Use suitable IP ranges based on the assigned IPs.
1. Still on the first machine, configure LXD to be able to communicate with the OVN DB cluster.
To do so, find the value for `ovn-northd-nb-db` in `/etc/default/ovn-central` and provide it to LXD with the following command:
1. Still on the first machine, configure Incus to be able to communicate with the OVN DB cluster.
To do so, find the value for `ovn-northd-nb-db` in `/etc/default/ovn-central` and provide it to Incus with the following command:
incus config set network.ovn.northbound_connection <ovn-northd-nb-db>
@ -178,9 +178,9 @@ See the linked YouTube video for the complete tutorial using four machines.
ping <nameserver>
ping6 -n www.example.com
## Send OVN logs to LXD
## Send OVN logs to Incus
Complete the following steps to have the OVN controller send its logs to LXD.
Complete the following steps to have the OVN controller send its logs to Incus.
1. Enable the syslog socket:

12
doc/howto/network_zones.md
View File

@ -12,10 +12,10 @@ Network zones are available for the {ref}`network-ovn` and the {ref}`network-bri
```{youtube} https://www.youtube.com/watch?v=2MqpJOogNVQ
```
Network zones can be used to serve DNS records for LXD networks.
Network zones can be used to serve DNS records for Incus networks.
You can use network zones to automatically maintain valid forward and reverse records for all your instances.
This can be useful if you are operating a LXD cluster with multiple instances across many networks.
This can be useful if you are operating a Incus cluster with multiple instances across many networks.
Having DNS records for each instance makes it easier to access network services running on an instance.
It is also important when hosting, for example, an outbound SMTP service.
@ -27,7 +27,7 @@ Each network can be associated to different zones:
- IPv4 reverse DNS records - single zone
- IPv6 reverse DNS records - single zone
LXD will then automatically manage forward and reverse records for all instances, network gateways and downstream network ports and serve those zones for zone transfer to the operator’s production DNS servers.
Incus will then automatically manage forward and reverse records for all instances, network gateways and downstream network ports and serve those zones for zone transfer to the operator’s production DNS servers.
## Project views
@ -105,15 +105,15 @@ For example, running `dig @<DNS_server_IP> -p <DNS_server_PORT> axfr 2.0.192.in-
To make use of network zones, you must enable the built-in DNS server.
To do so, set the {config:option}`server-core:core.dns_address` configuration option to a local address on the LXD server.
To do so, set the {config:option}`server-core:core.dns_address` configuration option to a local address on the Incus server.
To avoid conflicts with an existing DNS we suggest not using the port 53.
This is the address on which the DNS server will listen.
Note that in a LXD cluster, the address may be different on each cluster member.
Note that in a Incus cluster, the address may be different on each cluster member.
```{note}
The built-in DNS server supports only zone transfers through AXFR.
It cannot be directly queried for DNS records.
Therefore, the built-in DNS server must be used in combination with an external DNS server (`bind9`, `nsd`, ...), which will transfer the entire zone from LXD, refresh it upon expiry and provide authoritative answers to DNS requests.
Therefore, the built-in DNS server must be used in combination with an external DNS server (`bind9`, `nsd`, ...), which will transfer the entire zone from Incus, refresh it upon expiry and provide authoritative answers to DNS requests.
Authentication for zone transfers is configured on a per-zone basis, with peers defined in the zone configuration and a combination of IP address matching and TSIG-key based authentication.
```

14
doc/howto/projects_confine.md
View File

@ -11,7 +11,7 @@ How to confine a project to a specific user depends on the authentication method
```{youtube} https://www.youtube.com/watch?v=4iNpiL-lrXU&t=525s
```
You can confine access to specific projects by restricting the TLS client certificate that is used to connect to the LXD server.
You can confine access to specific projects by restricting the TLS client certificate that is used to connect to the Incus server.
See {ref}`authentication-tls-certs` for detailed information.
To confine the access from the time the client certificate is added, you must either use token authentication or add the client certificate to the server directly.
@ -48,21 +48,21 @@ This configuration pre-selects the specified project.
However, it does not confine the client to this project.
```
## Confine projects to specific LXD users
## Confine projects to specific Incus users
```{youtube} https://www.youtube.com/watch?v=6O0q3rSWr8A
```
If you use the [LXD snap](https://snapcraft.io/lxd), you can configure the multi-user LXD daemon contained in the snap to dynamically create projects for all users in a specific user group.
If you use the [Incus snap](https://snapcraft.io/lxd), you can configure the multi-user Incus daemon contained in the snap to dynamically create projects for all users in a specific user group.
To do so, set the `daemon.user.group` configuration option to the corresponding user group:
sudo snap set lxd daemon.user.group=<user_group>
Make sure that all user accounts that you want to be able to use LXD are a member of this group.
Make sure that all user accounts that you want to be able to use Incus are a member of this group.
Once a member of the group issues a LXD command, LXD creates a confined project for this user and switches to this project.
If LXD has not been {ref}`initialized <initialize>` at this point, it is automatically initialized (with the default settings).
Once a member of the group issues a Incus command, Incus creates a confined project for this user and switches to this project.
If Incus has not been {ref}`initialized <initialize>` at this point, it is automatically initialized (with the default settings).
If you want to customize the project settings, for example, to impose limits or restrictions, you can do so after the project has been created.
To modify the project configuration, you must have full access to LXD, which means you must be part of the `lxd` group and not only the group that you configured as the LXD user group.
To modify the project configuration, you must have full access to Incus, which means you must be part of the `lxd` group and not only the group that you configured as the Incus user group.

10
doc/howto/projects_work.md
View File

@ -1,10 +1,10 @@
(projects-work)=
# How to work with different projects
If you have more projects than just the `default` profile, you must make sure to use or address the correct project when working with LXD.
If you have more projects than just the `default` profile, you must make sure to use or address the correct project when working with Incus.
```{note}
If you have projects that are {ref}`confined to specific users <projects-confined>`, only users with full access to LXD can see all projects.
If you have projects that are {ref}`confined to specific users <projects-confined>`, only users with full access to Incus can see all projects.
Users without full access can only see information for the projects to which they have access.
```
@ -24,7 +24,7 @@ By default, the output is presented as a list:
+----------------------+--------+----------+-----------------+-----------------+----------+---------------+---------------------+---------+
| NAME | IMAGES | PROFILES | STORAGE VOLUMES | STORAGE BUCKETS | NETWORKS | NETWORK ZONES | DESCRIPTION | USED BY |
+----------------------+--------+----------+-----------------+-----------------+----------+---------------+---------------------+---------+
| default | YES | YES | YES | YES | YES | YES | Default LXD project | 19 |
| default | YES | YES | YES | YES | YES | YES | Default Incus project | 19 |
+----------------------+--------+----------+-----------------+-----------------+----------+---------------+---------------------+---------+
| my-project (current) | YES | NO | NO | NO | YES | YES | | 0 |
+----------------------+--------+----------+-----------------+-----------------+----------+---------------+---------------------+---------+
@ -35,7 +35,7 @@ See [`incus project list --help`](incus_project_list.md) for more information.
## Switch projects
By default, all commands that you issue in LXD affect the project that you are currently using.
By default, all commands that you issue in Incus affect the project that you are currently using.
To see which project you are in, use the [`incus project list`](incus_project_list.md) command.
To switch to a different project, enter the following command:
@ -45,7 +45,7 @@ To switch to a different project, enter the following command:
## Target a project
Instead of switching to a different project, you can target a specific project when running a command.
Many LXD commands support the `--project` flag to run an action in a different project.
Many Incus commands support the `--project` flag to run an action in a different project.
```{note}
You can target only projects that you have permission for.

8
doc/howto/server_configure.md
View File

@ -1,9 +1,9 @@
(server-configure)=
# How to configure the LXD server
# How to configure the Incus server
See {ref}`server` for all configuration options that are available for the LXD server.
See {ref}`server` for all configuration options that are available for the Incus server.
If the LXD server is part of a cluster, some of the options apply to the cluster, while others apply only to the local server, thus the cluster member.
If the Incus server is part of a cluster, some of the options apply to the cluster, while others apply only to the local server, thus the cluster member.
In the {ref}`server` option tables, options that apply to the cluster are marked with a `global` scope, while options that apply to the local server are marked with a `local` scope.
## Configure server options
@ -12,7 +12,7 @@ You can configure a server option with the following command:
incus config set <key> <value>
For example, to allow remote access to the LXD server on port 8443, enter the following command:
For example, to allow remote access to the Incus server on port 8443, enter the following command:
incus config set core.https_address :8443

14
doc/howto/server_expose.md
View File

@ -1,12 +1,12 @@
(server-expose)=
# How to expose LXD to the network
# How to expose Incus to the network
By default, LXD can be used only by local users through a Unix socket and is not accessible over the network.
By default, Incus can be used only by local users through a Unix socket and is not accessible over the network.
To expose LXD to the network, you must configure it to listen to addresses other than the local Unix socket.
To expose Incus to the network, you must configure it to listen to addresses other than the local Unix socket.
To do so, set the {config:option}`server-core:core.https_address` server configuration option.
For example, to allow access to the LXD server on port `8443`, enter the following command:
For example, to allow access to the Incus server on port `8443`, enter the following command:
incus config set core.https_address :8443
@ -39,12 +39,12 @@ For example:
:input: incus config set core.https_address 10.68.216.12
```
All remote clients can then connect to LXD and access any image that is marked for public use.
All remote clients can then connect to Incus and access any image that is marked for public use.
(server-authenticate)=
## Authenticate with the LXD server
## Authenticate with the Incus server
To be able to access the remote API, clients must authenticate with the LXD server.
To be able to access the remote API, clients must authenticate with the Incus server.
There are several authentication methods; see {ref}`authentication` for detailed information.
The recommended method is to add the client's TLS certificate to the server's trust store through a trust token.

2
doc/howto/storage_backup_volume.md
View File

@ -19,7 +19,7 @@ Which method to choose depends both on your use case and on the storage driver y
In general, snapshots are quick and space efficient (depending on the storage driver), but they are stored in the same storage pool as the {{type}} and therefore not too reliable.
Export files can be stored on different disks and are therefore more reliable.
They can also be used to restore the {{type}} into a different storage pool.
If you have a separate, network-connected LXD server available, regularly copying {{type}}s to this other server gives high reliability as well, and this method can also be used to back up snapshots of the {{type}}.
If you have a separate, network-connected Incus server available, regularly copying {{type}}s to this other server gives high reliability as well, and this method can also be used to back up snapshots of the {{type}}.
<!-- Include end backup types -->
```{note}

2
doc/howto/storage_buckets.md
View File

@ -8,7 +8,7 @@ See the following sections for instructions on how to create, configure, view an
## Configure the S3 address
If you want to use storage buckets on local storage (thus in a `dir`, `btrfs`, `lvm`, or `zfs` pool), you must configure the S3 address for your LXD server.
If you want to use storage buckets on local storage (thus in a `dir`, `btrfs`, `lvm`, or `zfs` pool), you must configure the S3 address for your Incus server.
This is the address that you can then use to access the buckets through the S3 protocol.
To configure the S3 address, set the {config:option}`server-core:core.storage_buckets_address` server configuration option.

4
doc/howto/storage_move_volume.md
View File

@ -50,9 +50,9 @@ To copy or move a custom storage volume from one cluster member to another, add
Add the `--target-project` to copy or move a custom storage volume to a different project.
## Copy or move between LXD servers
## Copy or move between Incus servers
You can copy or move custom storage volumes between different LXD servers by specifying the remote for each pool:
You can copy or move custom storage volumes between different Incus servers by specifying the remote for each pool:
incus storage volume copy <source_remote>:<source_pool_name>/<source_volume_name> <target_remote>:<target_pool_name>/<target_volume_name>
incus storage volume move <source_remote>:<source_pool_name>/<source_volume_name> <target_remote>:<target_pool_name>/<target_volume_name>

8
doc/howto/storage_pools.md
View File

@ -10,14 +10,14 @@ See the following sections for instructions on how to create, configure, view an
(storage-create-pool)=
## Create a storage pool
LXD creates a storage pool during initialization.
Incus creates a storage pool during initialization.
You can add more storage pools later, using the same driver or different drivers.
To create a storage pool, use the following command:
incus storage create <pool_name> <driver> [configuration_options...]
Unless specified otherwise, LXD sets up loop-based storage with a sensible default size (20% of the free disk space, but at least 5 GiB and at most 30 GiB).
Unless specified otherwise, Incus sets up loop-based storage with a sensible default size (20% of the free disk space, but at least 5 GiB and at most 30 GiB).
See the {ref}`storage-drivers` documentation for a list of available configuration options for each driver.
@ -156,7 +156,7 @@ Use the existing Ceph Object Gateway `https://www.example.com/radosgw` to create
(storage-pools-cluster)=
### Create a storage pool in a cluster
If you are running a LXD cluster and want to add a storage pool, you must create the storage pool for each cluster member separately.
If you are running a Incus cluster and want to add a storage pool, you must create the storage pool for each cluster member separately.
The reason for this is that the configuration, for example, the storage location or the size of the pool, might be different between cluster members.
Therefore, you must first create a pending storage pool on each member with the `--target=<cluster_member>` flag and the appropriate configuration for the member.
@ -229,5 +229,5 @@ If you need more storage, you can increase the size of your storage pool by chan
incus storage set <pool_name> size=<new_size>
This will only work for loop-backed storage pools that are managed by LXD.
This will only work for loop-backed storage pools that are managed by Incus.
You can only grow the pool (increase its size), not shrink it.

2
doc/howto/storage_volumes.md
View File

@ -8,7 +8,7 @@ See the following sections for instructions on how to create, configure, view an
## Create a custom storage volume
When you create an instance, LXD automatically creates a storage volume that is used as the root disk for the instance.
When you create an instance, Incus automatically creates a storage volume that is used as the root disk for the instance.
You can add custom storage volumes to your instances.
Such custom storage volumes are independent of the instance, which means that they can be backed up separately and are retained until you delete them.

20
doc/image-handling.md
View File

@ -4,8 +4,8 @@
```{youtube} https://www.youtube.com/watch?v=wT7IDjo0Wgg
```
LXD uses an image-based workflow.
Each instance is based on an image, which contains a basic operating system (for example, a Linux distribution) and some LXD-related information.
Incus uses an image-based workflow.
Each instance is based on an image, which contains a basic operating system (for example, a Linux distribution) and some Incus-related information.
Images are available from remote image stores (see {ref}`remote-image-servers` for an overview), but you can also create your own images, either based on an existing instances or a rootfs image.
@ -13,22 +13,22 @@ You can copy images from remote servers to your local image store, or copy local
You can also use a local image to create a remote instance.
Each image is identified by a fingerprint (SHA256).
To make it easier to manage images, LXD allows defining one or more aliases for each image.
To make it easier to manage images, Incus allows defining one or more aliases for each image.
## Caching
When you create an instance using a remote image, LXD downloads the image and caches it locally.
When you create an instance using a remote image, Incus downloads the image and caches it locally.
It is stored in the local image store with the cached flag set.
The image is kept locally as a private image until either:
- The image has not been used to create a new instance for the number of days set in {config:option}`server-images:images.remote_cache_expiry`.
- The image's expiry date (one of the image properties; see {ref}`images-manage-edit` for information on how to change it) is reached.
LXD keeps track of the image usage by updating the `last_used_at` image property every time a new instance is spawned from the image.
Incus keeps track of the image usage by updating the `last_used_at` image property every time a new instance is spawned from the image.
## Auto-update
LXD can automatically keep images that come from a remote server up to date.
Incus can automatically keep images that come from a remote server up to date.
```{note}
Only images that are requested through an alias can be updated.
@ -42,18 +42,18 @@ Whether auto-update is enabled for an image depends on how the image was downloa
You can change this behavior for an image by [editing the `auto_update` property](images-manage-edit).
On startup and after every {config:option}`server-images:images.auto_update_interval` (by default, every six hours), the LXD daemon checks for more recent versions of all the images in the store that are marked to be auto-updated and have a recorded source server.
On startup and after every {config:option}`server-images:images.auto_update_interval` (by default, every six hours), the Incus daemon checks for more recent versions of all the images in the store that are marked to be auto-updated and have a recorded source server.
When a new version of an image is found, it is downloaded into the image store.
Then any aliases pointing to the old image are moved to the new one, and the old image is removed from the store.
To not delay instance creation, LXD does not check if a new version is available when creating an instance from a cached image.
To not delay instance creation, Incus does not check if a new version is available when creating an instance from a cached image.
This means that the instance might use an older version of an image for the new instance until the image is updated at the next update interval.
## Special image properties
Image properties that begin with the prefix `requirements` (for example, `requirements.XYZ`) are used by LXD to determine the compatibility of the host system and the instance that is created based on the image.
If these are incompatible, LXD does not start the instance.
Image properties that begin with the prefix `requirements` (for example, `requirements.XYZ`) are used by Incus to determine the compatibility of the host system and the instance that is created based on the image.
If these are incompatible, Incus does not start the instance.
The following requirements are supported:

10
doc/index.md
View File

@ -2,9 +2,9 @@
relatedlinks: https://ubuntu.com/lxd, https://ubuntu.com/blog/open-source-for-beginners-dev-environment-with-lxd
---
# LXD
# Incus
LXD is a modern, secure and powerful system container and virtual machine manager.
Incus is a modern, secure and powerful system container and virtual machine manager.
% Include content from [../README.md](../README.md)
```{include} ../README.md
@ -32,17 +32,17 @@ See [Security](security.md) for detailed information.
## Project and community
LXD is free software and developed under the [Apache 2 license](https://www.apache.org/licenses/LICENSE-2.0).
Incus is free software and developed under the [Apache 2 license](https://www.apache.org/licenses/LICENSE-2.0).
It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.
The LXD project is sponsored by [Canonical Ltd](https://www.canonical.com).
The Incus project is sponsored by [Canonical Ltd](https://www.canonical.com).
- [Code of Conduct](https://github.com/canonical/lxd/blob/main/CODE_OF_CONDUCT.md)
- [Contribute to the project](contributing.md)
- [Release announcements](https://discourse.ubuntu.com/c/lxd/news/)
- [Release tarballs](https://github.com/canonical/lxd/releases/)
- [Get support](support.md)
- [Watch tutorials and announcements on YouTube](https://www.youtube.com/c/LXDvideos)
- [Watch tutorials and announcements on YouTube](https://www.youtube.com/c/Incusvideos)
- [Discuss on IRC](https://web.libera.chat/#lxd) (see [Getting started with IRC](https://discuss.linuxcontainers.org/t/getting-started-with-irc/11920) if needed)
- [Ask and answer questions on the forum](https://discourse.ubuntu.com/c/lxd/)

96
doc/installing.md
View File

@ -3,12 +3,12 @@ discourse: ubuntu:37214, ubuntu:37327
---
(installing)=
# How to install LXD
# How to install Incus
The easiest way to install LXD is to {ref}`install one of the available packages <installing-from-package>`, but you can also {ref}`install LXD from the sources <installing_from_source>`.
The easiest way to install Incus is to {ref}`install one of the available packages <installing-from-package>`, but you can also {ref}`install Incus from the sources <installing_from_source>`.
After installing LXD, make sure you have a `lxd` group on your system.
Users in this group can interact with LXD.
After installing Incus, make sure you have a `lxd` group on your system.
Users in this group can interact with Incus.
See {ref}`installing-manage-access` for instructions.
## Choose your release
@ -22,28 +22,28 @@ See {ref}`installing-manage-access` for instructions.
LTS releases are recommended for production environments, because they benefit from regular bugfix and security updates.
However, there are no new features added to an LTS release, nor any kind of behavioral change.
To get all the latest features and monthly updates to LXD, use the feature release branch instead.
To get all the latest features and monthly updates to Incus, use the feature release branch instead.
(installing-from-package)=
## Install LXD from a package
## Install Incus from a package
The LXD daemon only works on Linux.
The Incus daemon only works on Linux.
The client tool ([`lxc`](incus.md)) is available on most platforms.
### Linux
The easiest way to install LXD on Linux is to install the {ref}`installing-snap-package`, which is available for different Linux distributions.
The easiest way to install Incus on Linux is to install the {ref}`installing-snap-package`, which is available for different Linux distributions.
If this option does not work for you, see the {ref}`installing-other`.
(installing-snap-package)=
#### Snap package
LXD publishes and tests [snap packages](https://snapcraft.io/lxd) that work for a number of Linux distributions (for example, Ubuntu, Arch Linux, Debian, Fedora, and OpenSUSE).
Incus publishes and tests [snap packages](https://snapcraft.io/lxd) that work for a number of Linux distributions (for example, Ubuntu, Arch Linux, Debian, Fedora, and OpenSUSE).
Complete the following steps to install the snap:
1. Check the [LXD snap page on Snapcraft](https://snapcraft.io/lxd) to see if a snap is available for your Linux distribution.
1. Check the [Incus snap page on Snapcraft](https://snapcraft.io/lxd) to see if a snap is available for your Linux distribution.
If it is not, use one of the {ref}`installing-other`.
1. Install `snapd`.
@ -54,14 +54,14 @@ Complete the following steps to install the snap:
sudo snap install lxd
For the LXD 5.0 LTS release, use:
For the Incus 5.0 LTS release, use:
sudo snap install lxd --channel=5.0/stable
For more information about LXD snap packages (regarding more versions, update management etc.), see [Managing the LXD snap](https://discuss.linuxcontainers.org/t/managing-the-lxd-snap/8178).
For more information about Incus snap packages (regarding more versions, update management etc.), see [Managing the Incus snap](https://discuss.linuxcontainers.org/t/managing-the-lxd-snap/8178).
```{note}
On Ubuntu 18.04, if you previously had the LXD deb package installed, you can migrate all your existing data over with the following command:
On Ubuntu 18.04, if you previously had the Incus deb package installed, you can migrate all your existing data over with the following command:
sudo lxd.migrate
```
@ -75,23 +75,23 @@ Some Linux distributions provide installation options other than the snap packag
```{group-tab} Alpine Linux
To install the feature branch of LXD on Alpine Linux, run:
To install the feature branch of Incus on Alpine Linux, run:
apk add lxd
```
```{group-tab} Arch Linux
To install the feature branch of LXD on Arch Linux, run:
To install the feature branch of Incus on Arch Linux, run:
pacman -S lxd
```
```{group-tab} Fedora
Fedora RPM packages for LXC/LXD are available in the [COPR repository](https://copr.fedorainfracloud.org/coprs/ganto/lxc4/).
Fedora RPM packages for LXC/Incus are available in the [COPR repository](https://copr.fedorainfracloud.org/coprs/ganto/lxc4/).
To install the LXD package for the feature branch, run:
To install the Incus package for the feature branch, run:
dnf copr enable ganto/lxc4
dnf install lxd
@ -101,7 +101,7 @@ See the [Installation Guide](https://github.com/ganto/copr-lxc4/wiki) for more d
```{group-tab} Gentoo
To install the feature branch of LXD on Gentoo, run:
To install the feature branch of Incus on Gentoo, run:
emerge --ask lxd
```
@ -118,27 +118,27 @@ The builds for other operating systems include only the client, not the server.
```{group-tab} macOS
LXD publishes builds of the LXD client for macOS through [Homebrew](https://brew.sh/).
Incus publishes builds of the Incus client for macOS through [Homebrew](https://brew.sh/).
To install the feature branch of LXD, run:
To install the feature branch of Incus, run:
brew install lxc
```
```{group-tab} Windows
The LXD client on Windows is provided as a [Chocolatey](https://community.chocolatey.org/packages/lxc) package.
The Incus client on Windows is provided as a [Chocolatey](https://community.chocolatey.org/packages/lxc) package.
To install it:
1. Install Chocolatey by following the [installation instructions](https://docs.chocolatey.org/en-us/choco/setup).
1. Install the LXD client:
1. Install the Incus client:
choco install lxc
```
````
You can also find native builds of the LXD client on [GitHub](https://github.com/canonical/lxd/actions).
You can also find native builds of the Incus client on [GitHub](https://github.com/canonical/lxd/actions).
To download a specific build:
1. Make sure that you are logged into your GitHub account.
@ -146,12 +146,12 @@ To download a specific build:
1. Select the latest build and download the suitable artifact.
(installing_from_source)=
## Install LXD from source
## Install Incus from source
Follow these instructions if you want to build and install LXD from the source code.
Follow these instructions if you want to build and install Incus from the source code.
We recommend having the latest versions of `liblxc` (>= 4.0.0 required)
available for LXD development. Additionally, LXD requires Golang 1.18 or
available for Incus development. Additionally, Incus requires Golang 1.18 or
later to work. On Ubuntu, you can get those with:
```bash
@ -159,7 +159,7 @@ sudo apt update
sudo apt install acl attr autoconf automake dnsmasq-base git golang libacl1-dev libcap-dev liblxc1 liblxc-dev libsqlite3-dev libtool libudev-dev liblz4-dev libuv1-dev make pkg-config rsync squashfs-tools tar tcl xz-utils ebtables
```
There are a few storage drivers for LXD besides the default `dir` driver.
There are a few storage drivers for Incus besides the default `dir` driver.
Installing these tools adds a bit to initramfs and may slow down your
host boot, but are needed if you'd like to use a particular driver:
@ -177,7 +177,7 @@ sudo apt install busybox-static curl gettext jq sqlite3 socat bind9-dnsutils
### From source: Build the latest version
These instructions for building from source are suitable for individual developers who want to build the latest version
of LXD, or build a specific release of LXD which may not be offered by their Linux distribution. Source builds for
of Incus, or build a specific release of Incus which may not be offered by their Linux distribution. Source builds for
integration into Linux distributions are not covered here and may be covered in detail in a separate document in the
future.
@ -186,13 +186,13 @@ git clone https://github.com/canonical/lxd
cd lxd
```
This will download the current development tree of LXD and place you in the source tree.
Then proceed to the instructions below to actually build and install LXD.
This will download the current development tree of Incus and place you in the source tree.
Then proceed to the instructions below to actually build and install Incus.
### From source: Build a release
The LXD release tarballs bundle a complete dependency tree as well as a
local copy of `libraft` and `libdqlite` for LXD's database setup.
The Incus release tarballs bundle a complete dependency tree as well as a
local copy of `libraft` and `libdqlite` for Incus's database setup.
```bash
tar zxvf lxd-4.18.tar.gz
@ -200,14 +200,14 @@ cd lxd-4.18
```
This will unpack the release tarball and place you inside of the source tree.
Then proceed to the instructions below to actually build and install LXD.
Then proceed to the instructions below to actually build and install Incus.
### Start the build
The actual building is done by two separate invocations of the Makefile: `make deps` -- which builds libraries required
by LXD -- and `make`, which builds LXD itself. At the end of `make deps`, a message will be displayed which will specify environment variables that should be set prior to invoking `make`. As new versions of LXD are released, these environment
by Incus -- and `make`, which builds Incus itself. At the end of `make deps`, a message will be displayed which will specify environment variables that should be set prior to invoking `make`. As new versions of Incus are released, these environment
variable settings may change, so be sure to use the ones displayed at the end of the `make deps` process, as the ones
below (shown for example purposes) may not exactly match what your version of LXD requires:
below (shown for example purposes) may not exactly match what your version of Incus requires:
We recommend having at least 2GiB of RAM to allow the build to complete.
@ -237,18 +237,18 @@ export PATH="${PATH}:$(go env GOPATH)/bin"
export LD_LIBRARY_PATH="$(go env GOPATH)/deps/dqlite/.libs/:$(go env GOPATH)/deps/raft/.libs/:${LD_LIBRARY_PATH}"
```
Now, the `lxd` and `lxc` binaries will be available to you and can be used to set up LXD. The binaries will automatically find and use the dependencies built in `$(go env GOPATH)/deps` thanks to the `LD_LIBRARY_PATH` environment variable.
Now, the `lxd` and `lxc` binaries will be available to you and can be used to set up Incus. The binaries will automatically find and use the dependencies built in `$(go env GOPATH)/deps` thanks to the `LD_LIBRARY_PATH` environment variable.
### Machine setup
You'll need sub{u,g}ids for root, so that LXD can create the unprivileged containers:
You'll need sub{u,g}ids for root, so that Incus can create the unprivileged containers:
```bash
echo "root:1000000:1000000000" | sudo tee -a /etc/subuid /etc/subgid
```
Now you can run the daemon (the `--group sudo` bit allows everyone in the `sudo`
group to talk to LXD; you can create your own group if you want):
group to talk to Incus; you can create your own group if you want):
```bash
sudo -E PATH=${PATH} LD_LIBRARY_PATH=${LD_LIBRARY_PATH} $(go env GOPATH)/bin/lxd --group sudo
@ -259,17 +259,17 @@ If `newuidmap/newgidmap` tools are present on your system and `/etc/subuid`, `et
```
(installing-manage-access)=
## Manage access to LXD
## Manage access to Incus
Access control for LXD is based on group membership.
Access control for Incus is based on group membership.
The root user and all members of the `lxd` group can interact with the local daemon.
See {ref}`security-daemon-access` for more information.
If the `lxd` group is missing on your system, create it and restart the LXD daemon.
If the `lxd` group is missing on your system, create it and restart the Incus daemon.
You can then add trusted users to the group.
Anyone added to this group will have full control over LXD.
Anyone added to this group will have full control over Incus.
Because group membership is normally only applied at login, you might need to either re-open your user session or use the `newgrp lxd` command in the shell you're using to talk to LXD.
Because group membership is normally only applied at login, you might need to either re-open your user session or use the `newgrp lxd` command in the shell you're using to talk to Incus.
````{important}
% Include content from [../README.md](../README.md)
@ -280,15 +280,15 @@ Because group membership is normally only applied at login, you might need to ei
````
(installing-upgrade)=
## Upgrade LXD
## Upgrade Incus
After upgrading LXD to a newer version, LXD might need to update its database to a new schema.
This update happens automatically when the daemon starts up after a LXD upgrade.
After upgrading Incus to a newer version, Incus might need to update its database to a new schema.
This update happens automatically when the daemon starts up after a Incus upgrade.
A backup of the database before the update is stored in the same location as the active database (for example, at `/var/snap/lxd/common/lxd/database` for the snap installation).
```{important}
After a schema update, older versions of LXD might regard the database as invalid.
That means that downgrading LXD might render your LXD installation unusable.
After a schema update, older versions of Incus might regard the database as invalid.
That means that downgrading Incus might render your Incus installation unusable.
In that case, if you need to downgrade, restore the database backup before starting the downgrade.
```

16
doc/instance-exec.md
View File

@ -1,9 +1,9 @@
(run-commands)=
# How to run commands in an instance
LXD allows to run commands inside an instance using the LXD client, without needing to access the instance through the network.
Incus allows to run commands inside an instance using the Incus client, without needing to access the instance through the network.
For containers, this always works and is handled directly by LXD.
For containers, this always works and is handled directly by Incus.
For virtual machines, the `lxd-agent` process must be running inside of the virtual machine for this to work.
To run commands inside your instance, use the [`incus exec`](incus_exec.md) command.
@ -21,7 +21,7 @@ For example, enter the following command to update the package list on your cont
### Execution mode
LXD can execute commands either interactively or non-interactively.
Incus can execute commands either interactively or non-interactively.
In interactive mode, a pseudo-terminal device (PTS) is used to handle input (stdin) and output (stdout, stderr).
This mode is automatically selected by the CLI if connected to a terminal emulator (and not run from a script).
@ -33,12 +33,12 @@ To force non-interactive mode, add either `--force-noninteractive` or `--mode no
### User, groups and working directory
LXD has a policy not to read data from within the instances or trust anything that can be found in the instance.
Therefore, LXD does not parse files like `/etc/passwd`, `/etc/group` or `/etc/nsswitch.conf` to handle user and group resolution.
Incus has a policy not to read data from within the instances or trust anything that can be found in the instance.
Therefore, Incus does not parse files like `/etc/passwd`, `/etc/group` or `/etc/nsswitch.conf` to handle user and group resolution.
As a result, LXD doesn't know the home directory for the user or the supplementary groups the user is in.
As a result, Incus doesn't know the home directory for the user or the supplementary groups the user is in.
By default, LXD runs commands as `root` (UID 0) with the default group (GID 0) and the working directory set to `/root`.
By default, Incus runs commands as `root` (UID 0) with the default group (GID 0) and the working directory set to `/root`.
You can override the user, group and working directory by specifying absolute values through the following flags:
- `--user` - the user ID for running the command
@ -60,7 +60,7 @@ Pass environment variables to the exec command
incus exec <instance_name> --env ENVVAR=VALUE -- <command>
In addition, LXD sets the following default values (unless they are passed in one of the ways described above):
In addition, Incus sets the following default values (unless they are passed in one of the ways described above):
```{list-table}
:header-rows: 1

2
doc/internals.md
View File

@ -4,7 +4,7 @@
:maxdepth: 1
daemon-behavior
Debug LXD <debugging>
Debug Incus <debugging>
environment
syscall-interception
User namespace setup <userns-idmap>

48
doc/metrics.md
View File

@ -10,22 +10,22 @@ relatedlinks: https://grafana.com/grafana/dashboards/19131-lxd/
```
<!-- Include start metrics intro -->
LXD collects metrics for all running instances as well as some internal metrics.
Incus collects metrics for all running instances as well as some internal metrics.
These metrics cover the CPU, memory, network, disk and process usage.
They are meant to be consumed by Prometheus, and you can use Grafana to display the metrics as graphs.
See {ref}`provided-metrics` for lists of available metrics.
<!-- Include end metrics intro -->
In a cluster environment, LXD returns only the values for instances running on the server that is being accessed.
In a cluster environment, Incus returns only the values for instances running on the server that is being accessed.
Therefore, you must scrape each cluster member separately.
The instance metrics are updated when calling the `/1.0/metrics` endpoint.
To handle multiple scrapers, they are cached for 8 seconds.
Fetching metrics is a relatively expensive operation for LXD to perform, so if the impact is too high, consider scraping at a higher than default interval.
Fetching metrics is a relatively expensive operation for Incus to perform, so if the impact is too high, consider scraping at a higher than default interval.
## Query the raw data
To view the raw data that LXD collects, use the [`incus query`](incus_query.md) command to query the `/1.0/metrics` endpoint:
To view the raw data that Incus collects, use the [`incus query`](incus_query.md) command to query the `/1.0/metrics` endpoint:
```{terminal}
:input: incus query /1.0/metrics
@ -78,10 +78,10 @@ To expose only the metrics API endpoint on a specific IP address and port, enter
incus config set core.metrics_address "192.0.2.101:8444"
### Add a metrics certificate to LXD
### Add a metrics certificate to Incus
Authentication for the `/1.0/metrics` API endpoint is done through a metrics certificate.
A metrics certificate (type `metrics`) is different from a client certificate (type `client`) in that it is meant for metrics only and doesn't work for interaction with instances or any other LXD entities.
A metrics certificate (type `metrics`) is different from a client certificate (type `client`) in that it is meant for metrics only and doesn't work for interaction with instances or any other Incus entities.
To create a certificate, enter the following command:
@ -105,10 +105,10 @@ incus config set core.metrics_authentication false
### Make the metrics certificate available for Prometheus
If you run Prometheus on a different machine than your LXD server, you must copy the required certificates to the Prometheus machine:
If you run Prometheus on a different machine than your Incus server, you must copy the required certificates to the Prometheus machine:
- The metrics certificate (`metrics.crt`) and key (`metrics.key`) that you created
- The LXD server certificate (`server.crt`) located in `/var/snap/lxd/common/lxd/` (if you are using the snap) or `/var/lib/lxd/` (otherwise)
- The Incus server certificate (`server.crt`) located in `/var/snap/lxd/common/lxd/` (if you are using the snap) or `/var/lib/lxd/` (otherwise)
Copy these files into a `tls` directory that is accessible to Prometheus, for example, `/var/snap/prometheus/common/tls` (if you are using the snap) or `/etc/prometheus/tls` (otherwise).
See the following example commands:
@ -120,7 +120,7 @@ mkdir /var/snap/prometheus/common/tls
# Copy newly created certificate and key to tls directory
cp metrics.crt metrics.key /var/snap/prometheus/common/tls/
# Copy LXD server certificate to tls directory
# Copy Incus server certificate to tls directory
cp /var/snap/lxd/common/lxd/server.crt /var/snap/prometheus/common/tls/
```
@ -128,11 +128,11 @@ If you are not using the snap, you must also make sure that Prometheus can read
chown -R prometheus:prometheus /etc/prometheus/tls
### Configure Prometheus to scrape from LXD
### Configure Prometheus to scrape from Incus
Finally, you must add LXD as a target to the Prometheus configuration.
Finally, you must add Incus as a target to the Prometheus configuration.
To do so, edit `/var/snap/prometheus/current/prometheus.yml` (if you are using the snap) or `/etc/prometheus/prometheus.yaml` (otherwise) and add a job for LXD.
To do so, edit `/var/snap/prometheus/current/prometheus.yml` (if you are using the snap) or `/etc/prometheus/prometheus.yaml` (otherwise) and add a job for Incus.
Here's what the configuration needs to look like:
@ -153,7 +153,7 @@ scrape_configs:
```
````{note}
The `server_name` must be specified if the LXD server certificate does not contain the same host name as used in the `targets` list.
The `server_name` must be specified if the Incus server certificate does not contain the same host name as used in the `targets` list.
To verify this, open `server.crt` and check the Subject Alternative Name (SAN) section.
For example, assume that `server.crt` has the following content:
@ -170,7 +170,7 @@ For example, assume that `server.crt` has the following content:
Since the Subject Alternative Name (SAN) list doesn't include the host name provided in the `targets` list (`foo.example.com`), you must override the name used for comparison using the `server_name` directive.
````
Here is an example of a `prometheus.yml` configuration where multiple jobs are used to scrape the metrics of multiple LXD servers:
Here is an example of a `prometheus.yml` configuration where multiple jobs are used to scrape the metrics of multiple Incus servers:
```yaml
scrape_configs:
@ -178,7 +178,7 @@ scrape_configs:
# initially bootstrapped by abydos which is why all 3 targets
# share the same `ca_file` and `server_name`. That `ca_file` corresponds
# to the `/var/snap/lxd/common/lxd/cluster.crt` file found on every member of
# the LXD cluster.
# the Incus cluster.
#
# Note: the `project` param is are provided when not using the `default` project
# or when multiple projects are used.
@ -201,7 +201,7 @@ scrape_configs:
key_file: 'tls/metrics.key'
server_name: 'abydos'
# jupiter, mars and saturn are 3 standalone LXD servers.
# jupiter, mars and saturn are 3 standalone Incus servers.
# Note: only the `default` project is used on them, so it is not specified.
- job_name: "lxd-jupiter"
metrics_path: '/1.0/metrics'
@ -242,7 +242,7 @@ After editing the configuration, restart Prometheus (for example, `snap restart
## Set up a Grafana dashboard
To visualize the metrics data, set up [Grafana](https://grafana.com/).
LXD provides a [Grafana dashboard](https://grafana.com/grafana/dashboards/19131-lxd/) that is configured to display the LXD metrics scraped by Prometheus.
Incus provides a [Grafana dashboard](https://grafana.com/grafana/dashboards/19131-lxd/) that is configured to display the Incus metrics scraped by Prometheus.
```{note}
The dashboard requires Grafana 8.4 or later.
@ -253,7 +253,7 @@ See the Grafana documentation for instructions on installing and signing in:
- [Install Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/installation/)
- [Sign in to Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/sign-in-to-grafana/)
Complete the following steps to import the [LXD dashboard](https://grafana.com/grafana/dashboards/19131-lxd/):
Complete the following steps to import the [Incus dashboard](https://grafana.com/grafana/dashboards/19131-lxd/):
1. Configure Prometheus as the data source:
@ -272,7 +272,7 @@ Complete the following steps to import the [LXD dashboard](https://grafana.com/g
1. Keep the default configuration for the other fields and click {guilabel}`Save & test`.
1. Import the LXD dashboard:
1. Import the Incus dashboard:
1. Go to {guilabel}`Dashboards` > {guilabel}`Browse`.
1. Click {guilabel}`New` and select {guilabel}`Import`.
@ -281,20 +281,20 @@ Complete the following steps to import the [LXD dashboard](https://grafana.com/g
1. In the {guilabel}`Import via grafana.com` field, enter the dashboard ID `19131`.
![Enter the LXD dashboard ID](images/grafana_dashboard_id.png)
![Enter the Incus dashboard ID](images/grafana_dashboard_id.png)
1. Click {guilabel}`Load`.
1. In the {guilabel}`LXD` drop-down menu, select the Prometheus data source that you configured.
1. In the {guilabel}`Incus` drop-down menu, select the Prometheus data source that you configured.
![Select the Prometheus data source](images/grafana_dashboard_select_datasource.png)
1. Click {guilabel}`Import`.
You should now see the LXD dashboard.
You should now see the Incus dashboard.
You can select the project and filter by instances.
![Resource overview in the LXD Grafana dashboard](images/grafana_resources.png)
![Resource overview in the Incus Grafana dashboard](images/grafana_resources.png)
At the bottom of the page, you can see data for each instance.
![Instance data in the LXD Grafana dashboard](images/grafana_instances.png)
![Instance data in the Incus Grafana dashboard](images/grafana_instances.png)

18
doc/migration.md
View File

@ -4,23 +4,23 @@
```{youtube} https://www.youtube.com/watch?v=F9GALjHtnUU
```
LXD provides tools and functionality to migrate instances in different contexts.
Incus provides tools and functionality to migrate instances in different contexts.
Migrate existing LXD instances between servers
: The most basic kind of migration is if you have a LXD instance on one server and want to move it to a different LXD server.
Migrate existing Incus instances between servers
: The most basic kind of migration is if you have a Incus instance on one server and want to move it to a different Incus server.
For virtual machines, you can do that as a live migration, which means that you can migrate your VM while it is running and there will be no downtime.
See {ref}`move-instances` for more information.
Migrate physical or virtual machines to LXD instances
: If you have an existing machine, either physical or virtual (VM or container), you can use the `lxd-migrate` tool to create a LXD instance based on your existing machine.
The tool copies the provided partition, disk or image to the LXD storage pool of the provided LXD server, sets up an instance using that storage and allows you to configure additional settings for the new instance.
Migrate physical or virtual machines to Incus instances
: If you have an existing machine, either physical or virtual (VM or container), you can use the `lxd-migrate` tool to create a Incus instance based on your existing machine.
The tool copies the provided partition, disk or image to the Incus storage pool of the provided Incus server, sets up an instance using that storage and allows you to configure additional settings for the new instance.
See {ref}`import-machines-to-instances` for more information.
Migrate instances from LXC to LXD
: If you are using LXC and want to migrate all or some of your LXC containers to a LXD installation on the same machine, you can use the `lxc-to-lxd` tool.
The tool analyzes the LXC configuration and copies the data and configuration of your existing LXC containers into new LXD containers.
Migrate instances from LXC to Incus
: If you are using LXC and want to migrate all or some of your LXC containers to a Incus installation on the same machine, you can use the `lxc-to-lxd` tool.
The tool analyzes the LXC configuration and copies the data and configuration of your existing LXC containers into new Incus containers.
See {ref}`migrate-from-lxc` for more information.

4
doc/networks.md
View File

@ -14,8 +14,8 @@ Configure a network </howto/network_configure>
Configure network ACLs </howto/network_acls>
Configure network forwards </howto/network_forwards>
Configure network zones </howto/network_zones>
Configure LXD as BGP server </howto/network_bgp>
Display LXD IPAM information </howto/network_ipam>
Configure Incus as BGP server </howto/network_bgp>
Display Incus IPAM information </howto/network_ipam>
/reference/network_bridge
/reference/network_ovn
/reference/network_external

4
doc/operation.md
View File

@ -1,11 +1,11 @@
(lxd-server)=
# LXD server and client
# Incus server and client
```{toctree}
:maxdepth: 1
/database
Configure the LXD server <howto/server_configure>
Configure the Incus server <howto/server_configure>
Add remote servers <remotes>
Add command aliases <howto/lxc_alias>
/server

2
doc/profiles.md
View File

@ -64,7 +64,7 @@ Check the contents of an existing profile or instance configuration for the requ
For example, the `default` profile might look like this:
config: {}
description: Default LXD profile
description: Default Incus profile
devices:
eth0:
name: eth0

2
doc/reference/devices.md
View File

@ -6,7 +6,7 @@ Devices are attached to an instance (see {ref}`instances-configure-devices`) or
They include, for example, network interfaces, mount points, USB and GPU devices.
These devices can have instance device options, depending on the type of the instance device.
LXD supports the following device types:
Incus supports the following device types:
| ID (database) | Name | Condition | Description |
|:--------------|:---------------------------------------|:----------|:--------------------------------|

6
doc/reference/devices_disk.md
View File

@ -39,14 +39,14 @@ Path on the host
The path is required for file systems, but not for block devices.
Ceph RBD
: LXD can use Ceph to manage an internal file system for the instance, but if you have an existing, externally managed Ceph RBD that you would like to use for an instance, you can add it with the following command:
: Incus can use Ceph to manage an internal file system for the instance, but if you have an existing, externally managed Ceph RBD that you would like to use for an instance, you can add it with the following command:
incus config device add <instance_name> <device_name> disk source=ceph:<pool_name>/<volume_name> ceph.user_name=<user_name> ceph.cluster_name=<cluster_name> [path=<path_in_instance>]
The path is required for file systems, but not for block devices.
CephFS
: LXD can use Ceph to manage an internal file system for the instance, but if you have an existing, externally managed Ceph file system that you would like to use for an instance, you can add it with the following command:
: Incus can use Ceph to manage an internal file system for the instance, but if you have an existing, externally managed Ceph file system that you would like to use for an instance, you can add it with the following command:
incus config device add <instance_name> <device_name> disk source=cephfs:<fs_name>/<path> ceph.user_name=<user_name> ceph.cluster_name=<cluster_name> path=<path_in_instance>
@ -103,7 +103,7 @@ Key | Type | Default | Required | Description
`limits.read` | string | - | no | I/O limit in byte/s (various suffixes supported, see {ref}`instances-limit-units`) or in IOPS (must be suffixed with `iops`) - see also {ref}`storage-configure-IO`
`limits.write` | string | - | no | I/O limit in byte/s (various suffixes supported, see {ref}`instances-limit-units`) or in IOPS (must be suffixed with `iops`) - see also {ref}`storage-configure-IO`
`path` | string | - | yes | Path inside the instance where the disk will be mounted (only for containers)
`pool` | string | - | no | The storage pool to which the disk device belongs (only applicable for storage volumes managed by LXD)
`pool` | string | - | no | The storage pool to which the disk device belongs (only applicable for storage volumes managed by Incus)
`propagation` | string | - | no | Controls how a bind-mount is shared between the instance and the host (can be one of `private`, the default, or `shared`, `slave`, `unbindable`, `rshared`, `rslave`, `runbindable`, `rprivate`; see the Linux Kernel [shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) documentation for a full explanation) <!-- wokeignore:rule=slave -->
`raw.mount.options` | string | - | no | File system specific mount options
`readonly` | bool | `false` | no | Controls whether to make the mount read-only

4
doc/reference/devices_infiniband.md
View File

@ -2,7 +2,7 @@
# Type: `infiniband`
```{youtube} https://www.youtube.com/watch?v=SDewhlRSOuM
:title: LXD InfiniBand devices - YouTube
:title: Incus InfiniBand devices - YouTube
```
```{note}
@ -10,7 +10,7 @@ The `infiniband` device type is supported for both containers and VMs.
It supports hotplugging only for containers, not for VMs.
```
LXD supports two different kinds of network types for InfiniBand devices:
Incus supports two different kinds of network types for InfiniBand devices:
- `physical`: Passes a physical device from the host through to the instance.
The targeted device will vanish from the host and appear in the instance.

32
doc/reference/devices_nic.md
View File

@ -2,7 +2,7 @@
# Type: `nic`
```{youtube} https://www.youtube.com/watch?v=W62eno28KMY
:title: LXD NIC devices
:title: Incus NIC devices
```
```{note}
@ -12,7 +12,7 @@ NICs support hotplugging for both containers and VMs (with the exception of the
```
Network devices, also referred to as *Network Interface Controllers* or *NICs*, supply a connection to a network.
LXD supports several different types of network devices (*NIC types*).
Incus supports several different types of network devices (*NIC types*).
## `nictype` vs. `network`
@ -22,16 +22,16 @@ These two device options are mutually exclusive, and you can specify only one of
However, note that when you specify the `network` option, the `nictype` option is derived automatically from the network type.
`nictype`
: When using the `nictype` device option, you can specify a network interface that is not controlled by LXD.
Therefore, you must specify all information that LXD needs to use the network interface.
: When using the `nictype` device option, you can specify a network interface that is not controlled by Incus.
Therefore, you must specify all information that Incus needs to use the network interface.
When using this method, the `nictype` option must be specified when creating the device, and it cannot be changed later.
`network`
: When using the `network` device option, the NIC is linked to an existing {ref}`managed network <managed-networks>`.
In this case, LXD has all required information about the network, and you need to specify only the network name when adding the device.
In this case, Incus has all required information about the network, and you need to specify only the network name when adding the device.
When using this method, LXD derives the `nictype` option automatically.
When using this method, Incus derives the `nictype` option automatically.
The value is read-only and cannot be changed.
Other device options that are inherited from the network are marked with a "yes" in the "Managed" column of the NIC-specific tables of device options.
@ -110,7 +110,7 @@ You can select this NIC type through the `nictype` option or the `network` optio
A `macvlan` NIC sets up a new network device based on an existing one, but using a different MAC address.
If you are using a `macvlan` NIC, communication between the LXD host and the instances is not possible.
If you are using a `macvlan` NIC, communication between the Incus host and the instances is not possible.
Both the host and the instances can talk to the gateway, but they cannot communicate directly.
#### Device options
@ -146,14 +146,14 @@ Given that VFs appear as regular PCIe devices to the system, they can be passed
VF allocation
: The `sriov` interface type expects to be passed the name of an SR-IOV enabled network device on the system via the `parent` property.
LXD then checks for any available VFs on the system.
Incus then checks for any available VFs on the system.
By default, LXD allocates the first free VF it finds.
By default, Incus allocates the first free VF it finds.
If it detects that either none are enabled or all currently enabled VFs are in use, it bumps the number of supported VFs to the maximum value and uses the first free VF.
If all possible VFs are in use or the kernel or card doesn't support incrementing the number of VFs, LXD returns an error.
If all possible VFs are in use or the kernel or card doesn't support incrementing the number of VFs, Incus returns an error.
```{note}
If you need LXD to use a specific VF, use a `physical` NIC instead of a `sriov` NIC and set its `parent` option to the VF name.
If you need Incus to use a specific VF, use a `physical` NIC instead of a `sriov` NIC and set its `parent` option to the VF name.
```
#### Device options
@ -182,8 +182,8 @@ An `ovn` NIC uses an existing OVN network and creates a virtual device pair to c
(devices-nic-hw-acceleration)=
SR-IOV hardware acceleration
: To use `acceleration=sriov`, you must have a compatible SR-IOV physical NIC that supports the Ethernet switch device driver model (`switchdev`) in your LXD host.
LXD assumes that the physical NIC (PF) is configured in `switchdev` mode and connected to the OVN integration OVS bridge, and that it has one or more virtual functions (VFs) active.
: To use `acceleration=sriov`, you must have a compatible SR-IOV physical NIC that supports the Ethernet switch device driver model (`switchdev`) in your Incus host.
Incus assumes that the physical NIC (PF) is configured in `switchdev` mode and connected to the OVN integration OVS bridge, and that it has one or more virtual functions (VFs) active.
To achieve this, follow these basic prerequisite setup steps:
@ -281,11 +281,11 @@ Key | Type | Default | Managed | Description
An `ipvlan` NIC sets up a new network device based on an existing one, using the same MAC address but a different IP.
If you are using an `ipvlan` NIC, communication between the LXD host and the instances is not possible.
If you are using an `ipvlan` NIC, communication between the Incus host and the instances is not possible.
Both the host and the instances can talk to the gateway, but they cannot communicate directly.
LXD currently supports IPVLAN in L2 and L3S mode.
In this mode, the gateway is automatically set by LXD, but the IP addresses must be manually specified using the `ipv4.address` and/or `ipv6.address` options before the container is started.
Incus currently supports IPVLAN in L2 and L3S mode.
In this mode, the gateway is automatically set by Incus, but the IP addresses must be manually specified using the `ipv4.address` and/or `ipv6.address` options before the container is started.
DNS
: The name servers must be configured inside the container, because they are not set automatically.

4
doc/reference/devices_pci.md
View File

@ -2,7 +2,7 @@
# Type: `pci`
```{youtube} https://www.youtube.com/watch?v=h3DZXbmsZHg
:title: LXD PCI devices
:title: Incus PCI devices
```
```{note}
@ -13,7 +13,7 @@ It does not support hotplugging.
PCI devices are used to pass raw PCI devices from the host into a virtual machine.
They are mainly intended to be used for specialized single-function PCI cards like sound cards or video capture cards.
In theory, you can also use them for more advanced PCI devices like GPUs or network cards, but it's usually more convenient to use the specific device types that LXD provides for these devices ([`gpu` device](devices-gpu) or [`nic` device](devices-nic)).
In theory, you can also use them for more advanced PCI devices like GPUs or network cards, but it's usually more convenient to use the specific device types that Incus provides for these devices ([`gpu` device](devices-gpu) or [`nic` device](devices-nic)).
## Device options

2
doc/reference/devices_proxy.md
View File

@ -66,7 +66,7 @@ You can specify that the connect address should be the IP of the instance by set
```{note}
The listen address can also use wildcard addresses when using non-NAT mode.
However, when using NAT mode, you must specify an IP address on the LXD host.
However, when using NAT mode, you must specify an IP address on the Incus host.
```
## Device options

4
doc/reference/devices_tpm.md
View File

@ -2,7 +2,7 @@
# Type: `tpm`
```{youtube} https://www.youtube.com/watch?v=iE1TN7YIqP0
:title: LXD TPM devices
:title: Incus TPM devices
```
```{note}
@ -14,7 +14,7 @@ TPM devices enable access to a {abbr}`TPM (Trusted Platform Module)` emulator.
TPM devices can be used to validate the boot process and ensure that no steps in the boot chain have been tampered with, and they can securely generate and store encryption keys.
LXD uses a software TPM that supports TPM 2.0.
Incus uses a software TPM that supports TPM 2.0.
For containers, the main use case is sealing certificates, which means that the keys are stored outside of the container, making it virtually impossible for attackers to retrieve them.
For virtual machines, TPM can be used both for sealing certificates and for validating the boot process, which allows using full disk encryption compatible with, for example, Windows BitLocker.

2
doc/reference/devices_unix_block.md
View File

@ -2,7 +2,7 @@
# Type: `unix-block`
```{youtube} https://www.youtube.com/watch?v=C2e3LD5wLI8
:title: LXD Unix devices - YouTube
:title: Incus Unix devices - YouTube
```
```{note}

2
doc/reference/devices_unix_char.md
View File

@ -2,7 +2,7 @@
# Type: `unix-char`
```{youtube} https://www.youtube.com/watch?v=C2e3LD5wLI8
:title: LXD Unix devices - YouTube
:title: Incus Unix devices - YouTube
```
```{note}

2
doc/reference/devices_unix_hotplug.md
View File

@ -2,7 +2,7 @@
# Type: `unix-hotplug`
```{youtube} https://www.youtube.com/watch?v=C2e3LD5wLI8
:title: LXD Unix devices - YouTube
:title: Incus Unix devices - YouTube
```
```{note}

2
doc/reference/devices_usb.md
View File

@ -2,7 +2,7 @@
# Type: `usb`
```{youtube} https://www.youtube.com/watch?v=SAord28VS4g
:title: LXD USB devices
:title: Incus USB devices
```
```{note}

16
doc/reference/image_format.md
View File

@ -28,7 +28,7 @@ For both instance types, the `templates/` directory is optional.
### Metadata
The `metadata.yaml` file contains information that is relevant to running the image in LXD.
The `metadata.yaml` file contains information that is relevant to running the image in Incus.
It includes the following information:
```yaml
@ -99,7 +99,7 @@ The `template` key points to the template file in the `templates/` directory.
You can pass user-defined template properties to the template file through the `properties` key.
Set the `create_only` key if you want LXD to create the file if it doesn't exist, but not overwrite an existing file.
Set the `create_only` key if you want Incus to create the file if it doesn't exist, but not overwrite an existing file.
#### Template files
@ -122,10 +122,10 @@ For convenience, the following functions are exported to the Pongo2 templates:
## Image tarballs
LXD supports two LXD-specific image formats: a unified tarball and split tarballs.
Incus supports two Incus-specific image formats: a unified tarball and split tarballs.
These tarballs can be compressed.
LXD supports a wide variety of compression algorithms for tarballs.
Incus supports a wide variety of compression algorithms for tarballs.
However, for compatibility purposes, you should use `gzip` or `xz`.
(image-format-unified)=
@ -133,8 +133,8 @@ However, for compatibility purposes, you should use `gzip` or `xz`.
A unified tarball is a single tarball (usually `*.tar.xz`) that contains the full content of the image, including the metadata, the root file system and optionally the template files.
This is the format that LXD itself uses internally when publishing images.
It is usually easier to work with; therefore, you should use the unified format when creating LXD-specific images.
This is the format that Incus itself uses internally when publishing images.
It is usually easier to work with; therefore, you should use the unified format when creating Incus-specific images.
The image identifier for such images is the SHA-256 of the tarball.
@ -148,7 +148,7 @@ For containers, the root file system tarball can be SquashFS-formatted.
For virtual machines, the `rootfs.img` file always uses the `qcow2` format.
It can optionally be compressed using `qcow2`'s native compression.
This format is designed to allow for easy image building from existing non-LXD rootfs tarballs that are already available.
You should also use this format if you want to create images that can be consumed by both LXD and other tools.
This format is designed to allow for easy image building from existing non-Incus rootfs tarballs that are already available.
You should also use this format if you want to create images that can be consumed by both Incus and other tools.
The image identifier for such images is the SHA-256 of the concatenation of the metadata and root file system tarball (in that order).

42
doc/reference/instance_options.md
View File

@ -113,25 +113,25 @@ You can specify either which CPUs or how many CPUs are visible and available to
- 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`).
To pin to a single CPU, use the range syntax (for example, `1-1`) to differentiate it from a number of CPUs.
- If you specify a number (for example, `4`) of CPUs, LXD will do dynamic load-balancing of all instances that aren't pinned to specific CPUs, trying to spread the load on the machine.
- If you specify a number (for example, `4`) of CPUs, Incus will do dynamic load-balancing of all instances that aren't pinned to specific CPUs, trying to spread the load on the machine.
Instances are re-balanced every time an instance starts or stops, as well as whenever a CPU is added to the system.
##### CPU limits for virtual machines
```{note}
LXD supports live-updating the `limits.cpu` option.
Incus supports live-updating the `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.
Incus 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 `limits.cpu` is set to a single integer, Incus 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 [`incus info --resources`](incus_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.
In this scenario, Incus 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.
For example, if the pinning configuration includes eight threads, with each pair of thread coming from the same core and an even number of cores spread across two CPUs, the guest will show two CPUs, each with two cores and each core with two threads.
@ -161,13 +161,13 @@ To specify which NUMA nodes to use, set `limits.cpu.nodes` to either a set of NU
(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.
Incus allows to limit the number of huge pages available to a container through the `limits.hugepage.[size]` key.
Architectures often expose multiple huge-page sizes.
The available huge-page sizes depend on the architecture.
Setting limits for huge pages is especially useful when LXD is configured to intercept the `mount` syscall for the `hugetlbfs` file system in unprivileged containers.
When LXD intercepts a `hugetlbfs` `mount` syscall, it mounts the `hugetlbfs` file system for a container with correct `uid` and `gid` values as mount options.
Setting limits for huge pages is especially useful when Incus is configured to intercept the `mount` syscall for the `hugetlbfs` file system in unprivileged containers.
When Incus intercepts a `hugetlbfs` `mount` syscall, it mounts the `hugetlbfs` file system for a container with correct `uid` and `gid` values as mount options.
This makes it possible to use huge pages from unprivileged containers.
However, it is recommended to limit the number of huge pages available to the container through `limits.hugepages.[size]` to stop the container from being able to exhaust the huge pages available to the host.
@ -176,11 +176,11 @@ Limiting huge pages is done through the `hugetlb` cgroup controller, which means
(instance-options-limits-kernel)=
### Kernel resource limits
LXD exposes a generic namespaced key `limits.kernel.*` that can be used to set resource limits for an instance.
Incus exposes a generic namespaced key `limits.kernel.*` that can be used to set resource limits for an instance.
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.
Instead, LXD simply passes down the corresponding resource key after the `limits.kernel.*` prefix and its value to the kernel.
It is generic in the sense that Incus does not perform any validation on the resource that is specified following the `limits.kernel.*` prefix.
Incus cannot know about all the possible resources that a given kernel supports.
Instead, Incus simply passes down the corresponding resource key after the `limits.kernel.*` prefix and its value to the kernel.
The kernel does the appropriate validation.
This allows users to specify any supported limit on their system.
@ -210,12 +210,12 @@ A limit is specified as two colon-separated values that are either numeric or th
A single value can be used as a shortcut to set both soft and hard limit to the same value (for example, `limits.kernel.nofile=3000`).
A resource with no explicitly configured limit will inherit its limit from the process that starts up the instance.
Note that this inheritance is not enforced by LXD but by the kernel.
Note that this inheritance is not enforced by Incus but by the kernel.
(instance-options-migration)=
## Migration options
The following instance options control the behavior if the instance is {ref}`moved from one LXD server to another <move-instances>`:
The following instance options control the behavior if the instance is {ref}`moved from one Incus server to another <move-instances>`:
% Include content from [../config_options.txt](../config_options.txt)
```{include} ../config_options.txt
@ -237,7 +237,7 @@ The following instance options specify the NVIDIA and CUDA configuration of the
(instance-options-raw)=
## Raw instance configuration overrides
The following instance options allow direct interaction with the backend features that LXD itself uses:
The following instance options allow direct interaction with the backend features that Incus itself uses:
% Include content from [../config_options.txt](../config_options.txt)
```{include} ../config_options.txt
@ -246,24 +246,24 @@ The following instance options allow direct interaction with the backend feature
```
```{important}
Setting these `raw.*` keys might break LXD in non-obvious ways.
Setting these `raw.*` keys might break Incus in non-obvious ways.
Therefore, you should avoid setting any of these keys.
```
(instance-options-qemu)=
### Override QEMU configuration
For VM instances, LXD configures QEMU through a configuration file that is passed to QEMU with the `-readconfig` command-line option.
For VM instances, Incus configures QEMU through a configuration file that is passed to QEMU with the `-readconfig` command-line option.
This configuration file is generated for each instance before boot.
It can be found at `/var/log/lxd/<instance_name>/qemu.conf`.
The default configuration works fine for LXD's most common use case: modern UEFI guests with VirtIO devices.
The default configuration works fine for Incus's most common use case: modern UEFI guests with VirtIO devices.
In some situations, however, you might need to override the generated configuration.
For example:
- To run an old guest OS that doesn't support UEFI.
- To specify custom virtual devices when VirtIO is not supported by the guest OS.
- To add devices that are not supported by LXD before the machines boots.
- To add devices that are not supported by Incus before the machines boots.
- To remove devices that conflict with the guest OS.
To override the configuration, set the `raw.qemu.conf` option.
@ -300,7 +300,7 @@ Since it is a multi-line configuration option, you can use it to modify multiple
- To add a new section, specify a section name that is not present in the configuration file.
The configuration file format used by QEMU allows multiple sections with the same name.
Here's a piece of the configuration generated by LXD:
Here's a piece of the configuration generated by Incus:
```
[global]
@ -367,7 +367,7 @@ The following instance options control the creation and expiry of {ref}`instance
(instance-options-volatile)=
## Volatile internal data
The following volatile keys are currently used internally by LXD to store internal data specific to an instance:
The following volatile keys are currently used internally by Incus to store internal data specific to an instance:
% Include content from [../config_options.txt](../config_options.txt)
```{include} ../config_options.txt

10
doc/reference/network_bridge.md
View File

@ -5,17 +5,17 @@ discourse: 7322
(network-bridge)=
# Bridge network
As one of the possible network configuration types under LXD, LXD supports creating and managing network bridges.
As one of the possible network configuration types under Incus, Incus supports creating and managing network bridges.
<!-- Include start bridge intro -->
A network bridge creates a virtual L2 Ethernet switch that instance NICs can connect to, making it possible for them to communicate with each other and the host.
LXD bridges can leverage underlying native Linux bridges and Open vSwitch.
Incus bridges can leverage underlying native Linux bridges and Open vSwitch.
<!-- Include end bridge intro -->
The `bridge` network type allows to create an L2 bridge that connects the instances that use it together into a single network L2 segment.
Bridges created by LXD are managed, which means that in addition to creating the bridge interface itself, LXD also sets up a local `dnsmasq` process to provide DHCP, IPv6 route announcements and DNS services to the network.
Bridges created by Incus are managed, which means that in addition to creating the bridge interface itself, Incus also sets up a local `dnsmasq` process to provide DHCP, IPv6 route announcements and DNS services to the network.
By default, it also performs NAT for the bridge.
See {ref}`network-bridge-firewall` for instructions on how to configure your firewall to work with LXD bridge networks.
See {ref}`network-bridge-firewall` for instructions on how to configure your firewall to work with Incus bridge networks.
<!-- Include start MAC identifier note -->
@ -69,7 +69,7 @@ Key | Type | Condition | Defau
`bridge.hwaddr` | string | - | - | MAC address for the bridge
`bridge.mtu` | integer | - | `1500` | Bridge MTU (default varies if tunnel in use)
`dns.domain` | string | - | `lxd` | Domain to advertise to DHCP clients and use for DNS resolution
`dns.mode` | string | - | `managed` | DNS registration mode: `none` for no DNS record, `managed` for LXD-generated static records or `dynamic` for client-generated records
`dns.mode` | string | - | `managed` | DNS registration mode: `none` for no DNS record, `managed` for Incus-generated static records or `dynamic` for client-generated records
`dns.search` | string | - | - | Full comma-separated domain search list, defaulting to `dns.domain` value
`dns.zone.forward` | string | - | `managed` | Comma-separated list of DNS zone names for forward DNS records
`dns.zone.reverse.ipv4` | string | - | `managed` | DNS zone name for IPv4 reverse DNS records

4
doc/reference/network_external.md
View File

@ -3,12 +3,12 @@
<!-- Include start external intro -->
External networks use network interfaces that already exist.
Therefore, LXD has limited possibility to control them, and LXD features like network ACLs, network forwards and network zones are not supported.
Therefore, Incus has limited possibility to control them, and Incus features like network ACLs, network forwards and network zones are not supported.
The main purpose for using external networks is to provide an uplink network through a parent interface.
This external network specifies the presets to use when connecting instances or other networks to a parent interface.
LXD supports the following external network types:
Incus supports the following external network types:
<!-- Include end external intro -->
```{toctree}

2
doc/reference/network_macvlan.md
View File

@ -10,7 +10,7 @@ The `macvlan` network type allows to specify presets to use when connecting inst
In this case, the instance NICs can simply set the `network` option to the network they connect to without knowing any of the underlying configuration details.
```{note}
If you are using a `macvlan` network, communication between the LXD host and the instances is not possible.
If you are using a `macvlan` network, communication between the Incus host and the instances is not possible.
Both the host and the instances can talk to the gateway, but they cannot communicate directly.
```

2
doc/reference/network_ovn.md
View File

@ -14,7 +14,7 @@ See [`www.ovn.org`](https://www.ovn.org/) for more information.
The `ovn` network type allows to create logical networks using the OVN {abbr}`SDN (software-defined networking)`.
This kind of network can be useful for labs and multi-tenant environments where the same logical subnets are used in multiple discrete networks.
A LXD OVN network can be connected to an existing managed {ref}`network-bridge` or {ref}`network-physical` to gain access to the wider network.
A Incus OVN network can be connected to an existing managed {ref}`network-bridge` or {ref}`network-physical` to gain access to the wider network.
By default, all connections from the OVN logical networks are NATed to an IP allocated from the uplink network.
See {ref}`network-ovn-setup` for basic instructions for setting up an OVN network.

2
doc/reference/provided_metrics.md
View File

@ -1,7 +1,7 @@
(provided-metrics)=
# Provided metrics
LXD provides a number of instance metrics and internal metrics.
Incus provides a number of instance metrics and internal metrics.
See {ref}`metrics` for instructions on how to work with these metrics.
## Instance metrics

12
doc/reference/remote_image_servers.md
View File

@ -29,20 +29,20 @@ The [`lxc`](incus.md) CLI command comes pre-configured with the following defaul
(remote-image-server-types)=
## Remote server types
LXD supports the following types of remote image servers:
Incus supports the following types of remote image servers:
Simple streams servers
: Pure image servers that use the [simple streams format](https://git.launchpad.net/simplestreams/tree/).
The default image servers are simple streams servers.
Public LXD servers
: LXD servers that are used solely to serve images and do not run instances themselves.
Public Incus servers
: Incus servers that are used solely to serve images and do not run instances themselves.
To make a LXD server publicly available over the network on port 8443, set the {config:option}`server-core:core.https_address` configuration option to `:8443` and do not configure any authentication methods (see {ref}`server-expose` for more information).
To make a Incus server publicly available over the network on port 8443, set the {config:option}`server-core:core.https_address` configuration option to `:8443` and do not configure any authentication methods (see {ref}`server-expose` for more information).
Then set the images that you want to share to `public`.
LXD servers
: Regular LXD servers that you can manage over a network, and that can also be used as image servers.
Incus servers
: Regular Incus servers that you can manage over a network, and that can also be used as image servers.
For security reasons, you should restrict the access to the remote API and configure an authentication method to control access.
See {ref}`server-expose` and {ref}`authentication` for more information.

4
doc/reference/server_settings.md
View File

@ -1,7 +1,7 @@
(server-settings)=
# Server settings for a LXD production setup
# Server settings for a Incus production setup
To allow your LXD server to run a large number of instances, configure the following settings to avoid hitting server limits.
To allow your Incus server to run a large number of instances, configure the following settings to avoid hitting server limits.
The `Value` column contains the suggested value for each parameter.

2
doc/reference/standard_devices.md
View File

@ -1,7 +1,7 @@
(standard-devices)=
# Standard devices
LXD provides each instance with the basic devices that are required for a standard POSIX system to work.
Incus provides each instance with the basic devices that are required for a standard POSIX system to work.
These devices aren't visible in the instance or profile configuration, and they may not be overridden.
The standard devices are:

10
doc/reference/storage_btrfs.md
View File

@ -18,18 +18,18 @@ A Btrfs file system can have *subvolumes*, which are named binary subtrees of th
A *Btrfs snapshot* is a special type of subvolume that captures a specific state of another subvolume.
Snapshots can be read-write or read-only.
## `btrfs` driver in LXD
## `btrfs` driver in Incus
The `btrfs` driver in LXD uses a subvolume per instance, image and snapshot.
The `btrfs` driver in Incus uses a subvolume per instance, image and snapshot.
When creating a new entity (for example, launching a new instance), it creates a Btrfs snapshot.
Btrfs doesn't natively support storing block devices.
Therefore, when using Btrfs for VMs, LXD creates a big file on disk to store the VM.
Therefore, when using Btrfs for VMs, Incus creates a big file on disk to store the VM.
This approach is not very efficient and might cause issues when creating snapshots.
Btrfs can be used as a storage backend inside a container in a nested LXD environment.
Btrfs can be used as a storage backend inside a container in a nested Incus environment.
In this case, the parent container itself must use Btrfs.
Note, however, that the nested LXD setup does not inherit the Btrfs quotas from the parent (see {ref}`storage-btrfs-quotas` below).
Note, however, that the nested Incus setup does not inherit the Btrfs quotas from the parent (see {ref}`storage-btrfs-quotas` below).
(storage-btrfs-quotas)=
### Quotas

12
doc/reference/storage_ceph.md
View File

@ -33,7 +33,7 @@ They are also referred to as *data pools*, *storage pools* or *OSD pools*.
Ceph block devices are also called *RBD images*, and you can create *snapshots* and *clones* of these RBD images.
## `ceph` driver in LXD
## `ceph` driver in Incus
```{note}
To use the Ceph RBD driver, you must specify it as `ceph`.
@ -53,15 +53,15 @@ As a result and depending on the internal network, storage access might be a bit
On the other hand, using remote storage has big advantages in a cluster setup, because all cluster members have access to the same storage pools with the exact same contents, without the need to synchronize storage pools.
<!-- Include end Ceph driver remote -->
The `ceph` driver in LXD uses RBD images for images, and snapshots and clones to create instances and snapshots.
The `ceph` driver in Incus uses RBD images for images, and snapshots and clones to create instances and snapshots.
<!-- Include start Ceph driver control -->
LXD assumes that it has full control over the OSD storage pool.
Therefore, you should never maintain any file system entities that are not owned by LXD in a LXD OSD storage pool, because LXD might delete them.
Incus assumes that it has full control over the OSD storage pool.
Therefore, you should never maintain any file system entities that are not owned by Incus in a Incus OSD storage pool, because Incus might delete them.
<!-- Include end Ceph driver control -->
Due to the way copy-on-write works in Ceph RBD, parent RBD images can't be removed until all children are gone.
As a result, LXD automatically renames any objects that are removed but still referenced.
As a result, Incus automatically renames any objects that are removed but still referenced.
Such objects are kept with a `zombie_` prefix until all references are gone and the object can safely be removed.
### Limitations
@ -74,7 +74,7 @@ Sharing custom volumes between instances
If you need to share a custom volume with content type `filesystem`, use the {ref}`CephFS <storage-cephfs>` driver instead.
Sharing the OSD storage pool between installations
: Sharing the same OSD storage pool between multiple LXD installations is not supported.
: Sharing the same OSD storage pool between multiple Incus installations is not supported.
Using an OSD pool of type "erasure"
: To use a Ceph OSD pool of type "erasure", you must create the OSD pool beforehand.

4
doc/reference/storage_cephfs.md
View File

@ -27,7 +27,7 @@ Internally, it maps files to Ceph objects and stores file metadata (for example,
A *CephFS file system* consists of two OSD storage pools, one for the actual data and one for the file metadata.
## `cephfs` driver in LXD
## `cephfs` driver in Incus
```{note}
The `cephfs` driver can only be used for custom storage volumes with content type `filesystem`.
@ -56,7 +56,7 @@ You must create the CephFS file system that you want to use beforehand and speci
:end-before: <!-- Include end Ceph driver control -->
```
The `cephfs` driver in LXD supports snapshots if snapshots are enabled on the server side.
The `cephfs` driver in Incus supports snapshots if snapshots are enabled on the server side.
## Configuration options

6
doc/reference/storage_cephobject.md
View File

@ -25,7 +25,7 @@ It provides object storage functionality with an interface that is compatible wi
A *Ceph Object Gateway* consists of several OSD pools and one or more *Ceph Object Gateway daemon* (`radosgw`) processes that provide object gateway functionality.
## `cephobject` driver in LXD
## `cephobject` driver in Incus
```{note}
The `cephobject` driver can only be used for buckets.
@ -39,12 +39,12 @@ For storage volumes, use the {ref}`Ceph <storage-ceph>` or {ref}`CephFS <storage
:end-before: <!-- Include end Ceph driver cluster -->
```
You must set up a `radosgw` environment beforehand and ensure that its HTTP/HTTPS endpoint URL is reachable from the LXD server or servers.
You must set up a `radosgw` environment beforehand and ensure that its HTTP/HTTPS endpoint URL is reachable from the Incus server or servers.
See [Manual Deployment](https://docs.ceph.com/en/latest/install/manual-deployment/) for information on how to set up a Ceph cluster and [Ceph Object Gateway](https://docs.ceph.com/en/latest/radosgw/) on how to set up a `radosgw` environment.
The `radosgw` URL can be specified at pool creation time using the [`cephobject.radosgw.endpoint`](storage-cephobject-pool-config) option.
LXD uses the `radosgw-admin` command to manage buckets. So this command must be available and operational on the LXD servers.
Incus uses the `radosgw-admin` command to manage buckets. So this command must be available and operational on the Incus servers.
% Include content from [storage_ceph.md](storage_ceph.md)
```{include} storage_ceph.md

6
doc/reference/storage_dir.md
View File

@ -6,11 +6,11 @@
The directory storage driver is a basic backend that stores its data in a standard file and directory structure.
This driver is quick to set up and allows inspecting the files directly on the disk, which can be convenient for testing.
However, LXD operations are {ref}`not optimized <storage-drivers-features>` for this driver.
However, Incus operations are {ref}`not optimized <storage-drivers-features>` for this driver.
## `dir` driver in LXD
## `dir` driver in Incus
The `dir` driver in LXD is fully functional and provides the same set of features as other drivers.
The `dir` driver in Incus is fully functional and provides the same set of features as other drivers.
However, it is much slower than all the other drivers because it must unpack images and do instant copies of instances, snapshots and images.
Unless specified differently during creation (with the `source` configuration option), the data is stored in the `/var/snap/lxd/common/lxd/storage-pools/` (for snap installations) or `/var/lib/lxd/storage-pools/` directory.

Some files were not shown because too many files have changed in this diff Show More