Update device option descriptions to accurately convey compatibility …

…with containers and VMs (#14454)

Resolves #14451.

doc/metadata.txt

@@ -1417,7 +1417,7 @@ For example: `/dev/tpmrm0`
 <!-- config group device-unix-block-device-conf start -->
 ```{config:option} gid device-unix-block-device-conf
 :defaultdesc: "`0`"
-:shortdesc: "GID of the device owner in the instance"
+:shortdesc: "GID of the device owner in the container"
 :type: "integer"
 
 ```
@@ -1438,21 +1438,21 @@ For example: `/dev/tpmrm0`
 
 ```{config:option} mode device-unix-block-device-conf
 :defaultdesc: "`0660`"
-:shortdesc: "Mode of the device in the instance"
+:shortdesc: "Mode of the device in the container"
 :type: "integer"
 
 ```
 
 ```{config:option} path device-unix-block-device-conf
 :required: "either `source` or `path` must be set"
-:shortdesc: "Path inside the instance"
+:shortdesc: "Path inside the container"
 :type: "string"
 
 ```
 
 ```{config:option} required device-unix-block-device-conf
 :defaultdesc: "`true`"
-:shortdesc: "Whether this device is required to start the instance"
+:shortdesc: "Whether this device is required to start the container"
 :type: "bool"
 See {ref}`devices-unix-block-hotplugging` for more information.
 ```
@@ -1466,7 +1466,7 @@ See {ref}`devices-unix-block-hotplugging` for more information.
 
 ```{config:option} uid device-unix-block-device-conf
 :defaultdesc: "`0`"
-:shortdesc: "UID of the device owner in the instance"
+:shortdesc: "UID of the device owner in the container"
 :type: "integer"
 
 ```
@@ -1475,7 +1475,7 @@ See {ref}`devices-unix-block-hotplugging` for more information.
 <!-- config group device-unix-char-device-conf start -->
 ```{config:option} gid device-unix-char-device-conf
 :defaultdesc: "`0`"
-:shortdesc: "GID of the device owner in the instance"
+:shortdesc: "GID of the device owner in the container"
 :type: "integer"
 
 ```
@@ -1496,21 +1496,21 @@ See {ref}`devices-unix-block-hotplugging` for more information.
 
 ```{config:option} mode device-unix-char-device-conf
 :defaultdesc: "`0660`"
-:shortdesc: "Mode of the device in the instance"
+:shortdesc: "Mode of the device in the container"
 :type: "integer"
 
 ```
 
 ```{config:option} path device-unix-char-device-conf
 :required: "either `source` or `path` must be set"
-:shortdesc: "Path inside the instance"
+:shortdesc: "Path inside the container"
 :type: "string"
 
 ```
 
 ```{config:option} required device-unix-char-device-conf
 :defaultdesc: "`true`"
-:shortdesc: "Whether this device is required to start the instance"
+:shortdesc: "Whether this device is required to start the container"
 :type: "bool"
 See {ref}`devices-unix-char-hotplugging` for more information.
 ```
@@ -1524,7 +1524,7 @@ See {ref}`devices-unix-char-hotplugging` for more information.
 
 ```{config:option} uid device-unix-char-device-conf
 :defaultdesc: "`0`"
-:shortdesc: "UID of the device owner in the instance"
+:shortdesc: "UID of the device owner in the container"
 :type: "integer"
 
 ```
@@ -1533,14 +1533,14 @@ See {ref}`devices-unix-char-hotplugging` for more information.
 <!-- config group device-unix-hotplug-device-conf start -->
 ```{config:option} gid device-unix-hotplug-device-conf
 :defaultdesc: "`0`"
-:shortdesc: "GID of the device owner in the instance"
+:shortdesc: "GID of the device owner in the container"
 :type: "integer"
 
 ```
 
 ```{config:option} mode device-unix-hotplug-device-conf
 :defaultdesc: "`0660`"
-:shortdesc: "Mode of the device in the instance"
+:shortdesc: "Mode of the device in the container"
 :type: "integer"
 
 ```
@@ -1553,14 +1553,14 @@ See {ref}`devices-unix-char-hotplugging` for more information.
 
 ```{config:option} required device-unix-hotplug-device-conf
 :defaultdesc: "`false`"
-:shortdesc: "Whether this device is required to start the instance"
+:shortdesc: "Whether this device is required to start the container"
 :type: "bool"
 The default is `false`, which means that all devices can be hotplugged.
 ```
 
 ```{config:option} uid device-unix-hotplug-device-conf
 :defaultdesc: "`0`"
-:shortdesc: "UID of the device owner in the instance"
+:shortdesc: "UID of the device owner in the container"
 :type: "integer"
 
 ```
@@ -1588,15 +1588,15 @@ The default is `false`, which means that all devices can be hotplugged.
 ```{config:option} gid device-unix-usb-device-conf
 :condition: "container"
 :defaultdesc: "`0`"
-:shortdesc: "GID of the device owner in the container"
+:shortdesc: "GID of the device owner in the instance"
 :type: "integer"
 
 ```
 
 ```{config:option} mode device-unix-usb-device-conf
 :condition: "container"
 :defaultdesc: "`0660`"
-:shortdesc: "Mode of the device in the container"
+:shortdesc: "Mode of the device in the instance"
 :type: "integer"
 
 ```
@@ -1623,7 +1623,7 @@ The default is `false`, which means that all devices can be hotplugged.
 ```{config:option} uid device-unix-usb-device-conf
 :condition: "container"
 :defaultdesc: "`0`"
-:shortdesc: "UID of the device owner in the container"
+:shortdesc: "UID of the device owner in the instance"
 :type: "integer"
 
 ```

doc/reference/devices_unix_block.md

@@ -10,7 +10,7 @@ The `unix-block` device type is supported for containers.
 It supports hotplugging.
 ```
 
-Unix block devices make the specified block device appear as a device in the instance (under `/dev`).
+Unix block devices make the specified block device appear as a device in the container (under `/dev`).
 You can read from the device and write to it.
 
 ## Device options
@@ -25,11 +25,11 @@ You can read from the device and write to it.
 
 ## Configuration examples
 
-Add a `unix-block` device to an instance by specifying its source and path:
+Add a `unix-block` device to a container by specifying its source and path:
 
     lxc config device add <instance_name> <device_name> unix-block source=<path_on_host> path=<path_on_instance>
 
-If you want to use the same path on the instance as on the host, you can omit the `source` option:
+If you want to use the same path on the container as on the host, you can omit the `source` option:
 
     lxc config device add <instance_name> <device_name> unix-block path=<path_to_the_device>
 

doc/reference/devices_unix_char.md

@@ -10,7 +10,7 @@ The `unix-char` device type is supported for containers.
 It supports hotplugging.
 ```
 
-Unix character devices make the specified character device appear as a device in the instance (under `/dev`).
+Unix character devices make the specified character device appear as a device in the container (under `/dev`).
 You can read from the device and write to it.
 
 ## Device options
@@ -25,11 +25,11 @@ You can read from the device and write to it.
 
 ## Configuration examples
 
-Add a `unix-char` device to an instance by specifying its source and path:
+Add a `unix-char` device to a container by specifying its source and path:
 
     lxc config device add <instance_name> <device_name> unix-char source=<path_on_host> path=<path_on_instance>
 
-If you want to use the same path on the instance as on the host, you can omit the `source` option:
+If you want to use the same path on the container as on the host, you can omit the `source` option:
 
     lxc config device add <instance_name> <device_name> unix-char path=<path_to_the_device>
 

doc/reference/devices_unix_hotplug.md

@@ -10,7 +10,7 @@ The `unix-hotplug` device type is supported for containers.
 It supports hotplugging.
 ```
 
-Unix hotplug devices make the requested Unix device appear as a device in the instance (under `/dev`).
+Unix hotplug devices make the requested Unix device appear as a device in the container (under `/dev`).
 If the device exists on the host system, you can read from it and write to it.
 
 The implementation depends on `systemd-udev` to be run on the host.
@@ -27,7 +27,7 @@ The implementation depends on `systemd-udev` to be run on the host.
 
 ## Configuration examples
 
-Add a `unix-hotplug` device to an instance by specifying its vendor ID and product ID:
+Add a `unix-hotplug` device to a container by specifying its vendor ID and product ID:
 
     lxc config device add <instance_name> <device_name> unix-hotplug vendorid=<vendor_ID> productid=<product_ID>
 

lxd/device/unix_common.go

@@ -63,87 +63,94 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error {
 
 			return &drivers.ErrInvalidPath{PrefixPath: d.state.DevMonitor.PrefixPath()}
 		},
+
 		// lxdmeta:generate(entities=device-unix-{char+block}; group=device-conf; key=path)
 		//
 		// ---
 		//  type: string
 		//  required: either `source` or `path` must be set
-		//  shortdesc: Path inside the instance
+		//  shortdesc: Path inside the container
 		"path": validate.IsAny,
+
 		// lxdmeta:generate(entities=device-unix-{char+block}; group=device-conf; key=major)
 		//
 		// ---
 		//  type: integer
 		//  defaultdesc: device on host
 		//  shortdesc: Device major number
 		"major": unixValidDeviceNum,
+
 		// lxdmeta:generate(entities=device-unix-{char+block}; group=device-conf; key=minor)
 		//
 		// ---
 		//  type: integer
 		//  defaultdesc: device on host
 		//  shortdesc: Device minor number
 		"minor": unixValidDeviceNum,
+
 		// lxdmeta:generate(entities=device-unix-{char+block+hotplug}; group=device-conf; key=uid)
 		//
 		// ---
 		//  type: integer
 		//  defaultdesc: `0`
-		//  shortdesc: UID of the device owner in the instance
+		//  shortdesc: UID of the device owner in the container
 
 		// lxdmeta:generate(entities=device-unix-usb; group=device-conf; key=uid)
 		//
 		// ---
 		//  type: integer
 		//  defaultdesc: `0`
 		//  condition: container
-		//  shortdesc: UID of the device owner in the container
+		//  shortdesc: UID of the device owner in the instance
 		"uid": unixValidUserID,
+
 		// lxdmeta:generate(entities=device-unix-{char+block+hotplug}; group=device-conf; key=gid)
 		//
 		// ---
 		//  type: integer
 		//  defaultdesc: `0`
-		//  shortdesc: GID of the device owner in the instance
+		//  shortdesc: GID of the device owner in the container
 
 		// lxdmeta:generate(entities=device-unix-usb; group=device-conf; key=gid)
 		//
 		// ---
 		//  type: integer
 		//  defaultdesc: `0`
 		//  condition: container
-		//  shortdesc: GID of the device owner in the container
+		//  shortdesc: GID of the device owner in the instance
 		"gid": unixValidUserID,
+
 		// lxdmeta:generate(entities=device-unix-{char+block+hotplug}; group=device-conf; key=mode)
 		//
 		// ---
 		//  type: integer
 		//  defaultdesc: `0660`
-		//  shortdesc: Mode of the device in the instance
+		//  shortdesc: Mode of the device in the container
 
 		// lxdmeta:generate(entities=device-unix-usb; group=device-conf; key=mode)
 		//
 		// ---
 		//  type: integer
 		//  defaultdesc: `0660`
 		//  condition: container
-		//  shortdesc: Mode of the device in the container
+		//  shortdesc: Mode of the device in the instance
 		"mode": unixValidOctalFileMode,
+
 		// lxdmeta:generate(entities=device-unix-char; group=device-conf; key=required)
 		// See {ref}`devices-unix-char-hotplugging` for more information.
 		// ---
 		//  type: bool
 		//  defaultdesc: `true`
-		//  shortdesc: Whether this device is required to start the instance
+		//  shortdesc: Whether this device is required to start the container
 
 		// lxdmeta:generate(entities=device-unix-block; group=device-conf; key=required)
 		// See {ref}`devices-unix-block-hotplugging` for more information.
 		// ---
 		//  type: bool
 		//  defaultdesc: `true`
-		//  shortdesc: Whether this device is required to start the instance
+		//  shortdesc: Whether this device is required to start the container
 
-		// lxdmeta:generate(entities=device-unix-{hotplug+usb}; group=device-conf; key=required)
+		// lxdmeta:generate(entities=device-unix-usb; group=device-conf; key=required)
 		// The default is `false`, which means that all devices can be hotplugged.
 		// ---
 		//  type: bool

lxd/device/unix_hotplug.go

@@ -72,7 +72,14 @@ func (d *unixHotplug) validateConfig(instConf instance.ConfigReader) error {
 		"uid":       unixValidUserID,
 		"gid":       unixValidUserID,
 		"mode":      unixValidOctalFileMode,
-		"required":  validate.Optional(validate.IsBool),
+
+		// lxdmeta:generate(entities=device-unix-hotplug; group=device-conf; key=required)
+		// The default is `false`, which means that all devices can be hotplugged.
+		// ---
+		//  type: bool
+		//  defaultdesc: `false`
+		//  shortdesc: Whether this device is required to start the container
+		"required": validate.Optional(validate.IsBool),
 	}
 
 	err := d.config.Validate(rules)