USB 透传

介绍如何把宿主机的 USB 设备透传给虚拟机使用。

支持版本:>=3.8

目前只有内置私有云平台的虚拟机可以使用宿主机上的 USB 设备。前提条件是宿主机需要有 lsusb 这个工具,如果没有请安装 usbutils 这个包。

配置宿主机

查看宿主机上的 USB 设备,命令如下:

$ lsusb
Bus 002 Device 002: ID 0951:1666 Kingston Technology DataTraveler 100 G3/G4/SE9 G2/50
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 0627:0001 Adomax Technology Co., Ltd
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

默认情况下宿主机透传 USB 设备功能是禁用的,需要在 /etc/yunion/host.conf 配置文件里面设置 disable_usb: false

$ vim /etc/yunion/host.conf
...
disable_usb: false
...

假设宿主机 hostname 为 oc-node-1,然后重启宿主机服务,登录到控制节点,执行下面的命令:

# 先找到对应的宿主机服务
$ kubectl get pods -n onecloud -o wide | grep host | grep oc-node-1 | egrep -v 'deployer|image'
default-host-59k76                                  3/3     Running   7          3d22h   192.168.121.21   oc-node-1   <none>           <none>

# 删除宿主机上的 pod ,等待重建
$ kubectl delete pods -n onecloud default-host-59k76
pod "default-host-59k76" deleted

# 查看新创建的 host 服务
$ kubectl get pods -n onecloud -o wide | grep host | grep oc-node-1 | egrep -v 'deployer|image'
default-host-6cl8w                                  3/3     Running   0          17s     192.168.121.21   oc-node-1   <none>           <none>
# 确保该服务变成 Running ,然后到云平台查看透传 USB 设备

如果宿主机很多,也可以使用 kubectl -n rollout restart daemonset default-host 命令来重启所有宿主机上的 host 服务。

查看 USB 透传设备

climc 命令行查看透传设备

使用命令行 climc isolated-device-list --details 查看设备:

$ climc isolated-device-list --details
+--------------------------------------+----------+------------------------------------------------------+---------+------------------+--------------------------------------+--------------------------+----------+-------+--------------+
|                  ID                  | Dev_type |                        Model                         |  Addr   | Vendor_device_id |               Host_id                |           Host           | Guest_id | Guest | Guest_status |
+--------------------------------------+----------+------------------------------------------------------+---------+------------------+--------------------------------------+--------------------------+----------+-------+--------------+
| 1541047f-0203-488a-8226-2de740da061f | USB      | Adomax Technology Co., Ltd                           | 001:002 | 0627:0001        | 7a11731f-dcc0-41e5-8d64-68eb36defcbe | oc-node-1-192-168-121-21 |          |       |              |
| a3fa9bd4-236c-4c5b-8056-f7afa807138d | USB      | Kingston Technology DataTraveler 100 G3/G4/SE9 G2/50 | 002:002 | 0951:1666        | 7a11731f-dcc0-41e5-8d64-68eb36defcbe | oc-node-1-192-168-121-21 |          |       |              |
+--------------------------------------+----------+------------------------------------------------------+---------+------------------+--------------------------------------+--------------------------+----------+-------+--------------+
***  Total: 2 Pages: 1 Limit: 20 Offset: 0 Page: 1  ***

web界面查看透传设备

  1. 在透传设备页面,可以查看到宿主机上的USB透传设备。

现在云平台就有了宿主机 oc-node-1 上的 USB 透传设备,接下来就可以把这些设备给虚拟机使用。

虚拟机挂载 USB

USB 可以在虚拟机运行状态下挂载进去,可以在前端的透传设备列表那里把 USB 挂载到虚拟机里面,一个虚拟机可关联多个USB透传设备。但是一个USB透传设备仅可被一个虚拟机使用。

web界面挂载USB

在虚拟机页面挂载USB透传设备

  1. 在左侧导航栏,选择 “主机/主机/虚拟机” 菜单项,进入虚拟机页面。
  2. 单击虚拟机右侧操作列 “更多” 按钮,选择下拉菜单 “实例设置-设置USB透传” 菜单项,弹出设置USB透传对话框。
  3. 配置以下参数:
    • 是否绑定:选择绑定USB透传设备。
    • USB设备:当启用绑定USB透传设备后,显示该项,并选择具体的透传设备。
    • 自动启动:挂载USB设备成功后虚拟机是否自动启动,仅虚拟机关机状态下生效。
  4. 单击 “确定” 按钮,挂载或取消挂载USB透传设备。

在透传设备页面关联虚拟机

  1. 在透传设备页面,单击USB类型透传设备右侧操作列 “关联虚拟机” 按钮,弹出关联虚拟机对话框。
  2. 配置以下参数:
    • 选择虚拟机:选择需要关联透传设备的虚拟机。
    • 自动启动:挂载USB设备成功后虚拟机是否自动启动,仅虚拟机关机状态下生效。
  3. 单击 “确定” 按钮,为USB透传设备关联虚拟机。

Climc命令行挂载USB设备

对应命令行操作如下 climc server-attach-isolated-device $server_id $device_id

# 比如虚拟机名称为 testvm,透传设备 id 为 a3fa9bd4-236c-4c5b-8056-f7afa807138d
$ climc server-attach-isolated-device testvm a3fa9bd4-236c-4c5b-8056-f7afa807138d

# 然后登录到 testvm 虚拟机里面,执行 lsusb 就能看到宿主机的 USB 设备
[root@testvm ~]# lsusb
Bus 002 Device 002: ID 0951:1666 Kingston Technology DataTraveler 100 G3/G4/SE9 G2/50

虚拟机卸载 USB

USB 可以在虚拟机运行状态下卸载 USB ,可以在前端的透传设备列表那里卸载 USB 对应的虚拟机。

web界面卸载USB

在虚拟机页面卸载USB透传设备

  1. 在左侧导航栏,选择 “主机/主机/虚拟机” 菜单项,进入虚拟机页面。
  2. 单击虚拟机右侧操作列 “更多” 按钮,选择下拉菜单 “实例设置-设置USB透传” 菜单项,弹出设置USB透传对话框。
  3. 配置以下参数:
    • 是否绑定:关闭绑定USB透传设备。
    • 自动启动:挂载USB设备成功后虚拟机是否自动启动,仅虚拟机关机状态下生效。
  4. 单击 “确定” 按钮,挂载或取消挂载USB透传设备。

在透传设备页面取消关联虚拟机

  1. 在透传设备页面,单击USB类型透传设备右侧操作列 “取消关联虚拟机” 按钮,弹出关联虚拟机对话框。
  2. 配置以下参数:
    • 自动启动:卸载USB设备成功后虚拟机是否自动启动,仅虚拟机关机状态下生效。
  3. 单击 “确定” 按钮,USB透传设备取消关联虚拟机。

Climc命令卸载USB

对应命令行操作如下 climc server-detach-isolated-device $server_id $device_id

# 比如虚拟机名称为 testvm,透传设备 id 为 a3fa9bd4-236c-4c5b-8056-f7afa807138d
$ climc server-detach-isolated-device testvm a3fa9bd4-236c-4c5b-8056-f7afa807138d

宿主机刷新设备

有些情况会频繁在宿主机上插拔 USB 设备,这样会导致云平台记录的 USB 设备信息和宿主机上的实际设备信息不一致,可以使用下面的命令 climc host-probe-isolated-devices $host_id 进行设备信息同步:

# 假设宿主机名称为 oc-node-1-192-168-121-21,看下目前的设备列表
$ lsusb
Bus 002 Device 002: ID 0951:1666 Kingston Technology DataTraveler 100 G3/G4/SE9 G2/50
Bus 001 Device 002: ID 0627:0001 Adomax Technology Co., Ltd

# 对应云平台的设备列表是一致的
$ climc isolated-device-list  --host oc-node-1-192-168-121-21
+--------------------------------------+----------+------------------------------------------------------+---------+------------------+--------------------------------------+
|                  ID                  | Dev_type |                        Model                         |  Addr   | Vendor_device_id |               Host_id                |
+--------------------------------------+----------+------------------------------------------------------+---------+------------------+--------------------------------------+
| 1541047f-0203-488a-8226-2de740da061f | USB      | Adomax Technology Co., Ltd                           | 001:002 | 0627:0001        | 7a11731f-dcc0-41e5-8d64-68eb36defcbe |
| a3fa9bd4-236c-4c5b-8056-f7afa807138d | USB      | Kingston Technology DataTraveler 100 G3/G4/SE9 G2/50 | 002:002 | 0951:1666        | 7a11731f-dcc0-41e5-8d64-68eb36defcbe |
+--------------------------------------+----------+------------------------------------------------------+---------+------------------+--------------------------------------+
***  Total: 2 Pages: 1 Limit: 20 Offset: 0 Page: 1  ***

# 从上面看到有两个 USB 设备列表,然后我把 Kingston U 盘拔掉
$ lsusb
Bus 001 Device 002: ID 0627:0001 Adomax Technology Co., Ltd

# 执行命令同步当前宿主机设备信息
$ climc host-probe-isolated-devices oc-node-1-192-168-121-21

# 再查看设备列表就只有一个了,Kingston U 盘记录已经被删掉
$ climc isolated-device-list  --host oc-node-1-192-168-121-21
+--------------------------------------+----------+----------------------------+---------+------------------+--------------------------------------+
|                  ID                  | Dev_type |           Model            |  Addr   | Vendor_device_id |               Host_id                |
+--------------------------------------+----------+----------------------------+---------+------------------+--------------------------------------+
| fa3cdbbd-7c54-4d2a-87cd-9362aa590a7d | USB      | Adomax Technology Co., Ltd | 001:002 | 0627:0001        | 7a11731f-dcc0-41e5-8d64-68eb36defcbe |
+--------------------------------------+----------+----------------------------+---------+------------------+--------------------------------------+
***  Total: 1 Pages: 1 Limit: 20 Offset: 0 Page: 1  ***

WebUI动态刷新USB设备

为了方便用户使用,WebUI会在以下场景自动刷新指定宿主机的透传USB设备列表:

  1. 访问宿主机-详情-透传设备,会自动刷新指定宿主机的透传设备
  2. 访问虚拟机-设置USB透传

指定USB控制器

默认采用qemu-xhci的USB控制器,该控制器支持版本为USB 3.0,向下兼容2.0。对于老版本的操作系统,例如 Windows Server 2008 R2,不识别USB 3.0的控制器,此时需要改为USB 2.0的控制器 usb-ehci。可以通过一下climc命令行更改虚拟机使用的USB控制器:

climc server-set-qemu-params <sid> --usb-controller-type <usb-ehci|qemu-xhci>

更改后,请请重启虚拟机。