doc/security: include info on privileged/unprivileged containers

README.md

@@ -52,9 +52,11 @@ Consider the following aspects to ensure that your LXD installation is secure:
 - Keep your operating system up-to-date and install all available security patches.
 - Use only supported LXD versions (LTS releases or monthly feature releases).
 - Restrict access to the LXD daemon and the remote API.
-- Do not use privileged containers unless required. If you use privileged containers, put appropriate security measures in place. See the [LXD security page](https://documentation.ubuntu.com/lxd/en/latest/explanation/security/) for more information.
 - Configure your network interfaces to be secure.
-<!-- Include end security -->
+- Do not use privileged containers unless required. If you use privileged containers, put appropriate security measures in place.
+  <!-- Include end security -->
+  See [Container security](https://documentation.ubuntu.com/lxd/en/latest/explanation/security/#container-security) for more information.
+
 
 See [Security](https://documentation.ubuntu.com/lxd/en/latest/explanation/security/) for detailed information.
 

doc/config_options.txt

@@ -549,7 +549,7 @@ If specified, the idmap used for this instance is unique among instances that ha
 :liveupdate: "no"
 :shortdesc: "Whether to run the instance in privileged mode"
 :type: "bool"
-
+See {ref}`container-security` for more information.
 ```
 
 ```{config:option} security.protection.delete instance-security

doc/explanation/security.md

@@ -1,3 +1,7 @@
+---
+relatedlinks: https://linuxcontainers.org/lxc/security/
+---
+
 (exp-security)=
 (security)=
 # About security
@@ -66,15 +70,34 @@ In addition, you should set firewall rules to allow access to the LXD port only
 
 LXD containers can use a wide range of features for security.
 
+Also see the [LXC security page](https://linuxcontainers.org/lxc/security/) on `linuxcontainers.org` for details on LXC container security and the applied kernel features.
+
+### Unprivileged containers
+
 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.
 
+Unprivileged containers are safe by design: The container UID 0 is mapped to an unprivileged user outside of the container.
+It has extra rights only on resources that it owns itself.
+
+This mechanism ensures that most security issues (for example, container escape or resource abuse) that might occur in a container apply just as well to a random unprivileged user, which means they are a generic kernel security bug rather than a LXD issue.
+
+```{tip}
 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.
+```
+
+### Privileged containers
 
 LXD 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.
+In privileged containers, the container UID 0 is mapped to the host's UID 0.
+
+Such privileged containers are not 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.
+
+LXC applies some protection measures to privileged containers to prevent accidental damage of the host (where damage is defined as things like reconfiguring host hardware, reconfiguring the host kernel, or accessing the host file system).
+This protection of the host and prevention of escape is achieved through mandatory access control (`apparmor`, `selinux`), Seccomp filters, dropping of capabilities, and namespaces.
+These measures are valuable when running trusted workloads, but they do not make privileged containers root-safe.
 
-More details on container security and the kernel features we use can be found on the
-[LXC security page](https://linuxcontainers.org/lxc/security/).
+Therefore, you should not use privileged containers unless required.
+If you use them, make sure to put appropriate security measures in place.
 
 ### Container name leakage
 

lxd/metadata/configuration.json

@@ -571,7 +571,7 @@
 							"condition": "container",
 							"defaultdesc": "`false`",
 							"liveupdate": "no",
-							"longdesc": "",
+							"longdesc": "See {ref}`container-security` for more information.",
 							"shortdesc": "Whether to run the instance in privileged mode",
 							"type": "bool"
 						}

shared/instance.go

@@ -718,7 +718,7 @@ var InstanceConfigKeysContainer = map[string]func(value string) error{
 	"security.nesting": validate.Optional(validate.IsBool),
 
 	// lxdmeta:generate(entity=instance, group=security, key=security.privileged)
-	//
+	// See {ref}`container-security` for more information.
 	// ---
 	//  type: bool
 	//  defaultdesc: `false`