From e93570a369f9e66b48c140d632b934e38d94bb45 Mon Sep 17 00:00:00 2001 From: Kadin Sayani Date: Tue, 12 Nov 2024 16:58:19 -0700 Subject: [PATCH 1/7] lxd/device: Update device option descriptions for `usb` to accurately convey compatibility with containers and vms Signed-off-by: Kadin Sayani --- lxd/device/unix_common.go | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/lxd/device/unix_common.go b/lxd/device/unix_common.go index f763aa89a0dc..fa339abe16b1 100644 --- a/lxd/device/unix_common.go +++ b/lxd/device/unix_common.go @@ -63,6 +63,7 @@ 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) // // --- @@ -70,6 +71,7 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // required: either `source` or `path` must be set // shortdesc: Path inside the instance "path": validate.IsAny, + // lxdmeta:generate(entities=device-unix-{char+block}; group=device-conf; key=major) // // --- @@ -77,6 +79,7 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // defaultdesc: device on host // shortdesc: Device major number "major": unixValidDeviceNum, + // lxdmeta:generate(entities=device-unix-{char+block}; group=device-conf; key=minor) // // --- @@ -84,6 +87,7 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // defaultdesc: device on host // shortdesc: Device minor number "minor": unixValidDeviceNum, + // lxdmeta:generate(entities=device-unix-{char+block+hotplug}; group=device-conf; key=uid) // // --- @@ -97,8 +101,9 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // 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) // // --- @@ -112,8 +117,9 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // 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) // // --- @@ -127,8 +133,9 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // 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. // --- From 79948f6112fb7c6cedaa3767d161059abe47b85b Mon Sep 17 00:00:00 2001 From: Kadin Sayani Date: Wed, 13 Nov 2024 10:32:04 -0700 Subject: [PATCH 2/7] lxd/device: Update container only device options to use word `container` Signed-off-by: Kadin Sayani --- lxd/device/unix_common.go | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/lxd/device/unix_common.go b/lxd/device/unix_common.go index fa339abe16b1..474082633603 100644 --- a/lxd/device/unix_common.go +++ b/lxd/device/unix_common.go @@ -69,7 +69,7 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // --- // 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) @@ -93,7 +93,7 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // --- // 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) // @@ -109,7 +109,7 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // --- // 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) // @@ -125,7 +125,7 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // --- // 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) // @@ -141,14 +141,14 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // --- // 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) // The default is `false`, which means that all devices can be hotplugged. From 405fc81d14b45b8ed5aaeb73e3174d88dcd35f08 Mon Sep 17 00:00:00 2001 From: Kadin Sayani Date: Thu, 14 Nov 2024 08:21:54 -0700 Subject: [PATCH 3/7] lxd/device: Split `required` device option metadata for `usb` and `unix-hotplug` This commit splits the `required` device option into separate metadata descriptions for the `usb` and `unix-hotplug` device, resulting in more accurate descriptions based on device compatibility. Signed-off-by: Kadin Sayani --- lxd/device/unix_common.go | 2 +- lxd/device/unix_hotplug.go | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/lxd/device/unix_common.go b/lxd/device/unix_common.go index 474082633603..b0dc27c5b573 100644 --- a/lxd/device/unix_common.go +++ b/lxd/device/unix_common.go @@ -150,7 +150,7 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { // defaultdesc: `true` // 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 diff --git a/lxd/device/unix_hotplug.go b/lxd/device/unix_hotplug.go index fdd259879028..b86fd70afa95 100644 --- a/lxd/device/unix_hotplug.go +++ b/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) From 32de1aa737f49601ba58efb4582f17b3c9786674 Mon Sep 17 00:00:00 2001 From: Kadin Sayani Date: Thu, 14 Nov 2024 08:27:04 -0700 Subject: [PATCH 4/7] doc: Update `devices_unix_char` docs to accurately convey device compatibility Signed-off-by: Kadin Sayani --- doc/reference/devices_unix_char.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/reference/devices_unix_char.md b/doc/reference/devices_unix_char.md index dfe51f7a9623..cc1b37ea9f43 100644 --- a/doc/reference/devices_unix_char.md +++ b/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 unix-char source= path= -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 unix-char path= From bc85891359fd0bf99991b132ddaaba2d35b1049b Mon Sep 17 00:00:00 2001 From: Kadin Sayani Date: Thu, 14 Nov 2024 08:28:45 -0700 Subject: [PATCH 5/7] doc: Update `devices_unix_block` docs to accurately convey device compatibility Signed-off-by: Kadin Sayani --- doc/reference/devices_unix_block.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/reference/devices_unix_block.md b/doc/reference/devices_unix_block.md index d48401b7e1fc..8909f7211efc 100644 --- a/doc/reference/devices_unix_block.md +++ b/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 unix-block source= path= -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 unix-block path= From c9b5a112c2b308b6477c6768a8f92ea2b34ac923 Mon Sep 17 00:00:00 2001 From: Kadin Sayani Date: Thu, 14 Nov 2024 08:31:28 -0700 Subject: [PATCH 6/7] doc: Update `devices_unix_hotplug` docs to accurately convey device compatibility Signed-off-by: Kadin Sayani --- doc/reference/devices_unix_hotplug.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/reference/devices_unix_hotplug.md b/doc/reference/devices_unix_hotplug.md index 0e56614be038..8421fdf4f1c9 100644 --- a/doc/reference/devices_unix_hotplug.md +++ b/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 unix-hotplug vendorid= productid= From b7d82479af1ec846ac114477ae5f214b8b4a3562 Mon Sep 17 00:00:00 2001 From: Kadin Sayani Date: Fri, 15 Nov 2024 12:21:38 -0700 Subject: [PATCH 7/7] metadata: Run `make update-metadata` Signed-off-by: Kadin Sayani --- doc/metadata.txt | 34 ++++++++++++++++----------------- lxd/metadata/configuration.json | 34 ++++++++++++++++----------------- 2 files changed, 34 insertions(+), 34 deletions(-) diff --git a/doc/metadata.txt b/doc/metadata.txt index 1606cc3d5ed2..8acedae509c2 100644 --- a/doc/metadata.txt +++ b/doc/metadata.txt @@ -1417,7 +1417,7 @@ For example: `/dev/tpmrm0` ```{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: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: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,7 +1588,7 @@ 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" ``` @@ -1596,7 +1596,7 @@ The default is `false`, which means that all devices can be hotplugged. ```{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" ``` diff --git a/lxd/metadata/configuration.json b/lxd/metadata/configuration.json index 70bf348ba562..2c5a5dd1d900 100644 --- a/lxd/metadata/configuration.json +++ b/lxd/metadata/configuration.json @@ -1631,7 +1631,7 @@ "gid": { "defaultdesc": "`0`", "longdesc": "", - "shortdesc": "GID of the device owner in the instance", + "shortdesc": "GID of the device owner in the container", "type": "integer" } }, @@ -1655,7 +1655,7 @@ "mode": { "defaultdesc": "`0660`", "longdesc": "", - "shortdesc": "Mode of the device in the instance", + "shortdesc": "Mode of the device in the container", "type": "integer" } }, @@ -1663,7 +1663,7 @@ "path": { "longdesc": "", "required": "either `source` or `path` must be set", - "shortdesc": "Path inside the instance", + "shortdesc": "Path inside the container", "type": "string" } }, @@ -1671,7 +1671,7 @@ "required": { "defaultdesc": "`true`", "longdesc": "See {ref}`devices-unix-block-hotplugging` for more information.", - "shortdesc": "Whether this device is required to start the instance", + "shortdesc": "Whether this device is required to start the container", "type": "bool" } }, @@ -1687,7 +1687,7 @@ "uid": { "defaultdesc": "`0`", "longdesc": "", - "shortdesc": "UID of the device owner in the instance", + "shortdesc": "UID of the device owner in the container", "type": "integer" } } @@ -1701,7 +1701,7 @@ "gid": { "defaultdesc": "`0`", "longdesc": "", - "shortdesc": "GID of the device owner in the instance", + "shortdesc": "GID of the device owner in the container", "type": "integer" } }, @@ -1725,7 +1725,7 @@ "mode": { "defaultdesc": "`0660`", "longdesc": "", - "shortdesc": "Mode of the device in the instance", + "shortdesc": "Mode of the device in the container", "type": "integer" } }, @@ -1733,7 +1733,7 @@ "path": { "longdesc": "", "required": "either `source` or `path` must be set", - "shortdesc": "Path inside the instance", + "shortdesc": "Path inside the container", "type": "string" } }, @@ -1741,7 +1741,7 @@ "required": { "defaultdesc": "`true`", "longdesc": "See {ref}`devices-unix-char-hotplugging` for more information.", - "shortdesc": "Whether this device is required to start the instance", + "shortdesc": "Whether this device is required to start the container", "type": "bool" } }, @@ -1757,7 +1757,7 @@ "uid": { "defaultdesc": "`0`", "longdesc": "", - "shortdesc": "UID of the device owner in the instance", + "shortdesc": "UID of the device owner in the container", "type": "integer" } } @@ -1771,7 +1771,7 @@ "gid": { "defaultdesc": "`0`", "longdesc": "", - "shortdesc": "GID of the device owner in the instance", + "shortdesc": "GID of the device owner in the container", "type": "integer" } }, @@ -1779,7 +1779,7 @@ "mode": { "defaultdesc": "`0660`", "longdesc": "", - "shortdesc": "Mode of the device in the instance", + "shortdesc": "Mode of the device in the container", "type": "integer" } }, @@ -1794,7 +1794,7 @@ "required": { "defaultdesc": "`false`", "longdesc": "The default is `false`, which means that all devices can be hotplugged.", - "shortdesc": "Whether this device is required to start the instance", + "shortdesc": "Whether this device is required to start the container", "type": "bool" } }, @@ -1802,7 +1802,7 @@ "uid": { "defaultdesc": "`0`", "longdesc": "", - "shortdesc": "UID of the device owner in the instance", + "shortdesc": "UID of the device owner in the container", "type": "integer" } }, @@ -1838,7 +1838,7 @@ "condition": "container", "defaultdesc": "`0`", "longdesc": "", - "shortdesc": "GID of the device owner in the container", + "shortdesc": "GID of the device owner in the instance", "type": "integer" } }, @@ -1847,7 +1847,7 @@ "condition": "container", "defaultdesc": "`0660`", "longdesc": "", - "shortdesc": "Mode of the device in the container", + "shortdesc": "Mode of the device in the instance", "type": "integer" } }, @@ -1878,7 +1878,7 @@ "condition": "container", "defaultdesc": "`0`", "longdesc": "", - "shortdesc": "UID of the device owner in the container", + "shortdesc": "UID of the device owner in the instance", "type": "integer" } },