2023-11-13 09:33:28 -05:00
|
|
|
# sys-usb
|
|
|
|
|
|
|
|
PCI handler of USB devices in Qubes OS.
|
|
|
|
|
|
|
|
## Table of Contents
|
|
|
|
|
|
|
|
* [Description](#description)
|
|
|
|
* [Installation](#installation)
|
2024-02-28 16:22:59 -05:00
|
|
|
* [Keyboard installation](#keyboard-installation)
|
|
|
|
* [AudioVM installation](#audiovm-installation)
|
|
|
|
* [Client installation](#client-installation)
|
|
|
|
* [Client USB proxy installation](#client-usb-proxy-installation)
|
|
|
|
* [Client cryptsetup installation](#client-cryptsetup-installation)
|
|
|
|
* [Client CTAP installation](#client-ctap-installation)
|
2024-01-10 06:50:02 -05:00
|
|
|
* [Access control](#access-control)
|
2023-11-13 09:33:28 -05:00
|
|
|
* [Usage](#usage)
|
2024-02-28 16:22:59 -05:00
|
|
|
* [How to use audio devices](#how-to-use-audio-devices)
|
2023-11-13 09:33:28 -05:00
|
|
|
* [Credits](#credits)
|
|
|
|
|
|
|
|
## Description
|
|
|
|
|
|
|
|
Setup named disposables for USB qubes. During creation, it tries to separate
|
|
|
|
the USB controllers to different qubes is possible.
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
- Top:
|
|
|
|
```sh
|
2024-02-23 10:54:35 -05:00
|
|
|
sudo qubesctl top.enable sys-usb
|
|
|
|
sudo qubesctl --targets=tpl-sys-usb state.apply
|
|
|
|
sudo qubesctl top.disable sys-usb
|
2023-11-13 09:33:28 -05:00
|
|
|
```
|
|
|
|
|
|
|
|
- State:
|
|
|
|
<!-- pkg:begin:post-install -->
|
|
|
|
```sh
|
2024-02-23 10:54:35 -05:00
|
|
|
sudo qubesctl state.apply sys-usb.create
|
|
|
|
sudo qubesctl --skip-dom0 --targets=tpl-sys-usb state.apply sys-usb.install
|
2023-11-13 09:33:28 -05:00
|
|
|
```
|
|
|
|
<!-- pkg:end:post-install -->
|
|
|
|
|
2024-02-28 16:22:59 -05:00
|
|
|
### Keyboard installation
|
|
|
|
|
2023-11-13 09:33:28 -05:00
|
|
|
If you use an USB keyboard, also run:
|
|
|
|
```sh
|
2024-02-23 10:54:35 -05:00
|
|
|
sudo qubesctl state.apply sys-usb.keyboard
|
2023-11-13 09:33:28 -05:00
|
|
|
```
|
|
|
|
|
2024-02-28 16:22:59 -05:00
|
|
|
### AudioVM installation
|
|
|
|
|
|
|
|
If you plan to use `disp-sys-usb` as an AudioVM:
|
|
|
|
```sh
|
|
|
|
sudo qubesctl --skip-dom0 --targets=tpl-sys-usb state.apply sys-audio.install
|
|
|
|
sudo qubesctl --skip-dom0 --targets=dvm-sys-usb state.apply sys-audio.configure-dvm
|
|
|
|
qvm-tags disp-sys-usb add audiovm
|
|
|
|
qvm-features disp-sys-usb service.audiovm 1
|
|
|
|
```
|
|
|
|
And set the qube preference `audiovm` to `disp-sys-usb`:
|
|
|
|
```sh
|
|
|
|
qvm-prefs QUBE audiovm disp-sys-usb
|
|
|
|
```
|
|
|
|
|
|
|
|
### Client installation
|
|
|
|
|
|
|
|
#### Client USB proxy installation
|
|
|
|
|
2023-11-13 09:33:28 -05:00
|
|
|
Install the proxy on the client template:
|
|
|
|
```sh
|
2024-02-23 10:54:35 -05:00
|
|
|
sudo qubesctl --skip-dom0 --targets=tpl-QUBE state.apply sys-usb.install-client-proxy
|
2023-11-13 09:33:28 -05:00
|
|
|
```
|
2024-01-09 12:44:50 -05:00
|
|
|
|
2024-02-28 16:22:59 -05:00
|
|
|
#### Client cryptsetup installation
|
|
|
|
|
2023-11-13 09:33:28 -05:00
|
|
|
If the client requires decrypting a device, install on the client template:
|
|
|
|
```sh
|
2024-02-23 10:54:35 -05:00
|
|
|
sudo qubesctl --skip-dom0 --targets=tpl-QUBE state.apply sys-usb.install-client-cryptsetup
|
2023-11-13 09:33:28 -05:00
|
|
|
```
|
2024-01-09 12:44:50 -05:00
|
|
|
|
2024-02-28 16:22:59 -05:00
|
|
|
#### Client CTAP installation
|
|
|
|
|
|
|
|
If the client requires a CTAP device, install on the client template:
|
2023-11-13 09:33:28 -05:00
|
|
|
```sh
|
2024-02-23 10:54:35 -05:00
|
|
|
sudo qubesctl --skip-dom0 --targets=tpl-QUBE state.apply sys-usb.install-client-fido
|
2023-11-13 09:33:28 -05:00
|
|
|
```
|
2024-01-09 12:44:50 -05:00
|
|
|
And enable the CTAP Proxy service for the client qubes:
|
|
|
|
```sh
|
|
|
|
qvm-features QUBE service.qubes-ctap-proxy 1
|
|
|
|
```
|
2023-11-13 09:33:28 -05:00
|
|
|
|
2024-01-10 06:50:02 -05:00
|
|
|
## Access control
|
|
|
|
|
|
|
|
No extra services are implemented, consult upstream to learn how to use the
|
|
|
|
following services:
|
|
|
|
- `qubes.InputMouse`, `qubes.InputKeyboard`, `qubes.InputTablet`;
|
|
|
|
- `ctap.GetInfo`, `ctap.ClientPin`, `u2f.Register`, `u2f.Authenticate`,
|
|
|
|
`policy.RegisterArgument`.
|
|
|
|
|
2023-11-13 09:33:28 -05:00
|
|
|
## Usage
|
|
|
|
|
2024-01-12 12:21:35 -05:00
|
|
|
Depending on you system, one or more USB qubes will be created to hold the
|
|
|
|
different controllers. The qube names are `disp-sys-usb`, `disp-sys-usb-left`,
|
|
|
|
`disp-sys-usb-dock`.
|
|
|
|
|
2024-02-28 16:22:59 -05:00
|
|
|
Start a USB qube an connect a device to it. USB PCI devices will appear on the
|
|
|
|
system tray icon `qui-devices`. From there, assign it to the intended qube.
|
|
|
|
|
|
|
|
### How to use audio devices
|
|
|
|
|
|
|
|
Bluetooth and Camera are normally integrated in laptops, but they still are
|
|
|
|
USB devices internally. They will be held by `(disp-)sys-usb` or
|
|
|
|
`(disp-)sys-net`, else `dom0`.
|
|
|
|
|
|
|
|
Built-in microphones on the other hand, are directly attached to `dom0`.
|
|
|
|
|
|
|
|
To use these devices, there are two options:
|
|
|
|
|
|
|
|
1. Attaching the device (USB passthrough) to the audio client:
|
|
|
|
- Advantages:
|
|
|
|
- Easier setup as it doesn't require an AudioVM.
|
|
|
|
- Disadvantages:
|
|
|
|
- Increased latency;
|
|
|
|
- Only one qube can use the device; and
|
|
|
|
- Less secure as it exposes the Audio stack to the client.
|
|
|
|
|
|
|
|
2. Leaving devices to the AudioVM (`(disp-)sys-usb` as AudioVM):
|
|
|
|
- Advantages:
|
|
|
|
- More secure as the devices are not on the client;
|
|
|
|
- Less latency; and
|
|
|
|
- All audio clients will have the same audio capabilities.
|
|
|
|
- Disadvantages:
|
|
|
|
- Some applications might not work due to not finding the device.
|
2023-11-13 09:33:28 -05:00
|
|
|
|
2024-06-04 13:59:45 -04:00
|
|
|
3. Using [video-companion](../video-companion/README.md) to access webcam:
|
|
|
|
- Advantages:
|
|
|
|
- The most secure for client and server as the physical devices are
|
|
|
|
unmanaged;
|
|
|
|
- Least latency.
|
|
|
|
- Disadvantages:
|
|
|
|
- Can't use video-companion to screen share and share webcam at the
|
|
|
|
same time; and
|
|
|
|
- Does not cover audio.
|
|
|
|
|
2023-11-13 09:33:28 -05:00
|
|
|
## Credits
|
|
|
|
|
|
|
|
- [Unman](https://github.com/unman/shaker/blob/main/sys-usb)
|