diff --git a/doc/config_options.txt b/doc/config_options.txt index 53c2da43b51..43e2d21c7de 100644 --- a/doc/config_options.txt +++ b/doc/config_options.txt @@ -16,6 +16,104 @@ User keys can be used in search. ``` + +```{config:option} gid devices-unix-char-block +:default: "0" +:shortdesc: "GID of the device owner in the instance" +:type: "int" + +``` + +```{config:option} major devices-unix-char-block +:default: "device on host" +:shortdesc: "Device major number" +:type: "int" + +``` + +```{config:option} minor devices-unix-char-block +:default: "device on host" +:shortdesc: "Device minor number" +:type: "int" + +``` + +```{config:option} mode devices-unix-char-block +:default: "0660" +:shortdesc: "Mode of the device in the instance" +:type: "int" + +``` + +```{config:option} path devices-unix-char-block +:shortdesc: "Path inside the instance (one of `source` and `path` must be set)" +:type: "string" + +``` + +```{config:option} required devices-unix-char-block +:default: "true" +:shortdesc: "Whether this device is required to start the instance" +:type: "bool" + +``` + +```{config:option} source devices-unix-char-block +:shortdesc: "Path on the host (one of `source` and `path` must be set)" +:type: "string" + +``` + +```{config:option} uid devices-unix-char-block +:default: "0" +:shortdesc: "UID of the device owner in the instance" +:type: "int" + +``` + + + +```{config:option} gid devices-unix-hotplug +:default: "0" +:shortdesc: "GID of the device owner in the instance" +:type: "int" + +``` + +```{config:option} mode devices-unix-hotplug +:default: "0660" +:shortdesc: "Mode of the device in the instance" +:type: "int" + +``` + +```{config:option} productid devices-unix-hotplug +:shortdesc: "The product ID of the USB device" +:type: "string" + +``` + +```{config:option} required devices-unix-hotplug +:default: "true" +:shortdesc: "Whether this device is required to start the instance" +:type: "bool" + +``` + +```{config:option} uid devices-unix-hotplug +:default: "0" +:shortdesc: "UID of the device owner in the instance" +:type: "int" + +``` + +```{config:option} vendorid devices-unix-hotplug +:shortdesc: "The vendor ID of the USB device" +:type: "string" + +``` + + ```{config:option} busnum devices-usb :shortdesc: "The bus number of which the USB device is attached" diff --git a/doc/reference/devices_unix_block.md b/doc/reference/devices_unix_block.md index 9992996811d..747986f876e 100644 --- a/doc/reference/devices_unix_block.md +++ b/doc/reference/devices_unix_block.md @@ -13,16 +13,11 @@ You can read from the device and write to it. `unix-block` devices have the following device options: -Key | Type | Default | Description -:-- | :-- | :-- | :-- -`gid` | int | `0` | GID of the device owner in the instance -`major` | int | device on host | Device major number -`minor` | int | device on host | Device minor number -`mode` | int | `0660` | Mode of the device in the instance -`path` | string | - | Path inside the instance (one of `source` and `path` must be set) -`required` | bool | `true` | Whether this device is required to start the instance (see {ref}`devices-unix-block-hotplugging`) -`source` | string | - | Path on the host (one of `source` and `path` must be set) -`uid` | int | `0` | UID of the device owner in the instance +% Include content from [../config_options.txt](../config_options.txt) +```{include} ../config_options.txt + :start-after: + :end-before: +``` (devices-unix-block-hotplugging)= ## Hotplugging diff --git a/doc/reference/devices_unix_char.md b/doc/reference/devices_unix_char.md index e5d35f439ef..be5a9c7f535 100644 --- a/doc/reference/devices_unix_char.md +++ b/doc/reference/devices_unix_char.md @@ -13,16 +13,11 @@ You can read from the device and write to it. `unix-char` devices have the following device options: -Key | Type | Default | Description -:-- | :-- | :-- | :-- -`gid` | int | `0` | GID of the device owner in the instance -`major` | int | device on host | Device major number -`minor` | int | device on host | Device minor number -`mode` | int | `0660` | Mode of the device in the instance -`path` | string | - | Path inside the instance (one of `source` and `path` must be set) -`required` | bool | `true` | Whether this device is required to start the instance (see {ref}`devices-unix-char-hotplugging`) -`source` | string | - | Path on the host (one of `source` and `path` must be set) -`uid` | int | `0` | UID of the device owner in the instance +% Include content from [../config_options.txt](../config_options.txt) +```{include} ../config_options.txt + :start-after: + :end-before: +``` (devices-unix-char-hotplugging)= ## Hotplugging diff --git a/doc/reference/devices_unix_hotplug.md b/doc/reference/devices_unix_hotplug.md index c5241971a6e..4606fc11c23 100644 --- a/doc/reference/devices_unix_hotplug.md +++ b/doc/reference/devices_unix_hotplug.md @@ -15,11 +15,8 @@ The implementation depends on `systemd-udev` to be run on the host. `unix-hotplug` devices have the following device options: -Key | Type | Default | Description -:-- | :-- | :-- | :-- -`gid` | int | `0` | GID of the device owner in the instance -`mode` | int | `0660` | Mode of the device in the instance -`productid` | string | - | The product ID of the Unix device -`required` | bool | `false` | Whether this device is required to start the instance (the default is `false`, and all devices can be hotplugged) -`uid` | int | `0` | UID of the device owner in the instance -`vendorid` | string | - | The vendor ID of the Unix device +% Include content from [../config_options.txt](../config_options.txt) +```{include} ../config_options.txt + :start-after: + :end-before: +``` diff --git a/internal/server/device/unix_common.go b/internal/server/device/unix_common.go index 7b9450a8188..cca43ac5288 100644 --- a/internal/server/device/unix_common.go +++ b/internal/server/device/unix_common.go @@ -45,6 +45,11 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { } rules := map[string]func(string) error{ + // gendoc:generate(entity=devices, group=unix-char-block, key=source) + // + // --- + // type: string + // shortdesc: Path on the host (one of `source` and `path` must be set) "source": func(value string) error { if value == "" { return nil @@ -56,13 +61,61 @@ func (d *unixCommon) validateConfig(instConf instance.ConfigReader) error { return &drivers.ErrInvalidPath{PrefixPath: d.state.DevMonitor.PrefixPath()} }, - "path": validate.IsAny, - "major": unixValidDeviceNum, - "minor": unixValidDeviceNum, - "uid": unixValidUserID, - "gid": unixValidUserID, - "mode": unixValidOctalFileMode, + + // gendoc:generate(entity=devices, group=unix-char-block, key=gid) + // + // --- + // type: int + // default: 0 + // shortdesc: GID of the device owner in the instance + "gid": unixValidUserID, + + // gendoc:generate(entity=devices, group=unix-char-block, key=major) + // + // --- + // type: int + // default: device on host + // shortdesc: Device major number + "major": unixValidDeviceNum, + + // gendoc:generate(entity=devices, group=unix-char-block, key=minor) + // + // --- + // type: int + // default: device on host + // shortdesc: Device minor number + "minor": unixValidDeviceNum, + + // gendoc:generate(entity=devices, group=unix-char-block, key=mode) + // + // --- + // type: int + // default: 0660 + // shortdesc: Mode of the device in the instance + "mode": unixValidOctalFileMode, + + // gendoc:generate(entity=devices, group=unix-char-block, key=path) + // + // --- + // type: string + // shortdesc: Path inside the instance (one of `source` and `path` must be set) + "path": validate.IsAny, + + // gendoc:generate(entity=devices, group=unix-char-block, key=required) + // + // --- + // type: bool + // default: true + // shortdesc: Whether this device is required to start the instance "required": validate.Optional(validate.IsBool), + + // gendoc:generate(entity=devices, group=unix-char-block, key=uid) + // + // --- + // type: int + // default: 0 + // shortdesc: UID of the device owner in the instance + "uid": unixValidUserID, } err := d.config.Validate(rules) diff --git a/internal/server/device/unix_hotplug.go b/internal/server/device/unix_hotplug.go index b38be51e48d..ab45f585847 100644 --- a/internal/server/device/unix_hotplug.go +++ b/internal/server/device/unix_hotplug.go @@ -45,11 +45,50 @@ func (d *unixHotplug) validateConfig(instConf instance.ConfigReader) error { } rules := map[string]func(string) error{ + // gendoc:generate(entity=devices, group=unix-hotplug, key=vendorid) + // + // --- + // type: string + // shortdesc: The vendor ID of the USB device "vendorid": validate.Optional(validate.IsDeviceID), + + // gendoc:generate(entity=devices, group=unix-hotplug, key=productid) + // + // --- + // type: string + // shortdesc: The product ID of the USB device "productid": validate.Optional(validate.IsDeviceID), + + // gendoc:generate(entity=devices, group=unix-hotplug, key=uid) + // + // --- + // type: int + // default: 0 + // shortdesc: UID of the device owner in the instance "uid": unixValidUserID, + + // gendoc:generate(entity=devices, group=unix-hotplug, key=gid) + // + // --- + // type: int + // default: 0 + // shortdesc: GID of the device owner in the instance "gid": unixValidUserID, + + // gendoc:generate(entity=devices, group=unix-hotplug, key=mode) + // + // --- + // type: int + // default: 0660 + // shortdesc: Mode of the device in the instance "mode": unixValidOctalFileMode, + + // gendoc:generate(entity=devices, group=unix-hotplug, key=required) + // + // --- + // type: bool + // default: true + // shortdesc: Whether this device is required to start the instance "required": validate.Optional(validate.IsBool), } diff --git a/internal/server/metadata/configuration.json b/internal/server/metadata/configuration.json index 47e5005722d..d849140ef25 100644 --- a/internal/server/metadata/configuration.json +++ b/internal/server/metadata/configuration.json @@ -22,6 +22,122 @@ } }, "devices": { + "unix-char-block": { + "keys": [ + { + "gid": { + "default": "0", + "longdesc": "", + "shortdesc": "GID of the device owner in the instance", + "type": "int" + } + }, + { + "major": { + "default": "device on host", + "longdesc": "", + "shortdesc": "Device major number", + "type": "int" + } + }, + { + "minor": { + "default": "device on host", + "longdesc": "", + "shortdesc": "Device minor number", + "type": "int" + } + }, + { + "mode": { + "default": "0660", + "longdesc": "", + "shortdesc": "Mode of the device in the instance", + "type": "int" + } + }, + { + "path": { + "longdesc": "", + "shortdesc": "Path inside the instance (one of `source` and `path` must be set)", + "type": "string" + } + }, + { + "required": { + "default": "true", + "longdesc": "", + "shortdesc": "Whether this device is required to start the instance", + "type": "bool" + } + }, + { + "source": { + "longdesc": "", + "shortdesc": "Path on the host (one of `source` and `path` must be set)", + "type": "string" + } + }, + { + "uid": { + "default": "0", + "longdesc": "", + "shortdesc": "UID of the device owner in the instance", + "type": "int" + } + } + ] + }, + "unix-hotplug": { + "keys": [ + { + "gid": { + "default": "0", + "longdesc": "", + "shortdesc": "GID of the device owner in the instance", + "type": "int" + } + }, + { + "mode": { + "default": "0660", + "longdesc": "", + "shortdesc": "Mode of the device in the instance", + "type": "int" + } + }, + { + "productid": { + "longdesc": "", + "shortdesc": "The product ID of the USB device", + "type": "string" + } + }, + { + "required": { + "default": "true", + "longdesc": "", + "shortdesc": "Whether this device is required to start the instance", + "type": "bool" + } + }, + { + "uid": { + "default": "0", + "longdesc": "", + "shortdesc": "UID of the device owner in the instance", + "type": "int" + } + }, + { + "vendorid": { + "longdesc": "", + "shortdesc": "The vendor ID of the USB device", + "type": "string" + } + } + ] + }, "usb": { "keys": [ {