mirror of
https://github.com/ben-grande/qusal.git
synced 2025-03-01 11:21:15 -05:00
383c840f2f
Only way to have a unified markdown syntax is to enforce the wanted syntax by linting the files. Don't rely on the many markdown syntaxes, be consistent.
160 lines
4.4 KiB
Markdown
160 lines
4.4 KiB
Markdown
# 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)
|
|
* [Usage](#usage)
|
|
* [How to use audio devices](#how-to-use-audio-devices)
|
|
* [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
|
|
```
|
|
|
|
* 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
|
|
```
|
|
|
|
<!-- pkg:end:post-install -->
|
|
|
|
### Keyboard installation
|
|
|
|
If you use an USB keyboard, also run:
|
|
|
|
```sh
|
|
sudo qubesctl state.apply sys-usb.keyboard
|
|
```
|
|
|
|
### 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
|
|
|
|
Install the proxy on the client template:
|
|
|
|
```sh
|
|
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-proxy
|
|
```
|
|
|
|
#### Client cryptsetup installation
|
|
|
|
If the client requires decrypting a device, install on the client template:
|
|
|
|
```sh
|
|
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-cryptsetup
|
|
```
|
|
|
|
#### Client CTAP installation
|
|
|
|
If the client requires a CTAP device, install on the client template:
|
|
|
|
```sh
|
|
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-fido
|
|
```
|
|
|
|
And enable the CTAP Proxy service for the client qubes:
|
|
|
|
```sh
|
|
qvm-features QUBE service.qubes-ctap-proxy 1
|
|
```
|
|
|
|
## 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`.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
## Credits
|
|
|
|
* [Unman](https://github.com/unman/shaker/blob/main/sys-usb)
|