doc: lint markdown files

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.
This commit is contained in:
Ben Grande 2024-07-04 17:10:11 +02:00
parent 88d9ba525c
commit 383c840f2f
No known key found for this signature in database
GPG key ID: 00C64E14F51F9E56
68 changed files with 1297 additions and 815 deletions

View file

@ -4,18 +4,18 @@ 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](#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
@ -24,24 +24,29 @@ the USB controllers to different qubes is possible.
## Installation
- Top:
* Top:
```sh
sudo qubesctl top.enable sys-usb
sudo qubesctl --targets=tpl-sys-usb state.apply
sudo qubesctl top.disable sys-usb
```
- State:
* 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
```
@ -49,13 +54,16 @@ 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
```
@ -65,6 +73,7 @@ qvm-prefs QUBE audiovm disp-sys-usb
#### 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
```
@ -72,6 +81,7 @@ sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-
#### 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
```
@ -79,10 +89,13 @@ sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-
#### 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
```
@ -91,9 +104,10 @@ qvm-features QUBE service.qubes-ctap-proxy 1
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`.
* `qubes.InputMouse`, `qubes.InputKeyboard`, `qubes.InputTablet`;
* `ctap.GetInfo`, `ctap.ClientPin`, `u2f.Register`, `u2f.Authenticate`,
`policy.RegisterArgument`.
## Usage
@ -114,32 +128,32 @@ 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.
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.
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
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
* Least latency.
* Disadvantages:
* Can't use video-companion to screen share and share webcam at the
same time; and
- Does not cover audio.
* Does not cover audio.
## Credits
- [Unman](https://github.com/unman/shaker/blob/main/sys-usb)
* [Unman](https://github.com/unman/shaker/blob/main/sys-usb)