qusal/salt/sys-usb/README.md

146 lines
4.3 KiB
Markdown
Raw Normal View History

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)
* [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)
* [Access control](#access-control)
2023-11-13 09:33:28 -05:00
* [Usage](#usage)
* [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
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
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 -->
### Keyboard installation
2023-11-13 09:33:28 -05:00
If you use an USB keyboard, also run:
```sh
sudo qubesctl state.apply sys-usb.keyboard
2023-11-13 09:33:28 -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
sudo qubesctl --skip-dom0 --targets=tpl-QUBE state.apply sys-usb.install-client-proxy
2023-11-13 09:33:28 -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
sudo qubesctl --skip-dom0 --targets=tpl-QUBE state.apply sys-usb.install-client-cryptsetup
2023-11-13 09:33:28 -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
sudo qubesctl --skip-dom0 --targets=tpl-QUBE state.apply sys-usb.install-client-fido
2023-11-13 09:33:28 -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
## 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
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`.
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
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)