From 383c840f2ff6658d0b64eb79c851305fc946f55e Mon Sep 17 00:00:00 2001 From: Ben Grande Date: Thu, 4 Jul 2024 17:10:11 +0200 Subject: [PATCH] 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. --- .mdl-style.rb | 21 ++ .mdlrc | 6 + .pre-commit-config.yaml | 11 +- README.md | 37 ++-- docs/BOOTSTRAP.md | 118 +++++------ docs/CONTRIBUTE.md | 45 +++-- docs/DESIGN.md | 306 +++++++++++++++-------------- docs/INSTALL.md | 70 ++++--- docs/SALT.md | 34 ++-- docs/TROUBLESHOOT.md | 25 ++- salt/ansible/README.md | 15 +- salt/browser/README.md | 38 ++-- salt/debian-minimal/README.md | 14 +- salt/debian-xfce/README.md | 14 +- salt/debian/README.md | 14 +- salt/dev/README.md | 33 ++-- salt/dev/install.sls | 1 + salt/docker/README.md | 15 +- salt/dom0/README.md | 24 ++- salt/dotfiles | 2 +- salt/electrum/README.md | 31 +-- salt/element/README.md | 14 +- salt/fedora-minimal/README.md | 15 +- salt/fedora-xfce/README.md | 14 +- salt/fedora/README.md | 14 +- salt/fetcher/README.md | 14 +- salt/kicksecure-minimal/README.md | 43 ++-- salt/mail/README.md | 65 +++--- salt/media/README.md | 18 +- salt/mgmt/README.md | 14 +- salt/mirage-builder/README.md | 15 +- salt/opentofu/README.md | 14 +- salt/qubes-builder/README.md | 33 +++- salt/reader/README.md | 18 +- salt/remmina/README.md | 14 +- salt/signal/README.md | 14 +- salt/ssh/README.md | 18 +- salt/sys-audio/README.md | 49 +++-- salt/sys-bitcoin/README.md | 98 +++++---- salt/sys-cacher/README.md | 54 +++-- salt/sys-electrs/README.md | 18 +- salt/sys-electrumx/README.md | 18 +- salt/sys-firewall/README.md | 15 +- salt/sys-git/README.md | 61 +++--- salt/sys-mirage-firewall/README.md | 23 ++- salt/sys-net/README.md | 19 +- salt/sys-pgp/README.md | 22 ++- salt/sys-pihole/README.md | 39 ++-- salt/sys-print/README.md | 40 ++-- salt/sys-rsync/README.md | 31 +-- salt/sys-ssh-agent/README.md | 67 ++++--- salt/sys-ssh/README.md | 30 +-- salt/sys-syncthing/README.md | 32 ++- salt/sys-usb/README.md | 92 +++++---- salt/sys-wireguard/README.md | 24 ++- salt/terraform/README.md | 14 +- salt/usb/README.md | 14 +- salt/utils/README.md | 4 +- salt/utils/tools/builder/README.md | 9 +- salt/utils/tools/zsh/README.md | 14 +- salt/vault/README.md | 14 +- salt/video-companion/README.md | 21 +- salt/whonix-gateway/README.md | 14 +- salt/whonix-workstation/README.md | 14 +- scripts/markdown-lint.sh | 41 ++++ scripts/salt-lint.sh | 5 +- scripts/spec-gen.sh | 2 +- scripts/spec-get.sh | 3 +- 68 files changed, 1297 insertions(+), 815 deletions(-) create mode 100644 .mdl-style.rb create mode 100644 .mdlrc create mode 100755 scripts/markdown-lint.sh diff --git a/.mdl-style.rb b/.mdl-style.rb new file mode 100644 index 0000000..040130e --- /dev/null +++ b/.mdl-style.rb @@ -0,0 +1,21 @@ +# SPDX-FileCopyrightText: 2024 Benjamin Grande M. S. +# +# SPDX-License-Identifier: AGPL-3.0-or-later + +## Load all rules +all + +## List indentation +rule "MD007", :indent => 4 + +## Line length +rule "MD013", :line_length => 78, :ignore_code_blocks => true, :tables => false + +## List order +rule "MD029", :style => :ordered + +## Space after list markers +rule "MD030", :ul_single => 3, :ol_single => 2, :ul_multi => 3, :ol_multi => 2 + +## In-line HTML +exclude_rule "MD033" diff --git a/.mdlrc b/.mdlrc new file mode 100644 index 0000000..c32a662 --- /dev/null +++ b/.mdlrc @@ -0,0 +1,6 @@ +# SPDX-FileCopyrightText: 2024 Benjamin Grande M. S. +# +# SPDX-License-Identifier: MIT + +# vim: ft=ruby +style "#{File.dirname(__FILE__)}/.mdl-style.rb" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3b6e933..4608e6a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ -# SPDX-FileCopyrightText: 2023 Benjamin Grande M. S. +# SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. # -# SPDX-License-Identifier: GPL-3.0-or-later +# SPDX-License-Identifier: AGPL-3.0-or-later --- repos: @@ -22,6 +22,13 @@ repos: pass_filenames: false description: Lint files to comply with the REUSE Specification + - id: markdown-lint + name: markdown-lint + entry: scripts/markdown-lint.sh + language: script + pass_filenames: true + description: Lint markdown files + - id: salt-lint name: salt-lint entry: scripts/salt-lint.sh diff --git a/README.md b/README.md index 516970f..3143ede 100644 --- a/README.md +++ b/README.md @@ -9,17 +9,17 @@ and will be introduced in the meantime. You've been warned. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) -* [Contribute](#contribute) -* [Donate](#donate) -* [Support](#support) - * [Free Support](#free-support) - * [Paid Support](#paid-support) -* [Contact](#contact) -* [Credits](#credits) -* [Legal](#legal) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) +* [Contribute](#contribute) +* [Donate](#donate) +* [Support](#support) + * [Free Support](#free-support) + * [Paid Support](#paid-support) +* [Contact](#contact) +* [Credits](#credits) +* [Legal](#legal) ## Description @@ -37,12 +37,12 @@ allowed to make. Here are some of the Global Preferences we can manage: -- **clockvm**: disp-sys-net, sys-net -- **default_audiovm**: disp-sys-audio -- **default_dispvm**: dvm-reader -- **default_netvm**: sys-pihole, sys-firewall or disp-sys-firewall -- **management_dispvm**: dvm-mgmt -- **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall +* **clockvm**: disp-sys-net, sys-net +* **default_audiovm**: disp-sys-audio +* **default_dispvm**: dvm-reader +* **default_netvm**: sys-pihole, sys-firewall or disp-sys-firewall +* **management_dispvm**: dvm-mgmt +* **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall ## Installation @@ -104,7 +104,7 @@ Paid consultation services can be provided. Request a quote You must not contact for [free support](#free-support). -- [E-mail](https://github.com/ben-grande/ben-grande) +* [E-mail](https://github.com/ben-grande/ben-grande) ## Credits @@ -119,6 +119,7 @@ list all licenses and copyrights and keep them up-to-date here. The easiest way to get the copyright and license of the project is with the reuse tool: + ```sh reuse spdx ``` diff --git a/docs/BOOTSTRAP.md b/docs/BOOTSTRAP.md index f324ced..c385bee 100644 --- a/docs/BOOTSTRAP.md +++ b/docs/BOOTSTRAP.md @@ -4,12 +4,12 @@ Qusal bootstrap strategy. ## Table of Contents -* [Description](#description) -* [Essential](#essential) -* [Optional](#optional) - * [Internet communication](#internet-communication) - * [Files](#files) - * [Admin](#admin) +* [Description](#description) +* [Essential](#essential) +* [Optional](#optional) + * [Internet communication](#internet-communication) + * [Files](#files) + * [Admin](#admin) ## Description @@ -22,75 +22,75 @@ matter in some circumstances, in those cases, it is noted in this page. ## Essential -- Base (order matters): - - [dom0](../salt/dom0/README.md) - - [debian-minimal](../salt/debian-minimal/README.md) - - [fedora-minimal](../salt/fedora-minimal/README.md) - - [mgmt](../salt/mgmt/README.md) - - [sys-cacher](../salt/sys-cacher/README.md) +* Base (order matters): + * [dom0](../salt/dom0/README.md) + * [debian-minimal](../salt/debian-minimal/README.md) + * [fedora-minimal](../salt/fedora-minimal/README.md) + * [mgmt](../salt/mgmt/README.md) + * [sys-cacher](../salt/sys-cacher/README.md) ## Optional ### Internet communication -- PCI devices holders: - - [sys-net](../salt/sys-net/README.md) - - [sys-audio](../salt/sys-audio/README.md) - - [sys-usb](../salt/sys-usb/README.md) +* PCI devices holders: + * [sys-net](../salt/sys-net/README.md) + * [sys-audio](../salt/sys-audio/README.md) + * [sys-usb](../salt/sys-usb/README.md) -- Firewall, DNS Sinkhole and VPN Tunnel: - - [sys-firewall](../salt/sys-firewall/README.md) - - [sys-mirage-firewall](../salt/sys-mirage-firewall/README.md) - - [sys-pihole](../salt/sys-pihole/README.md) - - [sys-wireguard](../salt/sys-wireguard/README.md) +* Firewall, DNS Sinkhole and VPN Tunnel: + * [sys-firewall](../salt/sys-firewall/README.md) + * [sys-mirage-firewall](../salt/sys-mirage-firewall/README.md) + * [sys-pihole](../salt/sys-pihole/README.md) + * [sys-wireguard](../salt/sys-wireguard/README.md) -- Web browser and file retriever: - - [browser](../salt/browser/README.md) - - [fetcher](../salt/fetcher/README.md) +* Web browser and file retriever: + * [browser](../salt/browser/README.md) + * [fetcher](../salt/fetcher/README.md) -- Instant messaging and E-Mail: - - [mail](../salt/mail/README.md) - - [signal](../salt/signal/README.md) - - [element](../salt/element/README.md) +* Instant messaging and E-Mail: + * [mail](../salt/mail/README.md) + * [signal](../salt/signal/README.md) + * [element](../salt/element/README.md) -- Electronic cash: - - [sys-bitcoin](../salt/sys-bitcoin/README.md) - - [sys-electrumx](../salt/sys-electrumx/README.md) - - [sys-electrs](../salt/sys-electrs/README.md) - - [electrum](../salt/electrum/README.md) +* Electronic cash: + * [sys-bitcoin](../salt/sys-bitcoin/README.md) + * [sys-electrumx](../salt/sys-electrumx/README.md) + * [sys-electrs](../salt/sys-electrs/README.md) + * [electrum](../salt/electrum/README.md) ### Files -- Passwords and TOTP: - - [vault](../salt/vault/README.md) +* Passwords and TOTP: + * [vault](../salt/vault/README.md) -- Multimedia: - - [reader](../salt/reader/README.md) - - [media](../salt/media/README.md) - - [sys-print](../salt/sys-print/README.md) - - [video-companion](../salt/video-companion/README.md) +* Multimedia: + * [reader](../salt/reader/README.md) + * [media](../salt/media/README.md) + * [sys-print](../salt/sys-print/README.md) + * [video-companion](../salt/video-companion/README.md) -- File sharing: - - [usb](../salt/usb/README.md) - - [sys-ssh](../salt/sys-ssh/README.md) - - [sys-syncthing](../salt/sys-syncthing/README.md) - - [sys-rsync](../salt/sys-rsync/README.md) +* File sharing: + * [usb](../salt/usb/README.md) + * [sys-ssh](../salt/sys-ssh/README.md) + * [sys-syncthing](../salt/sys-syncthing/README.md) + * [sys-rsync](../salt/sys-rsync/README.md) ### Admin -- Remote administration: - - [remmina](../salt/remmina/README.md) - - [ssh](../salt/ssh/README.md) - - [sys-ssh-agent](../salt/sys-ssh-agent/README.md) +* Remote administration: + * [remmina](../salt/remmina/README.md) + * [ssh](../salt/ssh/README.md) + * [sys-ssh-agent](../salt/sys-ssh-agent/README.md) -- Remote task execution and configuration management: - - [ansible](../salt/ansible/README.md) - - [docker](../salt/docker/README.md) - - [opentofu](../salt/opentofu/README.md) - - [terraform](../salt/terraform/README.md) +* Remote task execution and configuration management: + * [ansible](../salt/ansible/README.md) + * [docker](../salt/docker/README.md) + * [opentofu](../salt/opentofu/README.md) + * [terraform](../salt/terraform/README.md) -- Coding: - - [dev](../salt/dev/README.md) - - [sys-pgp](../salt/sys-pgp/README.md) - - [sys-git](../salt/sys-git/README.md) - - [sys-ssh-agent](../salt/sys-ssh-agent/README.md) +* Coding: + * [dev](../salt/dev/README.md) + * [sys-pgp](../salt/sys-pgp/README.md) + * [sys-git](../salt/sys-git/README.md) + * [sys-ssh-agent](../salt/sys-ssh-agent/README.md) diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md index 9eadfb0..99ac57a 100644 --- a/docs/CONTRIBUTE.md +++ b/docs/CONTRIBUTE.md @@ -4,11 +4,11 @@ Qusal contribution guidelines. ## Table of Contents -* [Respect](#respect) -* [Starters](#starters) -* [Environment](#environment) -* [Issues](#issues) -* [Lint](#lint) +* [Respect](#respect) +* [Starters](#starters) +* [Environment](#environment) +* [Issues](#issues) +* [Lint](#lint) ## Respect @@ -50,31 +50,32 @@ packages below depending on the task: General: -- git +* git For writing: -- editorconfig -- editorconfig plugin for your editor -- vim, [vim-jinja](https://github.com/ben-grande/vim-jinja), - [vim-salt](https://github.com/ben-grande/vim-salt) (recommended) +* editorconfig +* editorconfig plugin for your editor +* vim, [vim-jinja](https://github.com/ben-grande/vim-jinja), + [vim-salt](https://github.com/ben-grande/vim-salt) (recommended) For linting: -- pre-commit -- gitlint -- salt-lint -- shellcheck -- reuse +* gitlint +* markdownlint (ruby-mdl) +* pre-commit +* reuse +* salt-lint +* shellcheck For building RPMs: -- sed (GNU sed) -- dnf -- dnf-plugins-core (dnf builddep) -- rpm -- rpmlint -- rpmautospec (only available in Fedora) +* sed (GNU sed) +* dnf +* dnf-plugins-core (dnf builddep) +* rpm +* rpmlint +* rpmautospec (only available in Fedora) ## Issues @@ -90,12 +91,14 @@ already been sent, the maintainer has already read and both parties loses time. Install the local hooks: + ```sh pre-commit install gitlint install-hook ``` To run pre-commit linters: + ```sh pre-commit run ``` diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 5e1b126..1af8a81 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -4,27 +4,27 @@ Qusal design document. ## Table of Contents -* [Goal](#goal) -* [Documentation](#documentation) -* [Format](#format) - * [Readme](#readme) - * [Access Control](#access-control) - * [State file naming](#state-file-naming) - * [State ID](#state-id) - * [Qube preferences](#qube-preferences) - * [Qube naming](#qube-naming) - * [Qube label](#qube-label) - * [Qube menu](#qube-menu) - * [Qube features](#qube-features) - * [Qube connections](#qube-connections) - * [Qrexec call and policy](#qrexec-call-and-policy) - * [Qrexec socket services](#qrexec-socket-services) -* [Features](#features) - * [Browser isolation from the managed service](#browser-isolation-from-the-managed-service) -* [Release new version](#release-new-version) - * [Qubes OS major release upgrade](#qubes-os-major-release-upgrade) - * [Template major release upgrade](#template-major-release-upgrade) - * [Archive or Build from source major release upgrade](#archive-or-build-from-source-major-release-upgrade) +* [Goal](#goal) +* [Documentation](#documentation) +* [Format](#format) + * [Readme](#readme) + * [Access Control](#access-control) + * [State file naming](#state-file-naming) + * [State ID](#state-id) + * [Qube preferences](#qube-preferences) + * [Qube naming](#qube-naming) + * [Qube label](#qube-label) + * [Qube menu](#qube-menu) + * [Qube features](#qube-features) + * [Qube connections](#qube-connections) + * [Qrexec call and policy](#qrexec-call-and-policy) + * [Qrexec socket services](#qrexec-socket-services) +* [Features](#features) + * [Browser isolation from the managed service](#browser-isolation-from-the-managed-service) +* [Release new version](#release-new-version) + * [Qubes OS major release upgrade](#qubes-os-major-release-upgrade) + * [Template major release upgrade](#template-major-release-upgrade) + * [Archive or Build from source major release upgrade](#archive-or-build-from-source-major-release-upgrade) ## Goal @@ -55,7 +55,8 @@ provided via extra states that needs to be installed per the user discretion. Markdown code must follow [Google's Markdown style guide](https://google.github.io/styleguide/docguide/style.html). Any discrepancies with Google's style guide must be fixed or documented here -with clear motive. +with clear motive. Although some of Google's style guide is optional, we +enforce some for stylistic purpose via documentation lint tools. Documentation must not duplicate itself, but reference one another. Reproducing instructions that can be found in upstream documentation is @@ -69,19 +70,19 @@ modify the documentation constantly to keep up with upstream. Every project should have a README.md with at least the following sections: -- Table of Contents; -- Description; -- Installation; -- Access Control (if Qrexec policy changed); -- Usage; and -- Credits (if sourced). +* Table of Contents; +* Description; +* Installation; +* Access Control (if Qrexec policy changed); +* Usage; and +* Credits (if sourced). #### Access Control -- It must document default policy and RPC services the user can or should - edit. -- It must not document RPC services of other formulas unless the resolution of - the rule is `deny`. +* It must document default policy and RPC services the user can or should + edit. +* It must not document RPC services of other formulas unless the resolution + of the rule is `deny`. ### State file naming @@ -98,8 +99,8 @@ Every project should have a README.md with at least the following sections: 1. State IDs must use `-` as separator, not `_`. The underline is allowed in case the features it is changing has underline, such as `default_netvm`. -2. State IDs must always have the project ID, thus allowing to target multiple - states to the same minion from different projects without having +2. State IDs must always have the project ID, thus allowing to target + multiple states to the same minion from different projects without having conflicting IDs. ### Qube preferences @@ -110,12 +111,12 @@ We differ from upstream especially by placing the `dvm` part as the prefix of DispVM Templates. This is to easy parsing when the qube type is the first part of its name and no exceptions. -- **TemplateVM**: `tpl-NAME` -- **StandaloneVM**: `NAME` -- **AppVM**: `NAME` -- **DispVM**: `disp-NAME` -- **DispVM Template (AppVM)**: `dvm-NAME` -- **Service qubes (not a class)**: `sys-NAME` +* **TemplateVM**: `tpl-NAME` +* **StandaloneVM**: `NAME` +* **AppVM**: `NAME` +* **DispVM**: `disp-NAME` +* **DispVM Template (AppVM)**: `dvm-NAME` +* **Service qubes (not a class)**: `sys-NAME` We recommend that for user created qubes, use the domain in the prefix of the qube. An AppVM for personal banking will be named `personal-banking`, an @@ -131,44 +132,44 @@ the same as you trust your vault. The following method tries to fix this problem, domain name is in the prefix of the qube, the label is solely related to trustworthiness of the data it is dealing with. -- **Black**: - - **Trust**: Ultimate. - - **Description**: You must trust Dom0, Templates, Vaults, Management +* **Black**: + * **Trust**: Ultimate. + * **Description**: You must trust Dom0, Templates, Vaults, Management qubes, these qubes control your system and hold valuable information. - - **Examples**: dom0, tpl-ssh, vault, dvm-mgmt. -- **Gray**: - - **Trust**: Fully. - - **Description**: Trusted storage with extra RPC services that allow + * **Examples**: dom0, tpl-ssh, vault, dvm-mgmt. +* **Gray**: + * **Trust**: Fully. + * **Description**: Trusted storage with extra RPC services that allow certain operations to be made by the client and executed on the server or may build components for other qubes. - - **Examples**: sys-cacher, sys-git, sys-pgp, sys-ssh-agent, qubes-builder. -- **Purple**: - - **Trust**: Very much. - - **Description**: Has the ability to manager remote servers via encrypted - connections and depend on authorization provided by another qube. - Examples: ansible, dev, ssh, terraform. -- **Blue**: - - **Trust**: Much. - - **Description**: TODO - - **Examples**: TODO -- **Green**: - - **Trust**: Trusted. - - **Description**: TODO - - **Examples**: TODO -- **Yellow**: - - **Trust**: Relatively trusted. - - **Description**: TODO - - **Examples**: TODO -- **Orange**: - - **Trust**: Slight. - - **Description**: Controls the network flow of data to the client, + * **Examples**: sys-cacher, sys-git, sys-pgp, sys-ssh-agent, qubes-builder. +* **Purple**: + * **Trust**: Very much. + * **Description**: Has the ability to manager remote servers via encrypted + connections and depend on authorization provided by another qube. + Examples: ansible, dev, ssh, terraform. +* **Blue**: + * **Trust**: Much. + * **Description**: TODO + * **Examples**: TODO +* **Green**: + * **Trust**: Trusted. + * **Description**: TODO + * **Examples**: TODO +* **Yellow**: + * **Trust**: Relatively trusted. + * **Description**: TODO + * **Examples**: TODO +* **Orange**: + * **Trust**: Slight. + * **Description**: Controls the network flow of data to the client, normally a firewall. - - **Examples**: sys-firewall, sys-vpn, sys-pihole. -- **Red**: - - **Trust**: Untrusted. - - **Description**: Holds untrusted data (PCI devices, untrusted + * **Examples**: sys-firewall, sys-vpn, sys-pihole. +* **Red**: + * **Trust**: Untrusted. + * **Description**: Holds untrusted data (PCI devices, untrusted programs, disposables for opening untrusted files or web pages). - - **Examples**: sys-net, sys-usb, dvm-browser. + * **Examples**: sys-net, sys-usb, dvm-browser. #### Qube menu @@ -192,38 +193,39 @@ add a state to run a script during boot to unmask and start a specific service. The method below is most of the times combined with `systemd.unit` `ConditionPathExists=` to enable the service conditionally. -- Server's service name must match the syntax: `service-server` (example: - `rsync-server`, `syncthing-server`); -- Client's service name must match the syntax: `service-client` (example: - `ssh-client`; -- Local program's service name must match the syntax: `service` (example: - `docker`, `podman`. +* Server's service name must match the syntax: `service-server` (example: + `rsync-server`, `syncthing-server`); +* Client's service name must match the syntax: `service-client` (example: + `ssh-client`; +* Local program's service name must match the syntax: `service` (example: + `docker`, `podman`. ### Qube connections There are several ways a qube can connect to another, either directly with Xen or with Qrexec. If something is not required, we remove it. -- `template` is always required: - - When required, must be set to the custom-made template; - - When not possible to use, prefer StandaloneVMs instead. -- `audiovm` is rarely required on the majority of the projects: - - When required, set it to `"*default*"` to honor the global preferences. - - When not required, must be set to None; -- `netvm` is required on a lot of projects. - - When required, must not be managed to honor the global preferences. If - it requires a custom networking scheme, the state must make sure that - the netvm exists; - - When not required, must be set to None. -- `default_dispvm` is nice to have: - - When required, must guarantee that the network follows the same chain as - the calling qube in the default configuration; - - When not required, must be set to None. -- `management_dispvm` is always required: - - When required, should not be managed to honor the global preferences, +* `template` is always required: + * When required, must be set to the custom-made template; + * When not possible to use, prefer StandaloneVMs instead. +* `audiovm` is rarely required on the majority of the projects: + * When required, set it to `"*default*"` to honor the global + preferences. + * When not required, must be set to None; +* `netvm` is required on a lot of projects. + * When required, must not be managed to honor the global preferences. If + it requires a custom networking scheme, the state must make sure that + the netvm exists; + * When not required, must be set to None. +* `default_dispvm` is nice to have: + * When required, must guarantee that the network follows the same chain + as the calling qube in the default configuration; + * When not required, must be set to None. +* `management_dispvm` is always required: + * When required, should not be managed to honor the global preferences, but it can make sense to set a custom management qube for debugging. - - When not required, such as on qubes that don't work through Salt, don't - touch it, it doesn't increase attack surface. + * When not required, such as on qubes that don't work through Salt, + don't touch it, it doesn't increase attack surface. ### Qrexec call and policy @@ -232,8 +234,8 @@ Xen or with Qrexec. If something is not required, we remove it. to be set by Dom0 via the `target=` redirection parameter, instead of having to modify the client to target a different server via `qrexec-client-vm`. -3. Target qube for client script must default to `@default`, but other targets - must be allowed via parameters. +3. Target qube for client script must default to `@default`, but other + targets must be allowed via parameters. ### Qrexec socket services @@ -246,31 +248,32 @@ wants to connect in the server. We will refer to Unix Domains Sockets as Using `qusal.Service`, such as `qusal.Rsync`, `qusal.Syncthing`, `qusal.Ssh` has the following advantages: -- Usability: User recognizes the call per service name; -- Extensibility: Allows extending functionality for arguments added in the - future, no need to migrate user policy from `qubes.ConnectTCP`; - is not necessary; +* Usability: User recognizes the call per service name; +* Extensibility: Allows extending functionality for arguments added in the + future, no need to migrate user policy from `qubes.ConnectTCP`; is not + necessary; Rules for server RPC service: -- Symlink `qubes.ConnectTCP` to `qusal.Service` if connecting to a local port; -- Use `qubes.ConnectTCP` directly when the user won't manage the policy for - the wanted call, such as `sys-syncthing-browser`, where it happens that only - this qube will access the admin interface of `sys-syncthing`; -- Use `socat` to connect to remote hosts or UDS with path defined by the - service argument. +* Symlink `qubes.ConnectTCP` to `qusal.Service` if connecting to a local + port; +* Use `qubes.ConnectTCP` directly when the user won't manage the policy for + the wanted call, such as `sys-syncthing-browser`, where it happens that + only this qube will access the admin interface of `sys-syncthing`; +* Use `socat` to connect to remote hosts or UDS with path defined by the + service argument. Rules for client RPC call: -- Use `systemd.socket` units, it does not require `socat`, it is not - restricted to the use of `qubes.ConnectTCP` called by `qvm-connect-tcp`, the - service can be properly logged and status verified by a service manager - instead of forking socat to the background with a `rc.local` script and - finally, can be controlled by Qubes Services to enable or disable the unit - with `ConditionPathExists=` instead of doing if-else statements in - `rc.local`; -- Use of `socat` and `qvm-connect-tcp` is permitted for UDS and for - instructional use as it is very short. +* Use `systemd.socket` units, it does not require `socat`, it is not + restricted to the use of `qubes.ConnectTCP` called by `qvm-connect-tcp`, + the service can be properly logged and status verified by a service + manager instead of forking socat to the background with a `rc.local` + script and finally, can be controlled by Qubes Services to enable or + disable the unit with `ConditionPathExists=` instead of doing if-else + statements in `rc.local`; +* Use of `socat` and `qvm-connect-tcp` is permitted for UDS and for + instructional use as it is very short. ## Features @@ -287,7 +290,6 @@ the browser is compromised, it can compromise the server. Some projects that uses this enhancement are `sys-pihole`, `sys-syncthing` and `sys-cacher`. - ## Release new version The following sections instruct how a contributor or maintainer can deploy qu @@ -296,44 +298,44 @@ The following sections instruct how a contributor or maintainer can deploy qu Qubes OS major releases might come with changes that can impact the project. -1. Subscribe to the - [qubes-announce](https://www.qubes-os.org/support/#qubes-announce) mailing - list to receive notification of new Qubes OS releases. -2. Keep up changelogs, especially notices of deprecation, new packages being - added or modifications to those packages that affects our states. -3. Install the new Qubes OS version. -4. Install all formulas. -5. Change the supported or minimum required version of Qubes OS. +1. Subscribe to the + [qubes-announce](https://www.qubes-os.org/support/#qubes-announce) mailing + list to receive notification of new Qubes OS releases. +2. Keep up changelogs, especially notices of deprecation, new packages being + added or modifications to those packages that affects our states. +3. Install the new Qubes OS version. +4. Install all formulas. +5. Change the supported or minimum required version of Qubes OS. ### Template major release upgrade -1. Subscribe to the - [qubes-announce](https://www.qubes-os.org/support/#qubes-announce) mailing - list to receive notifications of new templates. -2. Install the new template version. -3. Clone template to a new testing name of your choice. -4. Install all formulas on the testing template and see which states failed. - Most of the times, the state will fail due to a change in package name - (occurs when package has version in the name) or a deprecation of a - package. -5. Check if there are new packages that are useful to each specified formula. - The best way is to see the `Recommends` and `Suggests` fields of the main - package that is installed. -6. Install all formulas as instructed in each of their documents. -7. Change the version of the base template. +1. Subscribe to the + [qubes-announce](https://www.qubes-os.org/support/#qubes-announce) mailing + list to receive notifications of new templates. +2. Install the new template version. +3. Clone template to a new testing name of your choice. +4. Install all formulas on the testing template and see which states failed. + Most of the times, the state will fail due to a change in package name + (occurs when package has version in the name) or a deprecation of a + package. +5. Check if there are new packages that are useful to each specified formula. + The best way is to see the `Recommends` and `Suggests` fields of the main + package that is installed. +6. Install all formulas as instructed in each of their documents. +7. Change the version of the base template. ### Archive or Build from source major release upgrade Some projects might use archives for lack of a better alternative. Dealing with them can be troublesome. Prefer packages from repositories when possible. -1. Subscribe to the vendor release announcement mailing list or RSS to receive - notifications of new versions. -2. Read the changelog, breaking changes and new features might be present. -3. Clone the qube that uses the archive to a new testing name of your choice. -4. Install the new archive version on the testing qube. Regarding breaking - changes, most projects implement a migration on the next restart of the - daemon that rebuilds a database index for example, if they don't, deal with - it. For new features, check if they should be added to the default - installation. -5. Change the version of the archive, git tag or commit. +1. Subscribe to the vendor release announcement mailing list or RSS to + receive notifications of new versions. +2. Read the changelog, breaking changes and new features might be present. +3. Clone the qube that uses the archive to a new testing name of your choice. +4. Install the new archive version on the testing qube. Regarding breaking + changes, most projects implement a migration on the next restart of the + daemon that rebuilds a database index for example, if they don't, deal + with it. For new features, check if they should be added to the default + installation. +5. Change the version of the archive, git tag or commit. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 894189c..45b9469 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -4,17 +4,17 @@ Qusal install and update guide. ## Table of Contents -* [Installation](#installation) - * [Prerequisites](#prerequisites) - * [DomU Installation](#domu-installation) - * [Dom0 Installation](#dom0-installation) -* [Update](#update) - * [DomU Update](#domu-update) - * [Dom0 Update with Git](#dom0-update-with-git) - * [Dom0 Update by literally copying the git repository](#dom0-update-by-literally-copying-the-git-repository) -* [Template upgrade](#template-upgrade) - * [Clean install](#clean-install) - * [Upgrade a template in-place](#upgrade-a-template-in-place) +* [Installation](#installation) + * [Prerequisites](#prerequisites) + * [DomU Installation](#domu-installation) + * [Dom0 Installation](#dom0-installation) +* [Update](#update) + * [DomU Update](#domu-update) + * [Dom0 Update with Git](#dom0-update-with-git) + * [Dom0 Update by literally copying the git repository](#dom0-update-by-literally-copying-the-git-repository) +* [Template upgrade](#template-upgrade) + * [Clean install](#clean-install) + * [Upgrade a template in-place](#upgrade-a-template-in-place) ## Installation @@ -22,8 +22,8 @@ Qusal install and update guide. You current setup needs to fulfill the following requisites: -- Qubes OS R4.2 -- Internet connection +* Qubes OS R4.2 +* Internet connection ### DomU Installation @@ -33,6 +33,7 @@ You current setup needs to fulfill the following requisites: 2. Clone the repository (if you made a fork, fork the submodule(s) before clone and use your remote repository instead, the submodules will also be from your fork). + ```sh git clone --recurse-submodules https://github.com/ben-grande/qusal.git ``` @@ -47,6 +48,7 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d 1. Copy the repository `$file` from the DomU `$qube` to Dom0 (substitute `CHANGEME` for the desired valued): + ```sh qube="CHANGEME" # qube name where you downloaded the repository file="CHANGEME" # path to the repository in the qube @@ -58,6 +60,7 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d ``` 2. Pass the maintainer's key from the qube to Dom0: + ```sh qvm-run --pass-io "${qube}" -- "cat /home/user/ben-code.asc" | tee /tmp/ben-code.asc ``` @@ -65,6 +68,7 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d 3. Verify that the key fingerprint matches `DF38 3487 5B65 7587 13D9 2E91 A475 969D E4E3 71E3`. You can use Sequoia-PGP or GnuPG for the fingerprint verification: + ```sh gpg --show-keys /tmp/ben-code.asc # or @@ -72,18 +76,21 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d ``` 4. Import the verified key to your keyring: + ```sh gpg --import /tmp/ben-code.asc ``` 5. Verify the [commit or tag signature](https://www.qubes-os.org/security/verifying-signatures/#how-to-verify-signatures-on-git-repository-tags-and-commits) and expect a good signature, be surprised otherwise: + ```sh git verify-commit HEAD git submodule foreach git verify-commit HEAD ``` 6. Copy the project to the Salt directories: + ```sh ~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh ``` @@ -97,6 +104,7 @@ demonstrated below. ### DomU Update Update the repository state in your DomU: + ```sh git -C ~/src/qusal fetch --recurse-submodules ``` @@ -112,13 +120,15 @@ with the sys-git formula. 2. Install `git` on Dom0, allow the Qrexec protocol to work in submodules and clone the repository to `~/src/qusal` (only has to be run once): + ```sh mkdir -p ~/src sudo qubesctl state.apply sys-git.install-client git clone --recurse-submodules qrexec://@default/qusal.git ~/src/qusal ``` -3. Next updates will be pulling instead of cloning: +3. Next updates will be pulling instead of cloning: + ```sh git -C ~/src/qusal pull --recurse-submodules git -C ~/src/qusal submodule update --merge @@ -127,12 +137,14 @@ with the sys-git formula. 4. Verify the commit or tag signature and expect a good signature, be surprised otherwise (signature verification on submodules is skipped if checking out but not merging): + ```sh git verify-commit HEAD git submodule foreach git verify-commit HEAD ``` 5. Copy the project to the Salt directories: + ``` ~/src/qusal/scripts/setup.sh ``` @@ -147,6 +159,7 @@ project had a signed archive. The `.git/info/exclude` can exclude modified files from being tracked and signature verification won't catch it. 1. Install the helpers scripts and git on Dom0 (only has to be run once): + ```sh sudo qubesctl state.apply dom0.install-helpers sudo qubes-dom0-update git @@ -154,6 +167,7 @@ files from being tracked and signature verification won't catch it. 2. Copy the repository `$file` from the DomU `$qube` to Dom0 (substitute `CHANGEME` for the desired valued): + ```sh qube="CHANGEME" # qube name where you downloaded the repository file="CHANGEME" # path to the repository in the qube @@ -164,12 +178,14 @@ files from being tracked and signature verification won't catch it. 3. Verify the commit or tag signature and expect a good signature, be surprised otherwise: + ```sh git verify-commit HEAD git submodule foreach git verify-commit HEAD ``` 4. Copy the project to the Salt directories: + ```sh ~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh ``` @@ -183,13 +199,13 @@ Template upgrade refers to template major releases upgrade. As we use Salt, doing clean installs are easy. Unfortunately QubesOS does not provided a CLI program to rename qubes. -1. Open `Qube Manager`, select the template you want to upgrade and rename it - adding the suffix `-old`. The `Qube Manager` will change the `template` - preference of qubes based on the chosen template. -2. Rerun the formulas that targeted the chosen template. -3. If the formula fails, use `Qubes Template Switcher` to set the `-old` - template to be used by the qubes managed by that specific formula. -3. Repeat for every template that needs to be upgraded. +1. Open `Qube Manager`, select the template you want to upgrade and rename it + adding the suffix `-old`. The `Qube Manager` will change the `template` + preference of qubes based on the chosen template. +2. Rerun the formulas that targeted the chosen template. +3. If the formula fails, use `Qubes Template Switcher` to set the `-old` + template to be used by the qubes managed by that specific formula. +4. Repeat for every template that needs to be upgraded. ### Upgrade a template in-place @@ -204,9 +220,9 @@ data can be present in the root volume, in-place upgrades are easier for this qube class instead of doing a migration of specific folders and files to the new qube. -1. If you still want to do upgrade in-place, refer to upstream guides, for - [Debian](https://www.qubes-os.org/doc/templates/debian/in-place-upgrade) - and - [Fedora](https://www.qubes-os.org/doc/templates/fedora/in-place-upgrade). -2. Rerun the formulas that targeted the chosen template. -3. Repeat for every template that needs to be upgraded. +1. If you still want to do upgrade in-place, refer to upstream guides, for + [Debian](https://www.qubes-os.org/doc/templates/debian/in-place-upgrade) + and + [Fedora](https://www.qubes-os.org/doc/templates/fedora/in-place-upgrade). +2. Rerun the formulas that targeted the chosen template. +3. Repeat for every template that needs to be upgraded. diff --git a/docs/SALT.md b/docs/SALT.md index 794d52d..a4e9c6e 100644 --- a/docs/SALT.md +++ b/docs/SALT.md @@ -4,14 +4,14 @@ Qusal SaltStack development guide. ## Table of Contents -* [What this guide is](#what-this-guide-is) -* [Resources](#resources) -* [Minion Configuration](#minion-configuration) -* [Jinja](#jinja) -* [Targetting Minions](#targetting-minions) -* [Idempotence](#idempotence) -* [Examples](#examples) -* [Troubleshooting](#troubleshooting) +* [What this guide is](#what-this-guide-is) +* [Resources](#resources) +* [Minion Configuration](#minion-configuration) +* [Jinja](#jinja) +* [Targetting Minions](#targetting-minions) +* [Idempotence](#idempotence) +* [Examples](#examples) +* [Troubleshooting](#troubleshooting) ## What this guide is @@ -97,9 +97,9 @@ been done, changed or not. The `cmd` state might still be needed in some circumstances: -- When Qubes OS does not provide a module; -- When SaltStack does provide a module; and -- When SaltStack module does not meet all requirements. +* When Qubes OS does not provide a module; +* When SaltStack does provide a module; and +* When SaltStack module does not meet all requirements. ## Examples @@ -111,6 +111,7 @@ make sure to install Qusal before, it is required to create the base templates, do Jinja imports and run Jinja macros. `create-keys.sls`: + ```salt {# Use Qubes OS Jinja Template to create qubes using 'qvm.vm' #} {% from "qvm/template.jinja" import load %} @@ -165,6 +166,7 @@ features: ``` `install-keys.sls`: + ```salt {# Avoid applying the state by mistake to dom0 #} {% if grains['nodename'] != 'dom0' %} @@ -213,6 +215,7 @@ keys-installed-os-specific: ``` `appmenus-keys.sls`: + ```salt {# From our Jinja template sync-appmenus, import 'sync_appmenus' macro #} {% from 'utils/macros/sync-appmenus.sls' import sync_appmenus %} @@ -223,16 +226,19 @@ keys-installed-os-specific: After you have created the states above, copy them to Dom0 in `/srv/salt`. Create the qube: + ```sh sudo qubesctl state.apply create-keys ``` Install packages in the qube template: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-keys state.apply install-keys ``` Make the application menus appear after the requirements are installed: + ```sh sudo qubesctl state.apply appmenus-keys ``` @@ -245,9 +251,9 @@ Qusal macros. The above examples are based on our [vault formula](../salt/vault) You may face some [YAML idiosyncrasies](https://docs.saltproject.io/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html), these are the common mistakes that you may commit. Use an editor that: -- Shows when tabs have been used instead of spaces; -- Highlights syntax for Salt, Jinja, Python, YAML and Shellscript; and -- Lints your file at will or when saving it; +* Shows when tabs have been used instead of spaces; +* Highlights syntax for Salt, Jinja, Python, YAML and Shellscript; and +* Lints your file at will or when saving it; For further debugging information on Qusal, read our [troubleshooting guide](TROUBLESHOOT.md). diff --git a/docs/TROUBLESHOOT.md b/docs/TROUBLESHOOT.md index 51bc054..78da77b 100644 --- a/docs/TROUBLESHOOT.md +++ b/docs/TROUBLESHOOT.md @@ -4,10 +4,10 @@ Qusal troubleshooting guidelines. ## Table of Contents -* [Detect if your issue was already opened](#detect-if-your-issue-was-already-opened) -* [Qrexec client shows Request refused](#qrexec-client-shows-request-refused) -* [Salt wrapper qubesctl command fails](#salt-wrapper-qubesctl-command-fails) -* [Get Salt management information](#get-salt-management-information) +* [Detect if your issue was already opened](#detect-if-your-issue-was-already-opened) +* [Qrexec client shows Request refused](#qrexec-client-shows-request-refused) +* [Salt wrapper qubesctl command fails](#salt-wrapper-qubesctl-command-fails) +* [Get Salt management information](#get-salt-management-information) ## Detect if your issue was already opened @@ -24,9 +24,9 @@ typo in the configuration. Therefore, it is recommended to: -- Check if there is a rule for the service you want to call that would either - result in `ask` or `allow`; and -- Check again and again if you made a typo in the policy. +* Check if there is a rule for the service you want to call that would + either result in `ask` or `allow`; and +* Check again and again if you made a typo in the policy. The examples below will use the qube `dev` and the RPC service `qubes.GetDate` and other common Qrexec RPC services as an example, substitute them with the @@ -34,23 +34,27 @@ qube and service you intend to use, such as qube `code` and service `qusal.GitInit`. On `dom0`, watch the Qrexec policy logs: + ```sh sudo journalctl -fu qubes-qrexec-policy-daemon | cut -d " " -f 7- ``` If you ave many simultaneous calls being shown, get on the important ones: + ```sh sudo journalctl -fu qubes-qrexec-policy-daemon | cut -d " " -f 7- \ | grep -e qubes.GetDate -e qubes.Filecopy ``` You can emulate the call from `dom0`: + ```sh qrexec-policy dev @default qubes.GetDate ``` On the qube making the call, run the `qrexec-client-vm` command directly rather than using a wrapper around it: + ```sh qrexec-client-vm @default qubes.GetDate ``` @@ -61,13 +65,15 @@ The Salt Project has [troubleshooting](https://docs.saltproject.io/en/latest/top page for a variety of problems you may encounter. A nice summary of the states can be seen with the `--show-output` argument: -``` + +```sh sudo qubesctl --show-output state.apply pkg.uptodate ``` Ending the Salt call with `-l debug` argument gives the most detailed output (may contain private information): -``` + +```sh sudo qubesctl state.apply pkg.uptodate -l debug ``` @@ -79,6 +85,7 @@ Let's gather some information about it. Get information about the global `management_dispvm` and the same property of a specific qube. In this example we use `tpl-qubes-builder`, substitute for the qube being managed: + ```sh sudo qubesctl state.apply dom0.helpers qvm-mgmt tpl-qubes-builder diff --git a/salt/ansible/README.md b/salt/ansible/README.md index 8fbd584..f88cbe1 100644 --- a/salt/ansible/README.md +++ b/salt/ansible/README.md @@ -4,9 +4,9 @@ Ansible environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -14,25 +14,30 @@ Install Ansible and use it on the "ansible" app qube. ## Installation -- Top +* Top: + ```sh sudo qubesctl top.enable ansible sudo qubesctl --targets=tpl-ansible,ansible,ansible-minion state.apply sudo qubesctl top.disable ansible ``` -- State +* State + + ```sh sudo qubesctl state.apply ansible.create sudo qubesctl --skip-dom0 --targets=tpl-ansible state.apply ansible.install ``` + ## Usage From the control node `ansible`, test connection to the managed node `ansible-minion`: + ```sh ssh -p 1840 user@127.0.0.1 ``` diff --git a/salt/browser/README.md b/salt/browser/README.md index 3a6e404..3ffe06b 100644 --- a/salt/browser/README.md +++ b/salt/browser/README.md @@ -4,10 +4,10 @@ Browser environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) - * [Choose your browser](#choose-your-browser) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) + * [Choose your browser](#choose-your-browser) +* [Usage](#usage) ## Description @@ -21,7 +21,8 @@ Firefox, Firefox-ESR, Mullvad-Browser, W3M or Lynx. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable browser sudo qubesctl --targets=tpl-browser,dvm-browser state.apply @@ -29,14 +30,17 @@ sudo qubesctl top.disable browser sudo qubesctl state.apply browser.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply browser.create sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install sudo qubesctl --skip-dom0 --targets=dvm-browser state.apply browser.configure sudo qubesctl state.apply browser.appmenus ``` + ### Choose your browser @@ -44,43 +48,50 @@ sudo qubesctl state.apply browser.appmenus Instead of running the state `browser.install`, you can select which browser to install: -- Chromium: +* Chromium: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-chromium ``` -- Chrome: +* Chrome: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-chrome ``` -- Firefox: +* Firefox: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-firefox ``` -- Firefox-ESR: +* Firefox-ESR: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-firefox-esr ``` -- Mullvad-Browser: +* Mullvad-Browser: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-mullvad ``` +* W3M: -- W3M: ```sh sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-w3m ``` -- Lynx: +* Lynx: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-lynx ``` Do not forget to sync the `appmenus`: + ```sh sudo qubesctl state.apply browser.appmenus ``` @@ -96,6 +107,7 @@ If you want to use a permanent browser session, create an app qube based on If you are forwarding URLs from other qubes via `qvm-open-in-(d)vm`, you might want to set your preferred browser as the default browser in `tpl-browser` targeting the desired desktop file: + ```sh xdg-settings set default-web-browser firefox-esr.desktop ``` diff --git a/salt/debian-minimal/README.md b/salt/debian-minimal/README.md index be2b54f..652d0b3 100644 --- a/salt/debian-minimal/README.md +++ b/salt/debian-minimal/README.md @@ -4,9 +4,9 @@ Debian Minimal Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -15,19 +15,23 @@ it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable debian-minimal sudo qubesctl --targets=debian-12-minimal state.apply sudo qubesctl top.disable debian-minimal ``` -- State: +* State: + + ```sh sudo qubesctl state.apply debian-minimal.create sudo qubesctl --skip-dom0 --targets=debian-12-minimal state.apply debian-minimal.install ``` + ## Usage diff --git a/salt/debian-xfce/README.md b/salt/debian-xfce/README.md index 0061346..0210b44 100644 --- a/salt/debian-xfce/README.md +++ b/salt/debian-xfce/README.md @@ -4,9 +4,9 @@ Debian Xfce Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -14,19 +14,23 @@ Creates the Debian Xfce Template as well as a Disposable Template based on it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable debian-xfce sudo qubesctl --targets=debian-12-xfce state.apply sudo qubesctl top.disable debian-xfce ``` -- State: +* State: + + ```sh sudo qubesctl state.apply debian-xfce.create sudo qubesctl --skip-dom0 --targets=debian-12-xfce state.apply debian-xfce.install ``` + ## Usage diff --git a/salt/debian/README.md b/salt/debian/README.md index 714ff61..ecfd616 100644 --- a/salt/debian/README.md +++ b/salt/debian/README.md @@ -4,9 +4,9 @@ Debian Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -14,19 +14,23 @@ Creates the Debian template as well as a Disposable Template based on it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable debian sudo qubesctl --targets=debian-12 state.apply sudo qubesctl top.disable debian ``` -- State: +* State: + + ```sh sudo qubesctl state.apply debian.create sudo qubesctl --skip-dom0 --targets=debian-12 state.apply debian.install ``` + ## Usage diff --git a/salt/dev/README.md b/salt/dev/README.md index 9c4192e..aa5faa3 100644 --- a/salt/dev/README.md +++ b/salt/dev/README.md @@ -4,10 +4,10 @@ Development environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Access Control](#access-control) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Access Control](#access-control) +* [Usage](#usage) ## Description @@ -18,7 +18,8 @@ allows. ## Installation -- Top +* Top: + ```sh sudo qubesctl top.enable dev sudo qubesctl --targets=tpl-dev,dvm-dev,dev state.apply @@ -29,8 +30,10 @@ if test -n "${proxy_target}"; then fi ``` -- State +* State: + + ```sh sudo qubesctl state.apply dev.create sudo qubesctl --skip-dom0 --targets=tpl-dev state.apply dev.install @@ -41,9 +44,11 @@ if test -n "${proxy_target}"; then sudo qubesctl --skip-dom0 --targets="${proxy_target}" state.apply sys-net.install-proxy fi ``` + If you want some Python goodies, you can install them: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-dev state.apply dev.install-python-tools ``` @@ -52,6 +57,7 @@ The installation will make the Qusal TCP Proxy available in the `updatevm` (after it is restarted in case it is template based). If you want to have the proxy available on a `netvm` that is not deployed by Qusal, install the Qusal TCP proxy on the templates of your `netvm`: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-net.install-proxy ``` @@ -65,6 +71,7 @@ _Default policy_: `denies` `all` qubes from calling `qusal.ConnectTCP` Allow qube `dev` to `connect` to `github.com:22` via `disp-sys-net` but not to any other host or via any other qube: + ```qrexecpolicy qusal.ConnectTCP +github.com+22 dev @default allow target=disp-sys-net qusal.ConnectTCP * dev @anyvm deny @@ -74,13 +81,13 @@ qusal.ConnectTCP * dev @anyvm deny The development qube `dev` can be used for: -- code development; -- building programs; -- signing commits, tags, pushes and verifying with split-gpg; -- fetching and pushing to and from local qube repository with split-git; and -- fetching and pushing to and from remote repository with split-ssh-agent and - without direct network connection, you can open port to the desired SSH or - HTTP server. +* code development; +* building programs; +* signing commits, tags, pushes and verifying with split-gpg; +* fetching and pushing to and from local qube repository with split-git; and +* fetching and pushing to and from remote repository with split-ssh-agent + and without direct network connection, you can open port to the desired + SSH or HTTP server. As the `dev` qube has no netvm, configure the Qrexec policy to allow or ask calls to the `qusal.ConnectTCP` RPC service, so the qube can communicate with diff --git a/salt/dev/install.sls b/salt/dev/install.sls index 4dc0414..d6950b1 100644 --- a/salt/dev/install.sls +++ b/salt/dev/install.sls @@ -45,6 +45,7 @@ include: - gitlint - pylint - yamllint + - markdowlint ## Debian doesn't have: salt-lint {% set pkg = { diff --git a/salt/docker/README.md b/salt/docker/README.md index d8e1939..006264a 100644 --- a/salt/docker/README.md +++ b/salt/docker/README.md @@ -4,9 +4,9 @@ Docker installation in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -16,21 +16,26 @@ Setup docker in Qubes OS with the Docker repository. TODO: remove installation steps or provide a docker qube. -- Top +* Top: + ```sh sudo qubesctl top.enable docker sudo qubesctl --targets=tpl-qubes-builder state.apply sudo qubesctl top.disable docker ``` -- State +* State: + + ```sh sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply docker.install ``` + Enable the Docker and/or Podman service for qubes that will use it: + ```sh qvm-features QUBE service.docker 1 qvm-features QUBE service.podman 1 diff --git a/salt/dom0/README.md b/salt/dom0/README.md index d90db64..3680206 100644 --- a/salt/dom0/README.md +++ b/salt/dom0/README.md @@ -4,10 +4,10 @@ Dom0 environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) - * [Choose your Dom0 environment](#choose-your-dom0-environment) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) + * [Choose your Dom0 environment](#choose-your-dom0-environment) +* [Usage](#usage) ## Description @@ -16,7 +16,8 @@ etc. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable dom0 sudo qubesctl state.apply @@ -24,20 +25,25 @@ sudo qubesctl top.disable dom0 sudo qubesctl --skip-dom0 --templates --standalones state.apply update.qubes-vm ``` -- State: +* State: + + ```sh sudo qubesctl state.apply dom0 sudo qubesctl --skip-dom0 --templates --standalones state.apply update.qubes-vm ``` + If you need to develop in Dom0, install some goodies (bare bones): + ```sh sudo qubesctl state.apply dom0.install-dev ``` To forward ports from qubes to the external world: + ```sh sudo qubesctl state.apply dom0.port-forward ``` @@ -46,12 +52,14 @@ sudo qubesctl state.apply dom0.port-forward Instead of running the state `dom0`, you can select which states to apply: -- Window Manager i3: +* Window Manager i3: + ```sh sudo qubesctl state.apply dom0.desktop-i3,dom0.desktop-i3-settings ``` -- Window Manager AwesomeWM: +* Window Manager AwesomeWM: + ```sh sudo qubesctl state.apply dom0.desktop-awesome ``` diff --git a/salt/dotfiles b/salt/dotfiles index 46d0753..56191da 160000 --- a/salt/dotfiles +++ b/salt/dotfiles @@ -1 +1 @@ -Subproject commit 46d0753329cfdc0fcb57e4575dc831c1c6951a72 +Subproject commit 56191dab6da297a48d3df41b65c1f0ae15e37ae1 diff --git a/salt/electrum/README.md b/salt/electrum/README.md index e6c6658..534975b 100644 --- a/salt/electrum/README.md +++ b/salt/electrum/README.md @@ -4,14 +4,14 @@ Electrum Bitcoin Wallet in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) - * [Connect your cold wallet to a trusted server](#connect-your-cold-wallet-to-a-trusted-server) - * [Connect your cold wallet to an untrusted server](#connect-your-cold-wallet-to-an-untrusted-server) - * [Recommendations for cryptographic operations](#recommendations-for-cryptographic-operations) - * [Cold wallet terminology](#cold-wallet-terminology) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) + * [Connect your cold wallet to a trusted server](#connect-your-cold-wallet-to-a-trusted-server) + * [Connect your cold wallet to an untrusted server](#connect-your-cold-wallet-to-an-untrusted-server) + * [Recommendations for cryptographic operations](#recommendations-for-cryptographic-operations) + * [Cold wallet terminology](#cold-wallet-terminology) +* [Credits](#credits) ## Description @@ -31,7 +31,8 @@ usage from ever connecting to the internet. ## Installation -- Top +* Top: + ```sh sudo qubesctl top.enable electrum sudo qubesctl --targets=tpl-electrum-builder,tpl-electrum,disp-electrum-builder,electrum,electrum-hot state.apply @@ -39,8 +40,10 @@ sudo qubesctl top.disable electrum sudo qubesctl state.apply electrum.appmenus ``` -- State +* State: + + ```sh sudo qubesctl state.apply electrum.create sudo qubesctl --skip-dom0 --targets=tpl-electrum-builder state.apply electrum.install-builder @@ -50,6 +53,7 @@ sudo qubesctl --skip-dom0 --targets=electrum state.apply electrum.configure sudo qubesctl --skip-dom0 --targets=electrum-hot state.apply electrum.configure-hot sudo qubesctl state.apply electrum.appmenus ``` + ## Usage @@ -75,24 +79,28 @@ our netvm qube is named `sys-net`. In the qube `dom0`, allow `electrum` to connect to `sys-net` port `50002` via Qrexec Policy in the file `/etc/qubes/policy.d/30-user.policy`: + ```qrexecpolicy qubes.ConnectTCP +50002 electrum @default allow target=sys-net ``` In the qube `sys-net`, add the `socat` command to the file `/rw/config/rc.local`: + ```sh socat TCP4-LISTEN:50002,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:50002 & ``` In the qube `electrum`, add the `qvm-connect-tcp` command to the file `/rw/config/rc.local`: + ```sh qvm-connect-tcp ::50002 ``` In the qube `electrum`, run as the user `user` the electrum configuration commands: + ```sh electrum --offline setconfig auto_connect false electrum --offline setconfig oneserver true @@ -100,6 +108,7 @@ electrum --offline setconfig server 127.0.0.1:50002 ``` If you used a plain-text port, no SSL: + ```sh electrum --offline setconfig server 127.0.0.1:50001:t ``` @@ -198,4 +207,4 @@ have more security, not the one you "fell" more secure. ## Credits -- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) +* [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) diff --git a/salt/element/README.md b/salt/element/README.md index bc7efd9..f8beeab 100644 --- a/salt/element/README.md +++ b/salt/element/README.md @@ -4,9 +4,9 @@ Element Matrix client installation in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -15,7 +15,8 @@ Matrix account. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable element sudo qubesctl --targets=tpl-element state.apply @@ -23,13 +24,16 @@ sudo qubesctl top.disable element sudo qubesctl state.apply element.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply element.create sudo qubesctl --skip-dom0 --targets=tpl-element state.apply element.install sudo qubesctl state.apply element.appmenus ``` + ## Usage diff --git a/salt/fedora-minimal/README.md b/salt/fedora-minimal/README.md index c6411bf..694cf83 100644 --- a/salt/fedora-minimal/README.md +++ b/salt/fedora-minimal/README.md @@ -4,10 +4,9 @@ Fedora Minimal Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) - +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -16,7 +15,8 @@ it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable fedora-minimal sudo qubesctl --targets=fedora-40-minimal state.apply @@ -24,13 +24,16 @@ sudo qubesctl top.disable fedora-minimal sudo qubesctl state.apply fedora-minimal.prefs ``` -- State: +* State: + + ```sh sudo qubesctl state.apply fedora-minimal.create sudo qubesctl --skip-dom0 --targets=fedora-40-minimal state.apply fedora-minimal.install sudo qubesctl state.apply fedora-minimal.prefs ``` + ## Usage diff --git a/salt/fedora-xfce/README.md b/salt/fedora-xfce/README.md index 195ae78..696510c 100644 --- a/salt/fedora-xfce/README.md +++ b/salt/fedora-xfce/README.md @@ -4,9 +4,9 @@ Fedora Xfce Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -14,19 +14,23 @@ Creates the Fedora Xfce template as well as a Disposable Template based on it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable fedora-xfce sudo qubesctl --targets=fedora-40-xfce state.apply sudo qubesctl top.disable fedora-xfce ``` -- State: +* State: + + ```sh sudo qubesctl state.apply fedora-xfce.create sudo qubesctl --skip-dom0 --targets=fedora-40-xfce state.apply fedora-xfce.install ``` + ## Usage diff --git a/salt/fedora/README.md b/salt/fedora/README.md index 9330246..262cb78 100644 --- a/salt/fedora/README.md +++ b/salt/fedora/README.md @@ -4,9 +4,9 @@ Fedora Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -14,19 +14,23 @@ Creates the Fedora template as well as a Disposable Template based on it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable fedora sudo qubesctl --targets=fedora-40 state.apply sudo qubesctl top.disable fedora ``` -- State: +* State: + + ```sh sudo qubesctl state.apply fedora.create sudo qubesctl --skip-dom0 --targets=fedora-40 state.apply fedora.install ``` + ## Usage diff --git a/salt/fetcher/README.md b/salt/fetcher/README.md index 0079a8e..e171a48 100644 --- a/salt/fetcher/README.md +++ b/salt/fetcher/README.md @@ -4,9 +4,9 @@ Fetch publicly accessible files over the internet in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -21,20 +21,24 @@ Supported protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable fetcher sudo qubesctl --targets=tpl-fetcher,dvm-fetcher state.apply sudo qubesctl top.disable fetcher ``` -- State: +* State: + + ```sh sudo qubesctl state.apply fetcher.create sudo qubesctl --skip-dom0 --targets=tpl-fetcher state.apply fetcher.install sudo qubesctl --skip-dom0 --targets=dvm-fetcher state.apply fetcher.configure-dvm ``` + ## Usage diff --git a/salt/kicksecure-minimal/README.md b/salt/kicksecure-minimal/README.md index b5be0cf..af07fa6 100644 --- a/salt/kicksecure-minimal/README.md +++ b/salt/kicksecure-minimal/README.md @@ -4,11 +4,11 @@ Kicksecure Minimal Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) - * [Kicksecure Developers Installation](#kicksecure-developers-installation) -* [Usage](#usage) - * [Kicksecure Developers Usage](#kicksecure-developers-usage) +* [Description](#description) +* [Installation](#installation) + * [Kicksecure Developers Installation](#kicksecure-developers-installation) +* [Usage](#usage) + * [Kicksecure Developers Usage](#kicksecure-developers-usage) ## Description @@ -17,19 +17,23 @@ on it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable kicksecure-minimal sudo qubesctl --targets=kicksecure-17-minimal state.apply sudo qubesctl top.disable kicksecure-minimal ``` -- State: +* State: + + ```sh sudo qubesctl state.apply kicksecure-minimal.create sudo qubesctl --skip-dom0 --targets=kicksecure-17-minimal state.apply kicksecure-minimal.install ``` + ### Kicksecure Developers Installation @@ -37,23 +41,27 @@ sudo qubesctl --skip-dom0 --targets=kicksecure-17-minimal state.apply kicksecure If you want to help improve Kicksecure integration on Qubes, install packages that are known to be broken on Qubes and can break the boot of the Kicksecure Qube, to report bugs upstream (get a terminal with `qvm-console-dispvm`): + ```sh sudo qubesctl --skip-dom0 --targets=kicksecure-17-minimal state.apply kicksecure-minimal.install-developers ``` Choose the `kernel` according to the `virt_mode` you want for the template: -- `hvm`: +* `hvm`: + ```sh sudo qubesctl state.apply kicksecure-minimal.kernel-hvm ``` -- `pvh`: +* `pvh`: + ```sh sudo qubesctl state.apply kicksecure-minimal.kernel-pv ``` -- Dom0 provided kernel (resets `virt_mode` to `pvh`): +* Dom0 provided kernel (resets `virt_mode` to `pvh`): + ```sh sudo qubesctl state.apply kicksecure-minimal.kernel-default ``` @@ -70,18 +78,21 @@ hardening measures. It is not intended for other developers or users. After you have ran the developers SaltFile, when reporting bugs upstream, share the following information of the customizations made by this formula: -- `hardened-malloc`: -``` +* `hardened-malloc`: + +```txt libhardened_malloc.so ``` -- `hide-hardware-info`: -``` +* `hide-hardware-info`: + +```sh sysfs_whitelist=0 cpuionfo_whitelist=0 ``` -- `permission-hardener`: -``` +* `permission-hardener`: + +```sh whitelists_disable_all=true ``` diff --git a/salt/mail/README.md b/salt/mail/README.md index 5439b1d..63096bd 100644 --- a/salt/mail/README.md +++ b/salt/mail/README.md @@ -4,22 +4,22 @@ Mail operations in Qubes OS. ## Table of Contents -* [Description](#description) -* [Security](#security) -* [Installation](#installation) -* [Usage](#usage) - * [Fetcher](#fetcher) - * [fdm Configuration](#fdm-configuration) - * [mpop Configuration](#mpop-configuration) - * [OfflineIMAP Configuration](#offlineimap-configuration) - * [Send Inbox to Reader Qube](#send-inbox-to-reader-qube) - * [Reader](#reader) - * [Mutt Configuration](#mutt-configuration) - * [Send Queue to Sender Qube](#send-queue-to-sender-qube) - * [Sender](#sender) - * [msmtp Configuration](#msmtp-configuration) - * [Send emails to SMTP server](#send-emails-to-smtp-server) -* [Credits](#credits) +* [Description](#description) +* [Security](#security) +* [Installation](#installation) +* [Usage](#usage) + * [Fetcher](#fetcher) + * [fdm Configuration](#fdm-configuration) + * [mpop Configuration](#mpop-configuration) + * [OfflineIMAP Configuration](#offlineimap-configuration) + * [Send Inbox to Reader Qube](#send-inbox-to-reader-qube) + * [Reader](#reader) + * [Mutt Configuration](#mutt-configuration) + * [Send Queue to Sender Qube](#send-queue-to-sender-qube) + * [Sender](#sender) + * [msmtp Configuration](#msmtp-configuration) + * [Send emails to SMTP server](#send-emails-to-smtp-server) +* [Credits](#credits) ## Description @@ -74,7 +74,8 @@ exploitation, as `msmtp` still needs to parse the mail to be sent. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable mail reader sudo qubesctl --targets=tpl-mail-fetcher,tpl-mail-reader,tpl-mail-sender,dvm-mail-fetcher,mail-reader,dvm-mail-sender,tpl-reader state.apply @@ -82,8 +83,10 @@ sudo qubesctl top.disable mail reader sudo qubesctl state.apply mail.appmenus,reader.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply mail.create sudo qubesctl --skip-dom0 --targets=tpl-reader state.apply reader.install @@ -95,6 +98,7 @@ sudo qubesctl --skip-dom0 --targets=mail-reader state.apply mail.configure-reade sudo qubesctl --skip-dom0 --targets=dvm-mail-sender state.apply mail.configure-sender sudo qubesctl state.apply mail.appmenus,reader.appmenus ``` + ## Usage @@ -108,9 +112,9 @@ or/and `IMAP` server and `SMTP` server, respectively. Steps overview: -1. Receive mail via the `mail-fetcher` and transfer mail to `mail-reader`. -2. Read and compose mail from `mail-reader` and transfer to `mail-sender`. -3. Send queued mails from `mail-sender` to remote mail server. +1. Receive mail via the `mail-fetcher` and transfer mail to `mail-reader`. +2. Read and compose mail from `mail-reader` and transfer to `mail-sender`. +3. Send queued mails from `mail-sender` to remote mail server. ### Fetcher @@ -124,26 +128,31 @@ mails will be done in `disp-mail-fetcher`. #### fdm Configuration Copy example configuration file to where the program can read automatically: + ```sh cp ~/.fdm.conf.example ~/.fdm.conf ``` Edit the configuration according to your needs: + ```sh editor ~/.fdm.conf ``` Check the connection is working: + ```sh fdm -kv poll ``` Fetch mail: + ```sh fdm -kv fetch ``` If the fetch was successful, enable the fetch scheduler: + ```sh systemctl --user enable fdm.timer systemctl --user start fdm.timer @@ -155,26 +164,31 @@ Copy `~/.mpoprc.example` to `~/.mpoprc` and edit the configuration according to your needs. Copy example configuration file to where the program can read automatically: + ```sh cp ~/.mporc.example ~/.mpoprc ``` Edit the configuration according to your needs: + ```sh editor ~/.mpoprc ``` Check the connection is working: + ```sh mpop --debug --auth-only ``` Fetch mail: + ```sh mpop ``` If the fetch was successful, enable the fetch scheduler: + ```sh systemctl --user enable mpop.timer systemctl --user start mpop.timer @@ -187,6 +201,7 @@ TODO: difficult to exemplify as the folders are user and provider specific. #### Send Inbox to Reader Qube Send the inbox to the reader: + ```sh qusal-send-inbox ``` @@ -217,6 +232,7 @@ Samples for the aforementioned files can be found at `~/.config/mutt/sample`. #### Send Queue to Sender Qube Send the queued mail to the sender: + ```sh qusal-send-mail ``` @@ -231,16 +247,19 @@ mails are done in `disp-mail-sender`. #### msmtp Configuration Copy example configuration file to where the program can read automatically: + ```sh cp ~/.msmtprc.example ~/.msmtprc ``` Edit the configuration according to your needs: + ```sh editor ~/.msmtprc ``` Test the connection to the SMTP server: + ```sh msmtp --serverinfo ``` @@ -248,15 +267,17 @@ msmtp --serverinfo #### Send emails to SMTP server List the queued mails: + ```sh msmtp-queue -d ``` Send selected mails from the queue to the SMTP server: + ```sh msmtp-queue -R ``` ## Credits -- [Unman](https://github.com/unman/notes/blob/master/SplitMutt.md) +* [Unman](https://github.com/unman/notes/blob/master/SplitMutt.md) diff --git a/salt/media/README.md b/salt/media/README.md index fe54d3e..185f37d 100644 --- a/salt/media/README.md +++ b/salt/media/README.md @@ -4,10 +4,10 @@ Media opener through disposables in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) +* [Credits](#credits) ## Description @@ -16,20 +16,24 @@ files in a named disposable "disp-media" via MIME configuration. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable media sudo qubesctl --targets=tpl-media,media state.apply sudo qubesctl top.disable media ``` -- State: +* State: + + ```sh sudo qubesctl state.apply media.create sudo qubesctl --skip-dom0 --targets=tpl-media state.apply media.install sudo qubesctl --skip-dom0 --targets=media state.apply media.configure ``` + ## Usage @@ -47,4 +51,4 @@ You can personalize `mpv` by editing `$XDG_CONFIG_HOME/mpv/mpv.conf`. ## Credits -- [Unman](https://github.com/unman/shaker/tree/main/multimedia) +* [Unman](https://github.com/unman/shaker/tree/main/multimedia) diff --git a/salt/mgmt/README.md b/salt/mgmt/README.md index 2c60b86..ca8d0a2 100644 --- a/salt/mgmt/README.md +++ b/salt/mgmt/README.md @@ -4,9 +4,9 @@ Management environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -16,7 +16,8 @@ of a qube or for Salt Management on DomUs. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable mgmt sudo qubesctl --targets=tpl-mgmt state.apply @@ -24,13 +25,16 @@ sudo qubesctl top.disable mgmt sudo qubesctl state.apply mgmt.prefs ``` -- State: +* State: + + ```sh sudo qubesctl state.apply mgmt.create sudo qubesctl --skip-dom0 --targets=tpl-mgmt state.apply mgmt.install sudo qubesctl state.apply mgmt.prefs ``` + ## Usage diff --git a/salt/mirage-builder/README.md b/salt/mirage-builder/README.md index b5d528f..3205a54 100644 --- a/salt/mirage-builder/README.md +++ b/salt/mirage-builder/README.md @@ -4,9 +4,9 @@ Mirage Builder environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -21,20 +21,24 @@ are done through the web interface, they have GitHub Web-Flow signature. This is the best verification we can get for Mirage Firewall. If you don't trust the hosting provider however, don't install this package. -- Top: +* Top: + ```sh sudo qubesctl top.enable mirage-builder sudo qubesctl --targets=tpl-mirage-builder,mirage-builder state.apply sudo qubesctl top.disable mirage-builder ``` -- State: +* State: + + ```sh sudo qubesctl state.apply mirage-builder.create sudo qubesctl --skip-dom0 --targets=tpl-mirage-builder state.apply mirage-builder.install sudo qubesctl --skip-dom0 --targets=mirage-builder state.apply mirage-builder.configure ``` + ## Usage @@ -46,6 +50,7 @@ source](https://github.com/mirage/qubes-mirage-firewall#build-from-source). If you plan to build without docker, the hooks and completion scripts are already being sourced by your shell profile. Because of this, when calling `opam-init`, use it together with the option `--no-setup`: + ```sh opam init --no-setup ``` diff --git a/salt/opentofu/README.md b/salt/opentofu/README.md index ca918df..44e504a 100644 --- a/salt/opentofu/README.md +++ b/salt/opentofu/README.md @@ -4,9 +4,9 @@ OpenTofu installation in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -15,19 +15,23 @@ of Terraform. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable opentofu sudo qubesctl --targets=tpl-opentofu state.apply sudo qubesctl top.disable opentofu ``` -- State: +* State: + + ```sh sudo qubesctl state.apply opentofu.create sudo qubesctl --skip-dom0 --targets=tpl-opentofu state.apply opentofu.install ``` + ## Usage diff --git a/salt/qubes-builder/README.md b/salt/qubes-builder/README.md index 66fbb5f..67ea60c 100644 --- a/salt/qubes-builder/README.md +++ b/salt/qubes-builder/README.md @@ -4,13 +4,14 @@ Setup Qubes OS Builder V2 in Qubes OS itself. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Access Control](#access-control) -* [Usage](#usage) - * [Pulling new commits](#pulling-new-commits) - * [Add PGP public key to qubes-builder GPG home directory](#add-pgp-public-key-to-qubes-builder-gpg-home-directory) - * [Builder configuration](#builder-configuration) +* [Description](#description) +* [Installation](#installation) +* [Access Control](#access-control) +* [Usage](#usage) + * [Pulling new commits](#pulling-new-commits) + * [Add PGP public key to qubes-builder GPG home directory](#add-pgp-public-key-to-qubes-builder-gpg-home-directory) + * [Builder configuration](#builder-configuration) + * [Build Qusal](#build-qusal) ## Description @@ -43,7 +44,8 @@ need to `reset` the user changes and to do a clean `pull` that wouldn't fail. After you've pulled the commit including the `.gitmodules` once, future installations won't have this issue. -- Top +* Top: + ```sh sudo qubesctl top.enable qubes-builder sudo qubesctl --targets=tpl-qubes-builder,dvm-qubes-builder,qubes-builder state.apply @@ -51,8 +53,10 @@ sudo qubesctl top.disable qubes-builder sudo qubesctl state.apply qubes-builder.prefs ``` -- State +* State: + + ```sh sudo qubesctl state.apply qubes-builder.create sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply qubes-builder.install @@ -60,15 +64,18 @@ sudo qubesctl state.apply qubes-builder.prefs sudo qubesctl --skip-dom0 --targets=dvm-qubes-builder state.apply qubes-builder.configure-qubes-executor sudo qubesctl --skip-dom0 --targets=qubes-builder state.apply qubes-builder.configure ``` + If you plan to write for a long time and analyze logs on the builder qube, it is recommended to install some development goodies: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply qubes-builder.install-dev ``` If you plan on building Qusal packages (Development only): + ```sh sudo qubesctl --skip-dom0 --targets=qubes-builder state.apply qubes-builder.configure-qusal ``` @@ -89,12 +96,14 @@ need to pull new commits from time to time, their signature will be automatically verified before merging them to your git index. Pull `qubes-builderv2` commits: + ```sh git pull ``` Initialize and merge submodules: -``` + +```sh git submodule update --init git submodule update --merge ``` @@ -103,6 +112,7 @@ git submodule update --merge If you need to pull commits signed by someone with a key not deployed by default, import their key to the GPG home directory of qubes-builder: + ```sh gpg-qubes-builder --import /path/to/key ``` @@ -111,6 +121,7 @@ gpg-qubes-builder --import /path/to/key When using the Qubes Executor, configure the `builder.yml` `dispvm` option to either `dom0` or `dvm-qubes-builder`: + ```yaml include: - example-configs/desired-config.yml @@ -123,6 +134,7 @@ executor: gpg-client: gpg ``` + Setting the Disposable VM to Dom0 works because it will use the `default_dispvm` preference of `qubes-builder`, which is `dvm-qubes-builder`. @@ -135,6 +147,7 @@ Setting the `gpg-client` explicitly to enforce the use of `split-gpg2`. You can easily build Qusal as a default configuration is provided. Place only the following in `builder.yml`: + ```yaml include: - ../qusal-builder/qusal.yml diff --git a/salt/reader/README.md b/salt/reader/README.md index 47f4a5e..4f1adb8 100644 --- a/salt/reader/README.md +++ b/salt/reader/README.md @@ -4,10 +4,10 @@ Reader environment as the default_dispvm in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) +* [Credits](#credits) ## Description @@ -18,7 +18,8 @@ necessary packages will be installed in the template. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable reader sudo qubesctl --targets=tpl-reader,dvm-reader state.apply @@ -26,14 +27,17 @@ sudo qubesctl top.disable reader sudo qubesctl state.apply reader.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply reader.create sudo qubesctl --skip-dom0 --targets=tpl-reader state.apply reader.install sudo qubesctl --skip-dom0 --targets=dvm-reader state.apply reader.configure sudo qubesctl state.apply reader.appmenus ``` + ## Usage @@ -49,4 +53,4 @@ you want before the disposable makes a connection. ## Credits -- [Unman](https://github.com/unman/shaker/tree/main/reader) +* [Unman](https://github.com/unman/shaker/tree/main/reader) diff --git a/salt/remmina/README.md b/salt/remmina/README.md index 7d9992b..cc4bd83 100644 --- a/salt/remmina/README.md +++ b/salt/remmina/README.md @@ -4,9 +4,9 @@ Remmina Remote Desktop Client in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -16,7 +16,8 @@ you prefer to use an app qube, a qube named "remmina" will also be created. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable remmina sudo qubesctl --targets=tpl-remmina state.apply @@ -24,13 +25,16 @@ sudo qubesctl top.disable remmina sudo qubesctl state.apply remmina.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply remmina.create sudo qubesctl --skip-dom0 --targets=tpl-remmina state.apply remmina.install sudo qubesctl state.apply remmina.appmenus ``` + ## Usage diff --git a/salt/signal/README.md b/salt/signal/README.md index 67b6361..6575e4c 100644 --- a/salt/signal/README.md +++ b/salt/signal/README.md @@ -4,9 +4,9 @@ Signal messaging app in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -14,7 +14,8 @@ Install Signal Desktop and creates an app qube named "signal". ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable signal sudo qubesctl --targets=tpl-signal,signal state.appply @@ -22,14 +23,17 @@ sudo qubesctl top.disable signal sudo qubesctl state.apply signal.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply signal.create sudo qubesctl --skip-dom0 --targets=tpl-signal state.apply signal.install sudo qubesctl --skip-dom0 --targets=signal state.apply signal.configure sudo qubesctl state.apply signal.appmenus ``` + ## Usage diff --git a/salt/ssh/README.md b/salt/ssh/README.md index 9539bbb..08b30e2 100644 --- a/salt/ssh/README.md +++ b/salt/ssh/README.md @@ -4,9 +4,9 @@ SSH remote login client in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -18,20 +18,24 @@ in as a one time connection or to an untrusted host use a DispVM based on ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable ssh sudo qubesctl --targets=tpl-ssh,dvm-ssh,ssh state.apply sudo qubesctl top.disable ssh ``` -- State: +* State: + + ```sh sudo qubesctl state.apply ssh.create sudo qubesctl --skip-dom0 --targets=tpl-ssh state.apply ssh.install sudo qubesctl --skip-dom0 --targets=dvm-ssh,ssh state.apply ssh.configure ``` + ## Usage @@ -42,7 +46,7 @@ preserving the SSH configuration client side. The client qube can enhanced by being: -- sys-ssh-agent's client and not storing the SSH keys on the client; or -- sys-git's client and fetching from qubes and push to remote servers. +* sys-ssh-agent's client and not storing the SSH keys on the client; or +* sys-git's client and fetching from qubes and push to remote servers. The server requires the OpenSSH server to be installed. diff --git a/salt/sys-audio/README.md b/salt/sys-audio/README.md index c8ee032..34ed6d7 100644 --- a/salt/sys-audio/README.md +++ b/salt/sys-audio/README.md @@ -4,17 +4,17 @@ Audio operations in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) - * [Audio control](#audio-control) - * [Client switched it's AudioVM](#client-switched-its-audiovm) - * [Client started before it's AudioVM](#client-started-before-its-audiovm) - * [Client turned off with a device attached](#client-turned-off-with-a-device-attached) - * [How to use USB devices](#how-to-use-usb-devices) - * [How to use Bluetooth](#how-to-use-bluetooth) - * [How to make the Bluetooth icon appear in the system tray](#how-to-make-the-bluetooth-icon-appear-in-the-system-tray) - * [How to attach the Bluetooth controller to the AudioVM persistently](#how-to-attach-the-bluetooth-controller-to-the-audiovm-persistently) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) + * [Audio control](#audio-control) + * [Client switched it's AudioVM](#client-switched-its-audiovm) + * [Client started before it's AudioVM](#client-started-before-its-audiovm) + * [Client turned off with a device attached](#client-turned-off-with-a-device-attached) + * [How to use USB devices](#how-to-use-usb-devices) + * [How to use Bluetooth](#how-to-use-bluetooth) + * [How to make the Bluetooth icon appear in the system tray](#how-to-make-the-bluetooth-icon-appear-in-the-system-tray) + * [How to attach the Bluetooth controller to the AudioVM persistently](#how-to-attach-the-bluetooth-controller-to-the-audiovm-persistently) ## Description @@ -25,28 +25,34 @@ the necessary packages for bluetooth with the provided state. ## Installation -- Top +* Top: + ```sh sudo qubesctl top.enable sys-audio sudo qubesctl --targets=tpl-sys-audio,dvm-sys-audio state.apply sudo qubesctl top.disable sys-audio ``` -- State +* State: + + ```sh sudo qubesctl state.apply sys-audio.create sudo qubesctl --skip-dom0 --targets=tpl-sys-audio state.apply sys-audio.install sudo qubesctl --skip-dom0 --targets=dvm-sys-audio state.apply sys-audio.configure-dvm ``` + If you want to autostart the AudioVM on boot, you may run: + ```sh sudo qubesctl state.apply sys-audio.autostart ``` If you need Bluetooth support, install the dependencies: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-sys-audio state.apply sys-audio.install-bluetooth ``` @@ -61,8 +67,8 @@ to control the volume via the volume icon that appears on the system tray. Audio control basics: -- Left click toggles the volume; and -- Scrolling the mouse from left to right changes the volume; +* Left click toggles the volume; and +* Scrolling the mouse from left to right changes the volume; For more advanced features, right click the icon and click on `Open Mixer` or `Prefences`. For greater control, use the command `amixer`. @@ -76,6 +82,7 @@ will need to restart the client qube until [upstream issue is fixed](https://git Audio will not automatically connect if the AudioVM starts after the client. To connect the client to audio server, restart the client's Pipewire service: + ```sh systemctl --user restart pipewire ``` @@ -86,9 +93,9 @@ If you shutdown a client qube with a device attached, such as a microphone or speaker, normal operation to attach the device to the same or any other qube will fail. To be able to use the device again: -- Restart the AudioVM `disp-sys-audio`; -- Restart the audio client; and -- Attach the device to the audio client. +* Restart the AudioVM `disp-sys-audio`; +* Restart the audio client; and +* Attach the device to the audio client. ### How to use USB devices @@ -117,22 +124,26 @@ controller from the USB qube to the Audio qube, but this would decrease your system security. First, start the qube holding the USB stack: + ```sh qvm-start disp-sys-usb ``` Identify you Bluetooth controller: -``` + +```sh qvm-usb list disp-sys-usb ``` If you haven't identified the device, run `lsusb` in the USB stack server: + ```sh qvm-run -p disp-sys-usb -- lsusb ``` Permanently attach the Bluetooth controller to the AudioVM (change `DEVID` for the one you identified above): + ```sh qvm-usb attach --persistent disp-sys-audio disp-sys-usb:DEVID ``` diff --git a/salt/sys-bitcoin/README.md b/salt/sys-bitcoin/README.md index af31acd..df4e3af 100644 --- a/salt/sys-bitcoin/README.md +++ b/salt/sys-bitcoin/README.md @@ -4,17 +4,17 @@ Bitcoin Core in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) - * [Custom daemon parameters](#custom-daemon-parameters) - * [Bitcoin Core GUI](#bitcoin-core-gui) - * [Connect to a remote Bitcoin RPC](#connect-to-a-remote-bitcoin-rpc) - * [Evaluation of remote Bitcoin RPC](#evaluation-of-remote-bitcoin-rpc) - * [Configure the remote node](#configure-the-remote-node) - * [Connect the qube to the remote node](#connect-the-qube-to-the-remote-node) - * [Database on external drive](#database-on-external-drive) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) + * [Custom daemon parameters](#custom-daemon-parameters) + * [Bitcoin Core GUI](#bitcoin-core-gui) + * [Connect to a remote Bitcoin RPC](#connect-to-a-remote-bitcoin-rpc) + * [Evaluation of remote Bitcoin RPC](#evaluation-of-remote-bitcoin-rpc) + * [Configure the remote node](#configure-the-remote-node) + * [Connect the qube to the remote node](#connect-the-qube-to-the-remote-node) + * [Database on external drive](#database-on-external-drive) +* [Credits](#credits) ## Description @@ -46,7 +46,8 @@ At least `1TB` of disk space is required. At block `829054` (2024-02-05), ## Installation -- Top +* Top: + ```sh sudo qubesctl top.enable sys-bitcoin sudo qubesctl --targets=sys-bitcoin-gateway,tpl-sys-bitcoin,disp-sys-bitcoin-builder,sys-bitcoin,bitcoin state.apply @@ -54,8 +55,10 @@ sudo qubesctl top.disable sys-bitcoin sudo qubesctl state.apply sys-bitcoin.appmenus ``` -- State +* State: + + ```sh sudo qubesctl state.apply sys-bitcoin.create sudo qubesctl --skip-dom0 --targets=sys-bitcoin-gateway state.apply sys-bitcoin.configure-gateway @@ -65,38 +68,41 @@ sudo qubesctl --skip-dom0 --targets=sys-bitcoin state.apply sys-bitcoin.configur sudo qubesctl --skip-dom0 --targets=bitcoin state.apply sys-bitcoin.configure-client sudo qubesctl state.apply sys-bitcoin.appmenus ``` + If you prefer to build from source (will take approximately 1 hour to build): + ```sh sudo qubesctl --skip-dom0 --targets=tpl-sys-bitcoin state.apply sys-bitcoin.install-source sudo qubesctl --skip-dom0 --targets=disp-bitcoin-builder state.apply sys-bitcoin.configure-builder-source ``` If you want to relay blocks (listening node): + ```sh sudo qubesctl --skip-dom0 --targets=sys-bitcoin-gateway state.apply sys-bitcoin.configure-gateway-listen sudo qubesctl --skip-dom0 --targets=sys-bitcoin state.apply sys-bitcoin.configure-listen ``` Add the tag `bitcoin-client` to the client and install in the client template: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-bitcoin.install-client ``` - ## Usage The qube `sys-bitcoin` can: -- Index the Bitcoin blockchain connecting to peers over Tor; -- Connect to a remote Bitcoin RPC reachable over Tor; and -- Broadcast transactions over Tor. +* Index the Bitcoin blockchain connecting to peers over Tor; +* Connect to a remote Bitcoin RPC reachable over Tor; and +* Broadcast transactions over Tor. The qube `bitcoin` can: -- Create wallet addresses; and -- Sign transactions. +* Create wallet addresses; and +* Sign transactions. ### Custom daemon parameters @@ -110,6 +116,7 @@ used to rescan old wallet and is incompatible to serve any Electrum Server. You can enable pruning in `/home/user/.bitcoin/conf.d/bitcoin.conf.local` by specifying how many `MiB` of block files to retain: + ```cfg prune=550 ``` @@ -119,6 +126,7 @@ reduce the used memory, as it is not necessary anymore to have a large cache. As the bitcoind option `dbcache` is dynamic allocated per the qube memory, you just need to reduce the memory available to the `sys-bitcoin` qube. From `dom0`, run: + ```sh qvm-prefs sys-bitcoin memory 1000 ``` @@ -137,22 +145,22 @@ interface for the Bitcoin Core Wallet. You may wish to connect to a remote Bitcoin node with RPC available to: -- Lower disk space usage and to lower resource consumption by not having - multiple Bitcoin blockchains; -- Avoid changing scripts and configurations that expect the connection to be - working on `127.0.0.1:8332`, such as the Qrexec policy for connecting - Bitcoind RPC to the Electrum Servers. +* Lower disk space usage and to lower resource consumption by not having + multiple Bitcoin blockchains; +* Avoid changing scripts and configurations that expect the connection to + be working on `127.0.0.1:8332`, such as the Qrexec policy for connecting + Bitcoind RPC to the Electrum Servers. But there are huge disadvantages to this method: -- [Bitcoin Core RPC does not have transport encryption](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.12.0.md#rpc-ssl-support-dropped). - Therefore, this method is advised against unless you know how to enable - transport encryption to connect to your Bitcoin RPC. If you run bitcoind on - `sys-bitcoin`, you do not have to worry about transport encryption as - communication is done securely via Qrexec. -- Bitcoin configuration cannot be changed remotely, therefore adding RPC - Authentication for clients such as Electrum Servers have to be done - manually. +* [Bitcoin Core RPC does not have transport encryption](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.12.0.md#rpc-ssl-support-dropped). + Therefore, this method is advised against unless you know how to enable + transport encryption to connect to your Bitcoin RPC. If you run bitcoind + on `sys-bitcoin`, you do not have to worry about transport encryption as + communication is done securely via Qrexec. +* Bitcoin configuration cannot be changed remotely, therefore adding RPC + Authentication for clients such as Electrum Servers have to be done + manually. The remote bitcoind setup is difficult to fit all user needs and requires you to change a remote node we have no control over the configuration, therefore, @@ -162,16 +170,17 @@ it is intended for advanced users only. On the remote node: -- You must set in the node's `bitcoin.conf`, the following options to bind to - the external interface: `rpcbind`, `bind` (Electrs), - `whitelist=download@` (ElectRS), `zmqpubhashblock` (Fulcrum) and allow - connections of the external IP of your upstream netvm via `rpcallowip`. -- Open the configured ports of the previous settings in the firewall to be - reachable by the Qubes system. -- Generate RPC credentials (see `bitcoin/share/rpcauth/rpcauth.py`), add - `rpcauth=` option to `bitcoin.conf` and save the `user` and `password` for - later. -- Restart bitcoind to apply the configuration changes. +* You must set in the node's `bitcoin.conf`, the following options to bind + to the external interface: `rpcbind`, `bind` (Electrs), + `whitelist=download@` (ElectRS), `zmqpubhashblock` (Fulcrum) and + allow connections of the external IP of your upstream netvm via + `rpcallowip`. +* Open the configured ports of the previous settings in the firewall to be + reachable by the Qubes system. +* Generate RPC credentials (see `bitcoin/share/rpcauth/rpcauth.py`), add + `rpcauth=` option to `bitcoin.conf` and save the `user` and `password` for + later. +* Restart bitcoind to apply the configuration changes. #### Connect the qube to the remote node @@ -186,6 +195,7 @@ P2P port `8333`, ZMQPUBHASHBLOCK port `8433`. In `dom0`, create the user Qrexec policy to target the qube `sys-net` in `/etc/qubes/policy.d/30-user.policy`: + ```qrexecpolicy ## Getting Auth doesn't work with remote node. qusal.BitcoinAuthGet * @anyvm @anyvm deny @@ -198,6 +208,7 @@ qubes.ConnectTCP * @tag:bitcoin-client @anyvm deny In the qube `sys-net`, add the `socat` command (only the ones you need) to the file `/rw/config/rc.local`: + ```sh ## RPC socat TCP-LISTEN:8332,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8332 & @@ -210,6 +221,7 @@ socat TCP-LISTEN:8433,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8433 & In the Electrum Server qubes or any Bitcoin Client, `sys-electrumx`, `sys-electrs`, `sys-fulcrum`, add the `qvm-connect-tcp` command to the file `/rw/config/rc.local`: + ```sh ## RPC qvm-connect-tcp ::8332 @@ -236,4 +248,4 @@ If you have done this, please share a guide. ## Credits -- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) +* [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) diff --git a/salt/sys-cacher/README.md b/salt/sys-cacher/README.md index 23783f2..df3df24 100644 --- a/salt/sys-cacher/README.md +++ b/salt/sys-cacher/README.md @@ -4,15 +4,15 @@ Caching proxy server for software repositories in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Access control](#access-control) -* [Usage](#usage) - * [Report Page and Maintenance Tasks](#report-page-and-maintenance-tasks) - * [Connect to the cacher via IP instead of Qrexec](#connect-to-the-cacher-via-ip-instead-of-qrexec) - * [Non-TemplateVMs integration](#non-templatevms-integration) -* [Uninstallation](#uninstallation) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Access control](#access-control) +* [Usage](#usage) + * [Report Page and Maintenance Tasks](#report-page-and-maintenance-tasks) + * [Connect to the cacher via IP instead of Qrexec](#connect-to-the-cacher-via-ip-instead-of-qrexec) + * [Non-TemplateVMs integration](#non-templatevms-integration) +* [Uninstallation](#uninstallation) +* [Credits](#credits) ## Description @@ -21,9 +21,9 @@ packages, so that you need only download a package once and fetch locally the next time you want to upgrade your system packages. When you install this package, qubes will be tagged with "updatevm-sys-cacher" -and they will be altered to use the proxy by default. When there is "https://" +and they will be altered to use the proxy by default. When there is in your repository definitions, the entries will be changed in the templates -from to "http://HTTPS///". This is so that the request to the proxy is plain +from to . This is so that the request to the proxy is plain text, and the proxy will then make the request via https. This change will be done automatically for every template that exists and is @@ -32,16 +32,17 @@ those templates will not be cached. The caching proxy supports: -- Debian and derivatives (but not Whonix) -- Fedora and derivatives -- Arch Linux and derivatives +* Debian and derivatives (but not Whonix) +* Fedora and derivatives +* Arch Linux and derivatives ## Installation Installation may take a long time as it will target all templates unless you specify otherwise. -- Top +* Top: + ```sh sudo qubesctl top.enable sys-cacher browser sudo qubesctl --targets=tpl-browser,sys-cacher-browser,tpl-sys-cacher,sys-cacher state.apply @@ -50,8 +51,10 @@ sudo qubesctl state.apply sys-cacher.appmenus,sys-cacher.tag sudo qubesctl --skip-dom0 --targets="$(qvm-ls --no-spinner --raw-list --tags updatevm-sys-cacher | tr "\n" ",")" state.apply sys-cacher.install-client ``` -- State +* State: + + ```sh sudo qubesctl state.apply sys-cacher.create sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install @@ -61,6 +64,7 @@ sudo qubesctl --skip-dom0 --targets=sys-cacher-browser state.apply sys-cacher.co sudo qubesctl state.apply sys-cacher.appmenus,sys-cacher.tag sudo qubesctl --skip-dom0 --targets="$(qvm-ls --no-spinner --raw-list --tags updatevm-sys-cacher | tr "\n" ",")" state.apply sys-cacher.install-client ``` + ## Access control @@ -72,6 +76,7 @@ can do so. Allow qubes with tag `whonix-updatevm` to use the proxy in `sys-alt-whonix` and qube `dev` to use the proxy in `disp-sys-net`. + ```qrexecpolicy qubes.UpdatesProxy * @tag:whonix-updatevm @default allow target=sys-alt-whonix qubes.UpdatesProxy * @tag:whonix-updatevm @anyvm deny @@ -95,9 +100,11 @@ and any other client qube that has `sys-cacher` as it's update qube. This is apt-cacher-ng limitation and is bad security wise, every client has administrative access to the cacher qube. You should add the following to the end of `sys-cacher` rc.local: + ```sh echo "AdminAuth: username:password" | tee /etc/qusal-apt-cacher-ng/zzz_security.conf ``` + Where username and password are HTTP Auth strings. ### Connect to the cacher via IP instead of Qrexec @@ -108,11 +115,13 @@ configuration to set the update proxy using the IP address of `sys-cacher` by setting `sys-cacher` as the netvm of the client qube. Set `sys-cacher` as the netvm of your qube: + ```sh qvm-prefs QUBE netvm sys-cacher ``` Enable the service `netvm-cacher`: + ```sh qvm-features QUBE service.netvm-cacher 1 ``` @@ -132,15 +141,18 @@ firewall and connect to a remote host via the updates proxy. By default, only templates will use the proxy to update, if you want to cache non-TemplateVMs updates or simply make them functional again, the qube will need the `service.updates-proxy-setup` feature set: + ```sh qvm-tags QUBE add updatevm-sys-cacher qvm-features QUBE service.updates-proxy-setup 1 sudo qubesctl --skip-dom0 --targets=QUBE state.apply sys-cacher.install-client ``` + Don't forget to restart the qube. If you don't want or can't restart the qube, such as DispVMs, where you would lose the current session: + ```sh qvm-tags QUBE add updatevm-sys-cacher qvm-features QUBE service.updates-proxy-setup 1 @@ -153,7 +165,8 @@ systemctl restart qubes-updates-proxy-forwarder.socket" ## Uninstallation -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-cacher.deinit sudo qubesctl --targets="$(qvm-ls --no-spinner --raw-list --tags updatevm-sys-cacher | tr "\n" ",")" state.apply @@ -161,7 +174,8 @@ sudo qubesctl top.disable sys-cacher.deinit sudo qubesctl state.apply sys-cacher.untag ``` -- State: +* State: + ```sh sudo qubesctl state.apply sys-cacher.remove-policy sudo qubesctl --skip-dom0 --targets="$(qvm-ls --no-spinner --raw-list --tags updatevm-sys-cacher | tr "\n" ",")" state.apply sys-cacher.uninstall-client @@ -170,6 +184,7 @@ sudo qubesctl state.apply sys-cacher.untag If you want to use the standard proxy for a few qubes, only uninstall it from the templates that you don't want to cache packages: + ```sh sudo qubesctl --skip-dom0 --targets=QUBE state.apply sys-cacher.uninstall-client qvm-tags QUBE del updatevm-sys-cacher @@ -178,10 +193,11 @@ qvm-tags QUBE del updatevm-sys-cacher If you tagged manually a qube that is unsupported, updates for that qube will fail. Get a full list of unsupported qubes (**warning**: there may be false positives of supported qubes being listed): + ```sh sudo qubesctl --show-output state.apply sys-cacher.list-extra-tag ``` ## Credits -- [Unman](https://github.com/unman/shaker/tree/main/cacher) +* [Unman](https://github.com/unman/shaker/tree/main/cacher) diff --git a/salt/sys-electrs/README.md b/salt/sys-electrs/README.md index a906bbc..31e91da 100644 --- a/salt/sys-electrs/README.md +++ b/salt/sys-electrs/README.md @@ -4,10 +4,10 @@ Electrs in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) +* [Credits](#credits) ## Description @@ -26,7 +26,8 @@ At least `200GB` of disk space is required. This formula depends on [sys-bitcoin](../sys-bitcoin/README.md). -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-electrs sudo qubesctl --targets=tpl-electrs-builder,tpl-sys-electrs,disp-electrs-builder,sys-electrs state.apply @@ -34,8 +35,10 @@ sudo qubesctl top.disable sys-electrs sudo qubesctl state.apply sys-electrs.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-electrs.create sudo qubesctl --skip-dom0 --targets=tpl-electrs-builder state.apply sys-electrs.install-builder @@ -44,6 +47,7 @@ sudo qubesctl --skip-dom0 --targets=disp-electrs-builder state.apply sys-electrs sudo qubesctl --skip-dom0 --targets=sys-electrs state.apply sys-electrs.configure sudo qubesctl state.apply sys-electrs.appmenus ``` + ## Usage @@ -58,4 +62,4 @@ file, else Electrs will fail to start. ## Credits -- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) +* [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) diff --git a/salt/sys-electrumx/README.md b/salt/sys-electrumx/README.md index b2c58f1..1ded5da 100644 --- a/salt/sys-electrumx/README.md +++ b/salt/sys-electrumx/README.md @@ -4,10 +4,10 @@ ElectrumX in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) +* [Credits](#credits) ## Description @@ -26,7 +26,8 @@ At least `200GB` of disk space is required. This formula depends on [sys-bitcoin](../sys-bitcoin/README.md). -- Top +* Top: + ```sh sudo qubesctl top.enable sys-electrumx sudo qubesctl --targets=tpl-electrumx-builder,tpl-sys-electrumx,disp-electrumx-builder,sys-electrumx state.apply @@ -34,8 +35,10 @@ sudo qubesctl top.disable sys-electrumx sudo qubesctl state.apply sys-electrumx.appmenus ``` -- State +* State: + + ```sh sudo qubesctl state.apply sys-electrumx.create sudo qubesctl --skip-dom0 --targets=tpl-electrumx-builder state.apply sys-electrumx.install-builder @@ -44,6 +47,7 @@ sudo qubesctl --skip-dom0 --targets=disp-electrumx-builder state.apply sys-elect sudo qubesctl --skip-dom0 --targets=sys-electrumx state.apply sys-electrumx.configure sudo qubesctl state.apply sys-electrumx.appmenus ``` + ## Usage @@ -61,4 +65,4 @@ ElectrumX server. ## Credits -- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) +* [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) diff --git a/salt/sys-firewall/README.md b/salt/sys-firewall/README.md index c683d61..d605cca 100644 --- a/salt/sys-firewall/README.md +++ b/salt/sys-firewall/README.md @@ -4,9 +4,9 @@ Firewall in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -28,7 +28,8 @@ using, such as Debian or Fedora. Before starting, turn on `sys-firewall-old` or yours `default_netvm` and check if DNS is working, after that, proceed with the installation. -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-firewall sudo qubesctl --targets=tpl-sys-firewall state.apply @@ -36,16 +37,20 @@ sudo qubesctl top.disable sys-firewall sudo qubesctl state.apply sys-firewall.prefs-disp ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-firewall.create sudo qubesctl --skip-dom0 --targets=tpl-sys-firewall state.apply sys-firewall.install sudo qubesctl state.apply sys-firewall.prefs-disp ``` + Alternatively, if you prefer to have an app qube as the firewall: + ```sh sudo qubesctl state.apply sys-firewall.prefs ``` diff --git a/salt/sys-git/README.md b/salt/sys-git/README.md index d54f5c8..3a2f7d0 100644 --- a/salt/sys-git/README.md +++ b/salt/sys-git/README.md @@ -4,15 +4,15 @@ Git operations through Qrexec in Qubes OS. ## Table of Contents -* [Description](#description) -* [Alternatives comparison](#alternatives-comparison) -* [Security](#security) -* [Installation](#installation) -* [Access control](#access-control) -* [Usage](#usage) - * [Initialize the server repository](#initialize-the-server-repository) - * [Prepare the client](#prepare-the-client) -* [Credits](#credits) +* [Description](#description) +* [Alternatives comparison](#alternatives-comparison) +* [Security](#security) +* [Installation](#installation) +* [Access control](#access-control) +* [Usage](#usage) + * [Initialize the server repository](#initialize-the-server-repository) + * [Prepare the client](#prepare-the-client) +* [Credits](#credits) ## Description @@ -26,9 +26,9 @@ and Init. This is an implementation of split-git. The following alternatives will be compared against each other and this implementation: -- [Rudd-O/git-remote-qubes](https://github.com/Rudd-O/git-remote-qubes) -- [QubesOS-contrib/qubes-app-split-git](https://github.com/QubesOS-contrib/qubes-app-split-git) -- [qubes-os.org/doc/development-workflow/#git-connection-between-vms](https://www.qubes-os.org/doc/development-workflow/#git-connection-between-vms) +* [Rudd-O/git-remote-qubes](https://github.com/Rudd-O/git-remote-qubes) +* [QubesOS-contrib/qubes-app-split-git](https://github.com/QubesOS-contrib/qubes-app-split-git) +* [qubes-os.org/doc/development-workflow/#git-connection-between-vms](https://www.qubes-os.org/doc/development-workflow/#git-connection-between-vms) | | sys-git | git-remote-qubes | qubes-app-split-git | git-connection-between-vms | | :--- | :---: | :---: | :---: | :---: | @@ -76,23 +76,28 @@ trust the origin, don't use it. ## Installation -- Top +* Top: + ```sh sudo qubesctl top.enable sys-git sudo qubesctl --targets=tpl-sys-git,sys-git state.apply sudo qubesctl top.disable sys-git ``` -- State +* State: + + ```sh sudo qubesctl state.apply sys-git.create sudo qubesctl --skip-dom0 --targets=tpl-sys-git state.apply sys-git.install sudo qubesctl --skip-dom0 --targets=sys-git state.apply sys-git.configure ``` + Installation on the client template: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-dev state.apply sys-git.install-client ``` @@ -104,12 +109,13 @@ it to `Fetch` from, `Push` to and `Init` on `sys-git`. __Recommended usage__: -- __Init__: Argument useful when allowing a qube to always create a - repository on the server. -- __Fetch__: Fetch can be allowed by less trusted qubes. -- __Push__: Push should only be made by trusted qubes. +* __Init__: Argument useful when allowing a qube to always create a +* repository on the server. +* __Fetch__: Fetch can be allowed by less trusted qubes. +* __Push__: Push should only be made by trusted qubes. Allow qube `dev` to `Fetch` from `sys-git`, but ask to `Push` and `Init`: + ```qrexecpolicy qusal.GitFetch * dev @default allow target=sys-git qusal.GitPush * dev @default ask target=sys-git default_target=sys-git @@ -121,6 +127,7 @@ qusal.GitInit * dev @anyvm deny Allow qube `untrusted` to `Fetch` `repo` if using target name `sys-git` but deny `Push` and `Init` to any other qube: + ```qrexecpolicy qusal.GitFetch +repo untrusted sys-git ask target=sys-git default_target=sys-git qusal.GitFetch * untrusted @anyvm deny @@ -129,6 +136,7 @@ qusal.GitInit * untrusted @anyvm deny ``` Deny `Fetch`, `Push` and `Init` from any qube to any other qube: + ```qrexecpolicy qusal.GitFetch * @anyvm @anyvm deny qusal.GitPush * @anyvm @anyvm deny @@ -141,19 +149,22 @@ qusal.GitInit * @anyvm @anyvm deny There are a few constraints regarding repositories: -- Must be created under `/home/user/src` in `sys-git`; -- Names must have only letters, numbers, hyphen, underscore and dot. Must not - begin or end with dot, hyphen and underscore. +* Must be created under `/home/user/src` in `sys-git`; +* Names must have only letters, numbers, hyphen, underscore and dot. Must + not begin or end with dot, hyphen and underscore. In `sys-git`, create bare repositories under `/home/user/src`. From the `server`: + ```sh git init --bare ~/src/X.git ``` + You must use the `.git` prefix to indicate a bare repository. Or from the `client`, if the `qusal.GitInit` policy allows: + ```sh cd ~/path/to/repo git init-qrexec @@ -167,22 +178,26 @@ token and the `` field is the name of the repository that exists on `sys-git` under `/home/user/src`. Clone an existing repository: + ```sh git clone qrexec://@default/qubes-doc ``` Or Initialize a new repository: + ```sh git init qubes-doc cd qubes-doc ``` Add a remote using the Qrexec protocol: + ```sh git remote add sg qrexec://@default/qubes-doc ``` Test fetching from the newly added remote: + ```sh git fetch sg ``` @@ -190,15 +205,17 @@ git fetch sg Make changes to the git repository as you normally would on any system. Push to the server and set it as the default upstream: + ```sh git push -u sg main ``` Following pushes will be simpler: + ```sh git push ``` ## Credits -- [Unman](https://github.com/unman/shaker/tree/main/git) +* [Unman](https://github.com/unman/shaker/tree/main/git) diff --git a/salt/sys-mirage-firewall/README.md b/salt/sys-mirage-firewall/README.md index 2623103..c11acaa 100644 --- a/salt/sys-mirage-firewall/README.md +++ b/salt/sys-mirage-firewall/README.md @@ -4,10 +4,10 @@ Mirage Firewall in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) +* [Credits](#credits) ## Description @@ -26,23 +26,28 @@ You can't use Mirage Firewall to be the updatevm, use another qube instead. We have built the Unikernel locally and verified that the upstream checksum and local checksum matched when comparing the same release. -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-mirage-firewall sudo qubesctl state.apply sudo qubesctl top.disable sys-mirage-firewall ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-mirage-firewall.create ``` + ## Usage Set qubes `netvm` to `disp-sys-mirage-firewall`: + ```sh qvm-prefs --set QUBE netvm disp-sys-mirage-firewall ``` @@ -50,12 +55,14 @@ qvm-prefs --set QUBE netvm disp-sys-mirage-firewall To test the firewall, apply rules with `qvm-firewall`. For monitoring, inspect the Unikernel console: + ```sh sudo xl console disp-sys-mirage-firewall ``` + Exit the console with `Ctrl-]`. ## Credits -- [Unman](https://github.com/unman/shaker/tree/main/mirage) -- [Thien Tran](https://privsec.dev/posts/qubes/firewalling-with-mirageos-on-qubes-os/) +* [Unman](https://github.com/unman/shaker/tree/main/mirage) +* [Thien Tran](https://privsec.dev/posts/qubes/firewalling-with-mirageos-on-qubes-os/) diff --git a/salt/sys-net/README.md b/salt/sys-net/README.md index 85a2b42..5352071 100644 --- a/salt/sys-net/README.md +++ b/salt/sys-net/README.md @@ -4,10 +4,10 @@ PCI handler of network devices in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Access control](#access-control) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Access control](#access-control) +* [Usage](#usage) ## Description @@ -30,7 +30,8 @@ back, just set `sys-net` template to the full template you are using, such as Debian or Fedora. Before starting, turn on the `default_netvm` and check if DNS is working, after that, proceed with the installation. -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-net sudo qubesctl --targets=tpl-sys-net state.apply @@ -38,21 +39,26 @@ sudo qubesctl top.disable sys-net sudo qubesctl state.apply sys-net.prefs-disp ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-net.create sudo qubesctl --skip-dom0 --targets=tpl-sys-net state.apply sys-net.install sudo qubesctl state.apply sys-net.prefs-disp ``` + If you need to debug a net qube, install some helper tools: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-sys-net state.apply sys-net.install-debug ``` If you prefer to have an app qube as the net qube: + ```sh sudo qubesctl state.apply sys-net.prefs ``` @@ -68,6 +74,7 @@ As every call is denied by default, you need to add rules to you Qrexec policy for a call to occur. Some examples are represented below. Qube `dev` can ask to connect to `github.com:22` from `disp-sys-net`: + ```qrexecpolicy qusal.ConnectTCP +github.com+22 dev @default ask target=disp-sys-net qusal.ConnectTCP * dev @anyvm deny diff --git a/salt/sys-pgp/README.md b/salt/sys-pgp/README.md index b1f8be6..fef191e 100644 --- a/salt/sys-pgp/README.md +++ b/salt/sys-pgp/README.md @@ -4,10 +4,10 @@ PGP operations through Qrexec in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Access Control](#access-control) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Access Control](#access-control) +* [Usage](#usage) ## Description @@ -17,7 +17,8 @@ and access to them is made from the client through Qrexec. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-pgp sudo qubesctl --targets=tpl-sys-pgp,sys-pgp state.apply @@ -25,22 +26,27 @@ sudo qubesctl top.disable sys-pgp sudo qubesctl state.apply sys-pgp.prefs ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-pgp.create sudo qubesctl --skip-dom0 --targets=tpl-sys-pgp state.apply sys-pgp.install sudo qubesctl --skip-dom0 --targets=sys-pgp state.apply sys-pgp.configure sudo qubesctl state.apply sys-pgp.prefs ``` + Install on the client template: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder,tpl-dev state.apply sys-pgp.install-client ``` The client qube requires the split GPG client service to be enabled: + ```sh qvm-features QUBE service.split-gpg2-client 1 ``` @@ -51,6 +57,7 @@ _Default policy_: `any qube` can `ask` via the `@default` target if you allow it to use split-gpg in `sys-pgp`. Allow the `work` qubes to access `sys-pgp`, but not other qubes: + ```qrexecpolicy qubes.Gpg2 * work sys-pgp ask default_target=sys-pgp qubes.Gpg2 * work @default ask target=sys-pgp default_target=sys-pgp @@ -66,11 +73,13 @@ Save your PGP keys to `sys-pgp`, using isolated GnuPG home directory per qube at `~/.gnupg/split-gpg/`. On `dom0`, enabled the service `split-gpg2-client` for the client qube `dev`: + ```sh qvm-features dev service.split-gpg2-client 1 ``` On the qube `sys-pgp`, generate or import keys for the client qube `dev`: + ```sh mkdir -p ~/.gnupg/split-gpg/dev gpg --homedir ~/.gnupg/split-gpg/dev --import /path/to/secret.key @@ -78,6 +87,7 @@ gpg --homedir ~/.gnupg/split-gpg/dev --list-secret-keys ``` On the qube `dev`, import the public part of your key: + ```sh gpg --import /path/to/public.key ``` diff --git a/salt/sys-pihole/README.md b/salt/sys-pihole/README.md index 4d3e474..5609e80 100644 --- a/salt/sys-pihole/README.md +++ b/salt/sys-pihole/README.md @@ -4,14 +4,14 @@ Pi-hole DNS Sinkhole in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) - * [Web interface](#web-interface) - * [Torified Pi-Hole](#torified-pi-hole) - * [Local DNS server](#local-dns-server) - * [DNS issues after netvm restart](#dns-issues-after-netvm-restart) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) + * [Web interface](#web-interface) + * [Torified Pi-Hole](#torified-pi-hole) + * [Local DNS server](#local-dns-server) + * [DNS issues after netvm restart](#dns-issues-after-netvm-restart) +* [Credits](#credits) ## Description @@ -31,7 +31,8 @@ through the web interface, they have GitHub Web-Flow signature. This is the best verification we can get for Pi-Hole. If you don't trust the hosting provider however, don't install this package. -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-pihole browser sudo qubesctl --targets=tpl-browser,sys-pihole-browser,sys-pihole state.apply @@ -39,8 +40,10 @@ sudo qubesctl top.disable sys-pihole browser sudo qubesctl state.apply sys-pihole.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-pihole.create sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install @@ -48,11 +51,13 @@ sudo qubesctl --skip-dom0 --targets=sys-pihole state.apply sys-pihole.install sudo qubesctl --skip-dom0 --targets=sys-pihole-browser state.apply sys-pihole.configure-browser sudo qubesctl state.apply sys-pihole.appmenus ``` + If you want to change the global preferences `updatevm` and `default_netvm` and the per-qube preference `netvm` of all qubes from `sys-firewall` to `sys-pihole`, run: + ```sh sudo qubesctl state.apply sys-pihole.prefs ``` @@ -68,21 +73,22 @@ redirected to `sys-pihole-browser`. Pi-hole will be installed with the following settings: -- The DNS provider is Quad9 (filtered, DNSSEC) -- Steven Black's Unified Hosts List is included -- Query logging is enabled to show everything. +* The DNS provider is Quad9 (filtered, DNSSEC) +* Steven Black's Unified Hosts List is included +* Query logging is enabled to show everything. ### Torified Pi-Hole If you want to combine Pi-Hole with Tor, then you should reconfigure your netvm chaining (will break tor's client stream isolation) as such: -- qube -> sys-pihole -> Tor-gateway -> sys-firewall -> sys-net +* qube -> sys-pihole -> Tor-gateway -> sys-firewall -> sys-net ### Local DNS server If you want sys-pihole to use itself to resolve DNS queries, enable the service `local-dns-server` from Dom0 to sys-pihole: + ```sh qvm-features sys-pihole service.local-dns-server 1 ``` @@ -96,11 +102,12 @@ internet for updates, syncing time etc. If you encounter problems with DNS after having upstream netvm route changes, restart Pi-hole DNS from sys-pihole: + ```sh pihole restartdns ``` ## Credits -- [Patrizio Tufarolo](https://blog.tufarolo.eu/how-to-configure-pihole-in-qubesos-proxyvm/) -- [Unman](https://github.com/unman/shaker/tree/main/pihole) +* [Patrizio Tufarolo](https://blog.tufarolo.eu/how-to-configure-pihole-in-qubesos-proxyvm/) +* [Unman](https://github.com/unman/shaker/tree/main/pihole) diff --git a/salt/sys-print/README.md b/salt/sys-print/README.md index 21f3bff..71bae89 100644 --- a/salt/sys-print/README.md +++ b/salt/sys-print/README.md @@ -4,14 +4,14 @@ Printer environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Security](#security) -* [Installation](#installation) -* [Access Control](#access-control) -* [Usage](#usage) - * [Add a printer](#add-a-printer) - * [Print](#print) -* [Credits](#credits) +* [Description](#description) +* [Security](#security) +* [Installation](#installation) +* [Access Control](#access-control) +* [Usage](#usage) + * [Add a printer](#add-a-printer) + * [Print](#print) +* [Credits](#credits) ## Description @@ -40,7 +40,8 @@ qube that has access to the printer. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-print sudo qubesctl --targets=tpl-sys-print state.apply @@ -48,26 +49,32 @@ sudo qubesctl top.disable sys-print sudo qubesctl state.apply sys-print.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-print.create sudo qubesctl --skip-dom0 --targets=tpl-sys-print state.apply sys-print.install sudo qubesctl state.apply sys-print.appmenus ``` + If you want to install all printer drivers: + ```sh sudo qubesctl --skip-dom0 --targets=tpl-sys-print state.apply sys-print.install-driver-all ``` On the client template: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-print.install-client ``` The client qube requires the split Print service to be enabled: + ```sh qvm-features QUBE service.print-client 1 ``` @@ -76,21 +83,23 @@ qvm-features QUBE service.print-client 1 **_Default policy_** (qusal.Print RPC service): -- Clients with tag `print-client` are `allowed` to call servers with tag - `print-server`, defaulting to `sys-print`. -- `All` clients can `ask` servers with tag `print-server`, defaulting to - `sys-print`. +* Clients with tag `print-client` are `allowed` to call servers with tag + `print-server`, defaulting to `sys-print`. +* `All` clients can `ask` servers with tag `print-server`, defaulting to + `sys-print`. `Asking` can spawn multiple requests depending on the client, usage of `allow` is recommended for trusted clients. Add the tag `print-client` to the qube requesting the print content: + ```sh qvm-tags QUBE add print-client ``` As the call will default to `sys-print`, you can enforce the use of `disp-sys-print` via policy and not any other qube: + ```qrexecpolicy qusal.Print * @tag:print-client @default allow target=disp-sys-print qusal.Print * @tag:print-client @anyvm deny @@ -105,6 +114,7 @@ connect over the network or USB. If you do not want to save printing configuration, use `disp-sys-print`. On `sys-print` or `disp-sys-print`, add your printer: + ```sh system-config-printer ``` @@ -116,4 +126,4 @@ browser and target the desired printer. ## Credits -- [Unman](https://github.com/unman/shaker/tree/main/sys-print) +* [Unman](https://github.com/unman/shaker/tree/main/sys-print) diff --git a/salt/sys-rsync/README.md b/salt/sys-rsync/README.md index e043b6e..526ee80 100644 --- a/salt/sys-rsync/README.md +++ b/salt/sys-rsync/README.md @@ -4,13 +4,13 @@ Rsync over Qrexec in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Access Control](#access-control) -* [Usage](#usage) - * [Server](#server) - * [Client](#client) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Access Control](#access-control) +* [Usage](#usage) + * [Server](#server) + * [Client](#client) +* [Credits](#credits) ## Description @@ -26,29 +26,35 @@ the user. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-rsync sudo qubesctl --targets=tpl-sys-rsync,sys-rsync state.apply sudo qubesctl top.disable sys-rsync ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-rsync.create sudo qubesctl --skip-dom0 --targets=tpl-sys-rsync state.apply sys-rsync.install sudo qubesctl --skip-dom0 --targets=sys-rsync state.apply sys-rsync.configure ``` + Install on the client template: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-rsync.install-client ``` The client qube requires the Rsync forwarder service to be enabled: -``` + +```sh qvm-features QUBE service.rsync-client 1 ``` @@ -60,6 +66,7 @@ default policy `asks` if you want to connect with the `sys-rsync` qube. If you want to `allow` Rsync between qubes, insert in you user policy file `/etc/qubes/policy.d/30-user.policy` to allow the service using the following format: + ```qrexecpolicy qusal.Rsync * SOURCE @default allow target=TARGET ``` @@ -88,15 +95,17 @@ folders on each server qube. The Rsync connection is available with the socket `localhost:1839`. Rsync the server `shared` read/write directory: + ```sh rsync --port=1839 localhost::shared /LOCAL/PATH/TO/RSYNC ``` Rsync the server `archive` read-only directory: + ```sh rsync --port=1839 localhost::archive /LOCAL/PATH/TO/RSYNC ``` ## Credits -- [Unman](https://github.com/unman/qubes-sync) +* [Unman](https://github.com/unman/qubes-sync) diff --git a/salt/sys-ssh-agent/README.md b/salt/sys-ssh-agent/README.md index 54ed6b6..8acd9f9 100644 --- a/salt/sys-ssh-agent/README.md +++ b/salt/sys-ssh-agent/README.md @@ -4,21 +4,21 @@ SSH Agent through Qrexec in Qubes OS. ## Table of Contents -* [Description](#description) -* [Security](#security) -* [Installation](#installation) -* [Access Control](#access-control) -* [Usage](#usage) - * [Server](#server) - * [Generate keys](#generate-keys) - * [Limit key usage](#limit-key-usage) - * [Reload agent](#reload-agent) - * [Debug Agent side](#debug-agent-side) - * [Client](#client) - * [Enable and Start the service](#enable-and-start-the-service) - * [Single agent per client](#single-agent-per-client) - * [Multiple agents per client](#multiple-agents-per-client) -* [Credits](#credits) +* [Description](#description) +* [Security](#security) +* [Installation](#installation) +* [Access Control](#access-control) +* [Usage](#usage) + * [Server](#server) + * [Generate keys](#generate-keys) + * [Limit key usage](#limit-key-usage) + * [Reload agent](#reload-agent) + * [Debug Agent side](#debug-agent-side) + * [Client](#client) + * [Enable and Start the service](#enable-and-start-the-service) + * [Single agent per client](#single-agent-per-client) + * [Multiple agents per client](#multiple-agents-per-client) +* [Credits](#credits) ## Description @@ -46,29 +46,34 @@ to. A rogue client has full control of the allowed agent, therefore it can: -1. Use the keys for as long as the client runs; -2. Lock the agent with `ssh-add -X`; and -3. Delete keys from memory by issuing `ssh-add -D` +1. Use the keys for as long as the client runs; +2. Lock the agent with `ssh-add -X`; and +3. Delete keys from memory by issuing `ssh-add -D` ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-ssh-agent sudo qubesctl --targets=tpl-sys-ssh-agent,sys-ssh-agent state.apply sudo qubesctl top.disable sys-ssh-agent ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-ssh-agent.create sudo qubesctl --skip-dom0 --targets=tpl-sys-ssh-agent state.apply sys-ssh-agent.install sudo qubesctl --skip-dom0 --targets=sys-ssh-agent state.apply sys-ssh-agent.configure ``` + Installation on the client template: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-ssh-agent.install-client ``` @@ -82,6 +87,7 @@ As the default policy does not configure any allow rule, you are responsible for doing so. Allow access to the specified agent based on the qube tag: + ```qrexecpolicy qusal.SshAgent +work @tag:work @default allow target=sys-ssh-agent qusal.SshAgent +work @anyvm @anyvm deny @@ -90,18 +96,22 @@ qusal.SshAgent +personal @anyvm @anyvm deny ``` Ask access from `untrusted` qubes to the untrusted agent: + ```qrexecpolicy qusal.SshAgent +untrusted untrusted @default ask target=sys-ssh-agent default_target=sys-ssh-agent qusal.SshAgent +untrusted @anyvm @anyvm deny ``` -Ask access from `trusted` to use the agent `trusted` on the alternative qube agent named `sys-ssh-agent-trusted`: +Ask access from `trusted` to use the agent `trusted` on the alternative qube +agent named `sys-ssh-agent-trusted`: + ```qrexecpolicy qusal.SshAgent +trusted trusted @default ask target=sys-ssh-agent-trusted default_target=sys-ssh-agent-trusted qusal.SshAgent +trusted @anyvm @anyvm deny ``` Always recommended to end with an explicit deny rule: + ```qrexecpolicy qusal.SshAgent * @anyvm @anyvm deny ``` @@ -119,12 +129,14 @@ directory should have the same name as the agent itself. Example: Import preexisting keys to the agent directory or generate keys for a specific agent: + ```sh mkdir -m 0700 -p ~/.ssh/identities.d/ ssh-keygen -t ed25519 -f ~/.ssh/identities.d//id_example ``` You would do the following for the `work` agent: + ```sh mkdir -m 0700 -p ~/.ssh/identities.d/work ssh-keygen -t ed25519 -f ~/.ssh/identities.d/work/id_example @@ -139,6 +151,7 @@ You can set custom options by writing them to a file on the same path of the private key, but ending with the suffix `.ssh-add-option`. If the key is named `id_ed25519`, the option file should be named `id_ed25519.ssh-add-option`. The `.ssh-add-option` file has the following format: + ```sh # id_ed25519.ssh-add-option -q -t 600 @@ -149,6 +162,7 @@ The `.ssh-add-option` file has the following format: Or you can manually add the key to the agent which are not located under the `~/.ssh/identities.d` directory so they aren't automatically added (substitute AGENT, SECS, and LIFE for their appropriate values): + ```sh SSH_AUTH_SOCK="/run/user/1000/qusal-ssh-agent/.sock" ssh-add -t -f ``` @@ -158,6 +172,7 @@ SSH_AUTH_SOCK="/run/user/1000/qusal-ssh-agent/.sock" ssh-add -t -f The keys are added to the agent on the first call to that specific agent. If you have added keys to the correct agent directory but haven't rebooted yet, you will have to add the keys by executing: + ```sh qvm-ssh-agent reload qvm-ssh-agent reload work @@ -166,6 +181,7 @@ qvm-ssh-agent reload work #### Debug Agent side You can list agents and their keys with: + ```sh qvm-ssh-agent ls ``` @@ -176,16 +192,19 @@ qvm-ssh-agent ls Enable and start the connection to the SSH Agent via Qrexec for specified ``: + ```sh sudo systemctl --no-block restart qusal-ssh-agent-forwarder@.service sudo systemctl --no-block restart qusal-ssh-agent-forwarder@personal.service ``` + You can start the service on boot if you place the above line `/rw/config/rc.local` of the client. The ssh-agent socket will be at `/tmp/qusal-ssh-agent-forwarder/.sock`. You can test the connection is working with: + ```sh SSH_AUTH_SOCK="/tmp/qusal-ssh-agent-forwarder/personal.sock" ssh-add -l ``` @@ -195,6 +214,7 @@ SSH_AUTH_SOCK="/tmp/qusal-ssh-agent-forwarder/personal.sock" ssh-add -l You might want to set the `SSH_AUTH_SOCK` and `SSH_AGENT_PID` environment variables to point to the `work` agent so every connection will use the same agent: + ```sh echo 'export SSH_AUTH_SOCK=/tmp/qusal-ssh-agent-forwarder/work.sock; SSH_AGENT_PID="$(pgrep -f "/tmp/qusal-ssh-agent-forwarder/work.sock")"; @@ -209,11 +229,14 @@ different agent is not an alternative. Instead, use SSH client native method, the `IdentityAgent` option. You can control the SSH agent via SSH command-line option: + ```sh ssh -o IdentityAgent=/tmp/qusal-ssh-agent-forwarder/personal.sock personal-site.com ssh -o IdentityAgent=/tmp/qusal-ssh-agent-forwarder/work.sock work-site.com ``` + You can control the SSH agent via SSH configuration: + ```sshconfig Host personal IdentityAgent /tmp/qusal-ssh-agent-forwarder/personal.sock @@ -225,4 +248,4 @@ Host work ## Credits -- [Unman](https://github.com/unman/qusal-ssh-agent) +* [Unman](https://github.com/unman/qusal-ssh-agent) diff --git a/salt/sys-ssh/README.md b/salt/sys-ssh/README.md index f066236..48e7c50 100644 --- a/salt/sys-ssh/README.md +++ b/salt/sys-ssh/README.md @@ -4,13 +4,13 @@ SSH over Qrexec in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Access Control](#access-control) -* [Usage](#usage) - * [Server](#server) - * [Client](#client) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Access Control](#access-control) +* [Usage](#usage) + * [Server](#server) + * [Client](#client) +* [Credits](#credits) ## Description @@ -27,28 +27,34 @@ server qube directly. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-ssh sudo qubesctl --targets=tpl-sys-ssh,sys-ssh state.apply sudo qubesctl top.disable sys-ssh ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-ssh.create sudo qubesctl --skip-dom0 --targets=tpl-sys-ssh state.apply sys-ssh.install ``` + Install on the client template: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-ssh.install-client ``` The client qube requires the SSH forwarder service to be enabled: -``` + +```sh qvm-features QUBE service.ssh-client 1 ``` @@ -60,6 +66,7 @@ policy `asks` if you want to connect with the `sys-ssh` qube. If you want to `allow` SSH between qubes, insert in you user policy file `/etc/qubes/policy.d/30-user.policy` to allow the service using the following format: + ```qrexecpolicy qusal.Ssh * SOURCE @default allow target=TARGET ``` @@ -85,6 +92,7 @@ The SSH connection is available with the socket `localhost:1840`. From the client, mount the server `/home/user` directory as a SSH File System in the client `/home/user/sshfs` directory: + ```sh mkdir ~/sshfs sshfs -p 1840 localhost:/home/user /home/user/sshfs @@ -92,4 +100,4 @@ sshfs -p 1840 localhost:/home/user /home/user/sshfs ## Credits -- [Unman](https://github.com/unman/qubes-sync) +* [Unman](https://github.com/unman/qubes-sync) diff --git a/salt/sys-syncthing/README.md b/salt/sys-syncthing/README.md index b10761d..1de4d50 100644 --- a/salt/sys-syncthing/README.md +++ b/salt/sys-syncthing/README.md @@ -4,13 +4,13 @@ Syncthing through Qrexec in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Access Control](#access-control) -* [Usage](#usage) -* [Debugging](#debugging) -* [Uninstallation](#uninstallation) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Access Control](#access-control) +* [Usage](#usage) +* [Debugging](#debugging) +* [Uninstallation](#uninstallation) +* [Credits](#credits) ## Description @@ -23,7 +23,8 @@ accessible externally. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-syncthing browser sudo qubesctl --targets=tpl-browser,sys-syncthing-browser,tpl-sys-syncthing,sys-syncthing state.apply @@ -33,8 +34,10 @@ qvm-port-forward -a add -q sys-syncthing -n tcp -p 22000 qvm-port-forward -a add -q sys-syncthing -n udp -p 22000 ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-syncthing.create sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install @@ -45,15 +48,18 @@ sudo qubesctl state.apply sys-syncthing.appmenus qvm-port-forward -a add -q sys-syncthing -n tcp -p 22000 qvm-port-forward -a add -q sys-syncthing -n udp -p 22000 ``` + Install Syncthing on the client template: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-syncthing.install-client ``` The client qube requires the split Syncthing and the Syncthing Daemon service to be enabled: + ```sh qvm-features QUBE service.syncthing-client 1 qvm-features QUBE service.syncthing-server 1 @@ -68,6 +74,7 @@ qube. If you want to `allow` Syncthing between qubes, insert in you user policy file `/etc/qubes/policy.d/30-user.policy` to allow the service using the following format: + ```qrexecpolicy qusal.Syncthing * SOURCE @default allow target=DESTINATION default_target=DEFAULT_DESTINATION ``` @@ -93,12 +100,14 @@ traversal`, `Local Discovery`, `Global Discovery`, and `Enable Relaying` If sys-net has more than one network card the first external interface will be used by default. If this is incorrect, you must change it manually. In Dom0 run: + ```sh qvm-port-forward -a del -q sys-syncthing -n udp -p 22000 qvm-port-forward -a del -q sys-syncthing -n tcp -p 22000 qvm-port-forward -a add -q sys-syncthing -n udp -p 22000 qvm-port-forward -a add -q sys-syncthing -n tcp -p 22000 ``` + This will let you choose the NIC. ## Uninstallation @@ -110,14 +119,17 @@ must manually revert them. The Qrexec policy will be reverted to stop Syncthing between qubes. Uninstallation procedure: + + ```sh qvm-port-forward -a del -q sys-syncthing -n tcp -p 22000 qvm-port-forward -a del -q sys-syncthing -n udp -p 22000 sudo qubesctl state.apply sys-syncthing.clean ``` + ## Credits -- [Unman](https://github.com/unman/shaker/tree/main/syncthing) +* [Unman](https://github.com/unman/shaker/tree/main/syncthing) diff --git a/salt/sys-usb/README.md b/salt/sys-usb/README.md index f095ffc..b9a6f15 100644 --- a/salt/sys-usb/README.md +++ b/salt/sys-usb/README.md @@ -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: + + ```sh sudo qubesctl state.apply sys-usb.create sudo qubesctl --skip-dom0 --targets=tpl-sys-usb state.apply sys-usb.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) diff --git a/salt/sys-wireguard/README.md b/salt/sys-wireguard/README.md index 8e29d0e..03e72fe 100644 --- a/salt/sys-wireguard/README.md +++ b/salt/sys-wireguard/README.md @@ -4,10 +4,10 @@ Wireguard VPN in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) -* [Credits](#credits) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) +* [Credits](#credits) ## Description @@ -16,20 +16,24 @@ other qubes through the VPN with fail closed mechanism. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable sys-wireguard sudo qubesctl --targets=tpl-sys-wireguard,sys-wireguard state.apply sudo qubesctl top.disable sys-wireguard ``` -- State: +* State: + + ```sh sudo qubesctl state.apply sys-wireguard.create sudo qubesctl --skip-dom0 --targets=tpl-sys-wireguard state.apply sys-wireguard.install sudo qubesctl --skip-dom0 --targets=sys-wireguard state.apply sys-wireguard.configure ``` + ## Usage @@ -39,10 +43,10 @@ from clients connected to the VPN with a fail safe mechanism. To start using the VPN: -1. Copy the Wireguard configuration you downloaded to `sys-wireguard` and - place it in `/home/user/wireguard.conf`. -2. Run from Dom0 to apply Qubes Firewall rules: `qvm-wireguard` +1. Copy the Wireguard configuration you downloaded to `sys-wireguard` and + place it in `/home/user/wireguard.conf`. +2. Run from Dom0 to apply Qubes Firewall rules: `qvm-wireguard` ## Credits -- [Unman](https://github.com/unman/shaker/tree/main/mullvad) +* [Unman](https://github.com/unman/shaker/tree/main/mullvad) diff --git a/salt/terraform/README.md b/salt/terraform/README.md index 07d3a40..2e6fc46 100644 --- a/salt/terraform/README.md +++ b/salt/terraform/README.md @@ -4,9 +4,9 @@ Terraform installation in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -14,19 +14,23 @@ Install Terraform and use it on the "terraform" app qube. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable terraform sudo qubesctl --targets=tpl-terraform state.apply sudo qubesctl top.disable terraform ``` -- State: +* State: + + ```sh sudo qubesctl state.apply terraform.create sudo qubesctl --skip-dom0 --targets=tpl-terraform state.apply terraform.install ``` + ## Usage diff --git a/salt/usb/README.md b/salt/usb/README.md index 19d35cc..b7d792f 100644 --- a/salt/usb/README.md +++ b/salt/usb/README.md @@ -4,9 +4,9 @@ USB client in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -15,19 +15,23 @@ you can base disposable qubes, geared towards USB client usage. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable usb sudo qubesctl --targets=tpl-usb state.apply sudo qubesctl top.disable usb ``` -- State: +* State: + + ```sh sudo qubesctl state.apply usb.create sudo qubesctl --skip-dom0 --targets=tpl-usb state.apply usb.install ``` + ## Usage diff --git a/salt/utils/README.md b/salt/utils/README.md index b8b3ad7..ece0dca 100644 --- a/salt/utils/README.md +++ b/salt/utils/README.md @@ -4,8 +4,8 @@ Utilities library for Qusal. ## Table of Contents -* [Description](#description) -* [Usage](#usage) +* [Description](#description) +* [Usage](#usage) ## Description diff --git a/salt/utils/tools/builder/README.md b/salt/utils/tools/builder/README.md index c038599..f8ff67d 100644 --- a/salt/utils/tools/builder/README.md +++ b/salt/utils/tools/builder/README.md @@ -4,9 +4,9 @@ Build tools for packaging in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -16,10 +16,13 @@ building packages in UNIX distributions. ## Installation Install builder tools on templates: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS state.apply utils.tools.builder.core ``` + Install documentation tools on templates: + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS state.apply utils.tools.builder.doc ``` diff --git a/salt/utils/tools/zsh/README.md b/salt/utils/tools/zsh/README.md index 2aa5380..b95c9cc 100644 --- a/salt/utils/tools/zsh/README.md +++ b/salt/utils/tools/zsh/README.md @@ -4,9 +4,9 @@ Zsh environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -15,19 +15,23 @@ warnings. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable utils.tools.zsh sudo qubesctl --targets=TARGET state.apply sudo qubesctl top.disable utils.tools.zsh ``` -- State: +* State: + + ```sh sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS state.apply utils.tools.zsh.change-shell sudo qubesctl --skip-dom0 --targets=APPVMS state.apply utils.tools.zsh.touch-zshrc ``` + ## Usage diff --git a/salt/vault/README.md b/salt/vault/README.md index a7f817e..9a2a005 100644 --- a/salt/vault/README.md +++ b/salt/vault/README.md @@ -4,9 +4,9 @@ Vault environment in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -16,7 +16,8 @@ keys. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable vault sudo qubesctl --targets=tpl-vault state.apply @@ -24,13 +25,16 @@ sudo qubesctl top.disable vault sudo qubesctl state.apply vault.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply vault.create sudo qubesctl --skip-dom0 --targets=tpl-vault state.apply vault.install sudo qubesctl state.apply vault.appmenus ``` + ## Usage diff --git a/salt/video-companion/README.md b/salt/video-companion/README.md index 9c1cd9d..a3cf229 100644 --- a/salt/video-companion/README.md +++ b/salt/video-companion/README.md @@ -4,9 +4,9 @@ Stream webcams and share screens in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -16,32 +16,38 @@ access them without compromising the domains. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable video-companion sudo qubesctl state.apply sudo qubesctl top.disable video-companion ``` -- State: +* State: + + ```sh sudo qubesctl state.apply video-companion.create ``` + - Installation on the server (sender) template: + ```sh sudo qubesctl --skip-dom0 --targets=QUBE state.apply video-companion.install-sender ``` Installation on the client (receiver) template: + ```sh sudo qubesctl --skip-dom0 --targets=QUBE state.apply video-companion.install-receiver ``` Installation for debugging on the client (receiver) template: + ```sh sudo qubesctl --skip-dom0 --targets=QUBE state.apply video-companion.install-receiver-debug ``` @@ -54,17 +60,20 @@ The receiver the is client that requests access to the screen of webcam, therefore the client is responsible to initiate the call. On the client, to get the screen of another qube: + ```sh qubes-video-companion screenshare ``` On the client, to get the webcam of another qube: + ```sh qubes-video-companion webcam ``` On the client, if you installed the debug utilities, call cheese to access the shared screen or webcam: + ```sh cheese ``` diff --git a/salt/whonix-gateway/README.md b/salt/whonix-gateway/README.md index 1937250..987872a 100644 --- a/salt/whonix-gateway/README.md +++ b/salt/whonix-gateway/README.md @@ -4,9 +4,9 @@ Whonix Gateway Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -15,7 +15,8 @@ it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable whonix-gateway sudo qubesctl --targets=whonix-gateway-17 state.apply @@ -23,13 +24,16 @@ sudo qubesctl top.disable whonix-gateway sudo qubesctl state.apply whonix-gateway.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply whonix-gateway.create sudo qubesctl --skip-dom0 --targets=whonix-gateway-17 state.apply whonix-gateway.install sudo qubesctl state.apply whonix-gateway.appmenus ``` + ## Usage diff --git a/salt/whonix-workstation/README.md b/salt/whonix-workstation/README.md index e130925..82d9149 100644 --- a/salt/whonix-workstation/README.md +++ b/salt/whonix-workstation/README.md @@ -4,9 +4,9 @@ Whonix Workstation Template in Qubes OS. ## Table of Contents -* [Description](#description) -* [Installation](#installation) -* [Usage](#usage) +* [Description](#description) +* [Installation](#installation) +* [Usage](#usage) ## Description @@ -15,7 +15,8 @@ based on it. ## Installation -- Top: +* Top: + ```sh sudo qubesctl top.enable whonix-workstation sudo qubesctl --targets=whonix-workstation-17 state.apply @@ -23,13 +24,16 @@ sudo qubesctl top.disable whonix-workstation sudo qubesctl state.apply whonix-workstation.appmenus ``` -- State: +* State: + + ```sh sudo qubesctl state.apply whonix-workstation.create sudo qubesctl --skip-dom0 --targets=whonix-workstation-17 state.apply whonix-workstation.install sudo qubesctl state.apply whonix-workstation.appmenus ``` + ## Usage diff --git a/scripts/markdown-lint.sh b/scripts/markdown-lint.sh new file mode 100755 index 0000000..e33f09a --- /dev/null +++ b/scripts/markdown-lint.sh @@ -0,0 +1,41 @@ +#!/bin/sh + +## SPDX-FileCopyrightText: 2024 Benjamin Grande M. S. +## +## SPDX-License-Identifier: AGPL-3.0-or-later + +# shellcheck disable=SC2086 +set -eu + +command -v git >/dev/null || + { printf "Missing program: git\n" >&2; exit 1; } +cd "$(git rev-parse --show-toplevel)" || exit 1 +./scripts/requires-program.sh mdl + +find_tool="find" +if command -v fd; then + find_tool="fd" +elif command -v fdfind >/dev/null; then + find_tool="fdfind" +fi + +if test -n "${1-}"; then + files="" + for f in "$@"; do + test -f "$f" || continue + extension="${f##*.}" + case "$extension" in + md) files="$files $f";; + *) continue;; + esac + done + test -n "$files" || exit 0 + exec mdl ${files} +fi + +case "${find_tool}" in + fd|fdfind) files="$(${find_tool} . --extension=md)";; + find) files="$(find minion.d/ -type f -name "*.md")";; +esac + +exec mdl ${files} diff --git a/scripts/salt-lint.sh b/scripts/salt-lint.sh index eb7be8f..c8fca7c 100755 --- a/scripts/salt-lint.sh +++ b/scripts/salt-lint.sh @@ -7,11 +7,10 @@ # shellcheck disable=SC2086 set -eu -command -v salt-lint >/dev/null || - { printf >&2 "Missing program: salt-lint\n"; exit 1; } command -v git >/dev/null || { printf "Missing program: git\n" >&2; exit 1; } cd "$(git rev-parse --show-toplevel)" || exit 1 +./scripts/requires-program.sh salt-lint possible_conf="${PWD}/.salt-lint" conf="" @@ -28,7 +27,7 @@ if test -n "${1-}"; then files="" for f in "$@"; do test -f "$f" || continue - extension="$(echo "$f" | awk -F '.' '{print $NF}')" + extension="${f##*.}" case "$extension" in top|sls) files="$files $f";; *) continue;; diff --git a/scripts/spec-gen.sh b/scripts/spec-gen.sh index 7ab7682..fec958f 100755 --- a/scripts/spec-gen.sh +++ b/scripts/spec-gen.sh @@ -29,7 +29,7 @@ get_scriptlet(){ scriptlet="$1" scriptlet="$(sed -n \ "/^<\!-- pkg:begin:${scriptlet} -->$/,/^<\!-- pkg:end:${scriptlet} -->$/p" \ - "${readme}" | sed '/^```.*/d;/^<\!-- pkg:/d;s/^sudo //')" + "${readme}" | sed '/^```.*/d;/^\S*$/d;/^<\!-- pkg:/d;s/^sudo //')" if test -z "${scriptlet}"; then echo true return 0 diff --git a/scripts/spec-get.sh b/scripts/spec-get.sh index 0b2c2c4..951d0fd 100755 --- a/scripts/spec-get.sh +++ b/scripts/spec-get.sh @@ -106,7 +106,8 @@ fi if test "${key}" = "summary"; then summary="$(sed -n "/^# ${name}$/,/^## Table of Contents$/{ - /./!d; /^#/d; s/\.$//; p}" -- "${readme}")" + /./!d; /^#/d; /^SPDX/d; /^/d; s/\.$//; p}" \ + -- "${readme}")" block_max_chars summary "${summary}" 70 fi