Git-Mirrors/qusal
1
0
Fork 0
mirror of https://github.com/ben-grande/qusal.git synced 2024-10-01 02:35:49 -04:00
Code Issues Packages Projects Releases Wiki Activity

doc: lint markdown files

Browse Source 
Only way to have a unified markdown syntax is to enforce the wanted
syntax by linting the files. Don't rely on the many markdown syntaxes,
be consistent.
This commit is contained in:
Ben Grande 2024-07-04 17:10:11 +02:00
parent 88d9ba525c
commit 383c840f2f
No known key found for this signature in database
GPG Key ID: 00C64E14F51F9E56
68 changed files with 1297 additions and 815 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
.mdl-style.rb Normal file
View File

@ -0,0 +1,21 @@
# SPDX-FileCopyrightText: 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
#
# 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"

6
.mdlrc Normal file
View File

@ -0,0 +1,6 @@
# SPDX-FileCopyrightText: 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
#
# SPDX-License-Identifier: MIT
# vim: ft=ruby
style "#{File.dirname(__FILE__)}/.mdl-style.rb"

11
.pre-commit-config.yaml
View File

@ -1,6 +1,6 @@
# SPDX-FileCopyrightText: 2023 Benjamin Grande M. S. <ben.grande.b@gmail.com> # SPDX-FileCopyrightText: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
# #
# SPDX-License-Identifier: GPL-3.0-or-later # SPDX-License-Identifier: AGPL-3.0-or-later
--- ---
repos: repos:
@ -22,6 +22,13 @@ repos:
pass_filenames: false pass_filenames: false
description: Lint files to comply with the REUSE Specification 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 - id: salt-lint
name: salt-lint name: salt-lint
entry: scripts/salt-lint.sh entry: scripts/salt-lint.sh

15
README.md
View File

@ -37,12 +37,12 @@ allowed to make.
Here are some of the Global Preferences we can manage: Here are some of the Global Preferences we can manage:
- **clockvm**: disp-sys-net, sys-net * **clockvm**: disp-sys-net, sys-net
- **default_audiovm**: disp-sys-audio * **default_audiovm**: disp-sys-audio
- **default_dispvm**: dvm-reader * **default_dispvm**: dvm-reader
- **default_netvm**: sys-pihole, sys-firewall or disp-sys-firewall * **default_netvm**: sys-pihole, sys-firewall or disp-sys-firewall
- **management_dispvm**: dvm-mgmt * **management_dispvm**: dvm-mgmt
- **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall * **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall
## Installation ## Installation
@ -104,7 +104,7 @@ Paid consultation services can be provided. Request a quote
You must not contact for [free support](#free-support). 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 ## 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 The easiest way to get the copyright and license of the project is with the
reuse tool: reuse tool:
```sh ```sh
reuse spdx reuse spdx
``` ```

106
docs/BOOTSTRAP.md
View File

@ -22,75 +22,75 @@ matter in some circumstances, in those cases, it is noted in this page.
## Essential ## Essential
- Base (order matters): * Base (order matters):
- [dom0](../salt/dom0/README.md) * [dom0](../salt/dom0/README.md)
- [debian-minimal](../salt/debian-minimal/README.md) * [debian-minimal](../salt/debian-minimal/README.md)
- [fedora-minimal](../salt/fedora-minimal/README.md) * [fedora-minimal](../salt/fedora-minimal/README.md)
- [mgmt](../salt/mgmt/README.md) * [mgmt](../salt/mgmt/README.md)
- [sys-cacher](../salt/sys-cacher/README.md) * [sys-cacher](../salt/sys-cacher/README.md)
## Optional ## Optional
### Internet communication ### Internet communication
- PCI devices holders: * PCI devices holders:
- [sys-net](../salt/sys-net/README.md) * [sys-net](../salt/sys-net/README.md)
- [sys-audio](../salt/sys-audio/README.md) * [sys-audio](../salt/sys-audio/README.md)
- [sys-usb](../salt/sys-usb/README.md) * [sys-usb](../salt/sys-usb/README.md)
- Firewall, DNS Sinkhole and VPN Tunnel: * Firewall, DNS Sinkhole and VPN Tunnel:
- [sys-firewall](../salt/sys-firewall/README.md) * [sys-firewall](../salt/sys-firewall/README.md)
- [sys-mirage-firewall](../salt/sys-mirage-firewall/README.md) * [sys-mirage-firewall](../salt/sys-mirage-firewall/README.md)
- [sys-pihole](../salt/sys-pihole/README.md) * [sys-pihole](../salt/sys-pihole/README.md)
- [sys-wireguard](../salt/sys-wireguard/README.md) * [sys-wireguard](../salt/sys-wireguard/README.md)
- Web browser and file retriever: * Web browser and file retriever:
- [browser](../salt/browser/README.md) * [browser](../salt/browser/README.md)
- [fetcher](../salt/fetcher/README.md) * [fetcher](../salt/fetcher/README.md)
- Instant messaging and E-Mail: * Instant messaging and E-Mail:
- [mail](../salt/mail/README.md) * [mail](../salt/mail/README.md)
- [signal](../salt/signal/README.md) * [signal](../salt/signal/README.md)
- [element](../salt/element/README.md) * [element](../salt/element/README.md)
- Electronic cash: * Electronic cash:
- [sys-bitcoin](../salt/sys-bitcoin/README.md) * [sys-bitcoin](../salt/sys-bitcoin/README.md)
- [sys-electrumx](../salt/sys-electrumx/README.md) * [sys-electrumx](../salt/sys-electrumx/README.md)
- [sys-electrs](../salt/sys-electrs/README.md) * [sys-electrs](../salt/sys-electrs/README.md)
- [electrum](../salt/electrum/README.md) * [electrum](../salt/electrum/README.md)
### Files ### Files
- Passwords and TOTP: * Passwords and TOTP:
- [vault](../salt/vault/README.md) * [vault](../salt/vault/README.md)
- Multimedia: * Multimedia:
- [reader](../salt/reader/README.md) * [reader](../salt/reader/README.md)
- [media](../salt/media/README.md) * [media](../salt/media/README.md)
- [sys-print](../salt/sys-print/README.md) * [sys-print](../salt/sys-print/README.md)
- [video-companion](../salt/video-companion/README.md) * [video-companion](../salt/video-companion/README.md)
- File sharing: * File sharing:
- [usb](../salt/usb/README.md) * [usb](../salt/usb/README.md)
- [sys-ssh](../salt/sys-ssh/README.md) * [sys-ssh](../salt/sys-ssh/README.md)
- [sys-syncthing](../salt/sys-syncthing/README.md) * [sys-syncthing](../salt/sys-syncthing/README.md)
- [sys-rsync](../salt/sys-rsync/README.md) * [sys-rsync](../salt/sys-rsync/README.md)
### Admin ### Admin
- Remote administration: * Remote administration:
- [remmina](../salt/remmina/README.md) * [remmina](../salt/remmina/README.md)
- [ssh](../salt/ssh/README.md) * [ssh](../salt/ssh/README.md)
- [sys-ssh-agent](../salt/sys-ssh-agent/README.md) * [sys-ssh-agent](../salt/sys-ssh-agent/README.md)
- Remote task execution and configuration management: * Remote task execution and configuration management:
- [ansible](../salt/ansible/README.md) * [ansible](../salt/ansible/README.md)
- [docker](../salt/docker/README.md) * [docker](../salt/docker/README.md)
- [opentofu](../salt/opentofu/README.md) * [opentofu](../salt/opentofu/README.md)
- [terraform](../salt/terraform/README.md) * [terraform](../salt/terraform/README.md)
- Coding: * Coding:
- [dev](../salt/dev/README.md) * [dev](../salt/dev/README.md)
- [sys-pgp](../salt/sys-pgp/README.md) * [sys-pgp](../salt/sys-pgp/README.md)
- [sys-git](../salt/sys-git/README.md) * [sys-git](../salt/sys-git/README.md)
- [sys-ssh-agent](../salt/sys-ssh-agent/README.md) * [sys-ssh-agent](../salt/sys-ssh-agent/README.md)

33
docs/CONTRIBUTE.md
View File

@ -50,31 +50,32 @@ packages below depending on the task:
General: General:
- git * git
For writing: For writing:
- editorconfig * editorconfig
- editorconfig plugin for your editor * editorconfig plugin for your editor
- vim, [vim-jinja](https://github.com/ben-grande/vim-jinja), * vim, [vim-jinja](https://github.com/ben-grande/vim-jinja),
[vim-salt](https://github.com/ben-grande/vim-salt) (recommended) [vim-salt](https://github.com/ben-grande/vim-salt) (recommended)
For linting: For linting:
- pre-commit * gitlint
- gitlint * markdownlint (ruby-mdl)
- salt-lint * pre-commit
- shellcheck * reuse
- reuse * salt-lint
* shellcheck
For building RPMs: For building RPMs:
- sed (GNU sed) * sed (GNU sed)
- dnf * dnf
- dnf-plugins-core (dnf builddep) * dnf-plugins-core (dnf builddep)
- rpm * rpm
- rpmlint * rpmlint
- rpmautospec (only available in Fedora) * rpmautospec (only available in Fedora)
## Issues ## Issues
@ -90,12 +91,14 @@ already been sent, the maintainer has already read and both parties loses
time. time.
Install the local hooks: Install the local hooks:
```sh ```sh
pre-commit install pre-commit install
gitlint install-hook gitlint install-hook
``` ```
To run pre-commit linters: To run pre-commit linters:
```sh ```sh
pre-commit run pre-commit run
``` ```

188
docs/DESIGN.md
View File

@ -55,7 +55,8 @@ provided via extra states that needs to be installed per the user discretion.
Markdown code must follow Markdown code must follow
[Google's Markdown style guide](https://google.github.io/styleguide/docguide/style.html). [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 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. Documentation must not duplicate itself, but reference one another.
Reproducing instructions that can be found in upstream documentation is 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: Every project should have a README.md with at least the following sections:
- Table of Contents; * Table of Contents;
- Description; * Description;
- Installation; * Installation;
- Access Control (if Qrexec policy changed); * Access Control (if Qrexec policy changed);
- Usage; and * Usage; and
- Credits (if sourced). * Credits (if sourced).
#### Access Control #### Access Control
- It must document default policy and RPC services the user can or should * It must document default policy and RPC services the user can or should
edit. edit.
- It must not document RPC services of other formulas unless the resolution of * It must not document RPC services of other formulas unless the resolution
the rule is `deny`. of the rule is `deny`.
### State file naming ### 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 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`. 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 2. State IDs must always have the project ID, thus allowing to target
states to the same minion from different projects without having multiple states to the same minion from different projects without having
conflicting IDs. conflicting IDs.
### Qube preferences ### 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 DispVM Templates. This is to easy parsing when the qube type is the first
part of its name and no exceptions. part of its name and no exceptions.
- **TemplateVM**: `tpl-NAME` * **TemplateVM**: `tpl-NAME`
- **StandaloneVM**: `NAME` * **StandaloneVM**: `NAME`
- **AppVM**: `NAME` * **AppVM**: `NAME`
- **DispVM**: `disp-NAME` * **DispVM**: `disp-NAME`
- **DispVM Template (AppVM)**: `dvm-NAME` * **DispVM Template (AppVM)**: `dvm-NAME`
- **Service qubes (not a class)**: `sys-NAME` * **Service qubes (not a class)**: `sys-NAME`
We recommend that for user created qubes, use the domain in the prefix of the 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 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 problem, domain name is in the prefix of the qube, the label is solely
related to trustworthiness of the data it is dealing with. related to trustworthiness of the data it is dealing with.
- **Black**: * **Black**:
- **Trust**: Ultimate. * **Trust**: Ultimate.
- **Description**: You must trust Dom0, Templates, Vaults, Management * **Description**: You must trust Dom0, Templates, Vaults, Management
qubes, these qubes control your system and hold valuable information. qubes, these qubes control your system and hold valuable information.
- **Examples**: dom0, tpl-ssh, vault, dvm-mgmt. * **Examples**: dom0, tpl-ssh, vault, dvm-mgmt.
- **Gray**: * **Gray**:
- **Trust**: Fully. * **Trust**: Fully.
- **Description**: Trusted storage with extra RPC services that allow * **Description**: Trusted storage with extra RPC services that allow
certain operations to be made by the client and executed on the server certain operations to be made by the client and executed on the server
or may build components for other qubes. or may build components for other qubes.
- **Examples**: sys-cacher, sys-git, sys-pgp, sys-ssh-agent, qubes-builder. * **Examples**: sys-cacher, sys-git, sys-pgp, sys-ssh-agent, qubes-builder.
- **Purple**: * **Purple**:
- **Trust**: Very much. * **Trust**: Very much.
- **Description**: Has the ability to manager remote servers via encrypted * **Description**: Has the ability to manager remote servers via encrypted
connections and depend on authorization provided by another qube. connections and depend on authorization provided by another qube.
Examples: ansible, dev, ssh, terraform. Examples: ansible, dev, ssh, terraform.
- **Blue**: * **Blue**:
- **Trust**: Much. * **Trust**: Much.
- **Description**: TODO * **Description**: TODO
- **Examples**: TODO * **Examples**: TODO
- **Green**: * **Green**:
- **Trust**: Trusted. * **Trust**: Trusted.
- **Description**: TODO * **Description**: TODO
- **Examples**: TODO * **Examples**: TODO
- **Yellow**: * **Yellow**:
- **Trust**: Relatively trusted. * **Trust**: Relatively trusted.
- **Description**: TODO * **Description**: TODO
- **Examples**: TODO * **Examples**: TODO
- **Orange**: * **Orange**:
- **Trust**: Slight. * **Trust**: Slight.
- **Description**: Controls the network flow of data to the client, * **Description**: Controls the network flow of data to the client,
normally a firewall. normally a firewall.
- **Examples**: sys-firewall, sys-vpn, sys-pihole. * **Examples**: sys-firewall, sys-vpn, sys-pihole.
- **Red**: * **Red**:
- **Trust**: Untrusted. * **Trust**: Untrusted.
- **Description**: Holds untrusted data (PCI devices, untrusted * **Description**: Holds untrusted data (PCI devices, untrusted
programs, disposables for opening untrusted files or web pages). 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 #### Qube menu
@ -192,11 +193,11 @@ 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` service. The method below is most of the times combined with `systemd.unit`
`ConditionPathExists=` to enable the service conditionally. `ConditionPathExists=` to enable the service conditionally.
- Server's service name must match the syntax: `service-server` (example: * Server's service name must match the syntax: `service-server` (example:
`rsync-server`, `syncthing-server`); `rsync-server`, `syncthing-server`);
- Client's service name must match the syntax: `service-client` (example: * Client's service name must match the syntax: `service-client` (example:
`ssh-client`; `ssh-client`;
- Local program's service name must match the syntax: `service` (example: * Local program's service name must match the syntax: `service` (example:
`docker`, `podman`. `docker`, `podman`.
### Qube connections ### Qube connections
@ -204,26 +205,27 @@ service. The method below is most of the times combined with `systemd.unit`
There are several ways a qube can connect to another, either directly with 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. Xen or with Qrexec. If something is not required, we remove it.
- `template` is always required: * `template` is always required:
- When required, must be set to the custom-made template; * When required, must be set to the custom-made template;
- When not possible to use, prefer StandaloneVMs instead. * When not possible to use, prefer StandaloneVMs instead.
- `audiovm` is rarely required on the majority of the projects: * `audiovm` is rarely required on the majority of the projects:
- When required, set it to `"*default*"` to honor the global preferences. * When required, set it to `"*default*"` to honor the global
- When not required, must be set to None; preferences.
- `netvm` is required on a lot of projects. * When not required, must be set to None;
- When required, must not be managed to honor the global preferences. If * `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 it requires a custom networking scheme, the state must make sure that
the netvm exists; the netvm exists;
- When not required, must be set to None. * When not required, must be set to None.
- `default_dispvm` is nice to have: * `default_dispvm` is nice to have:
- When required, must guarantee that the network follows the same chain as * When required, must guarantee that the network follows the same chain
the calling qube in the default configuration; as the calling qube in the default configuration;
- When not required, must be set to None. * When not required, must be set to None.
- `management_dispvm` is always required: * `management_dispvm` is always required:
- When required, should not be managed to honor the global preferences, * When required, should not be managed to honor the global preferences,
but it can make sense to set a custom management qube for debugging. 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 * When not required, such as on qubes that don't work through Salt,
touch it, it doesn't increase attack surface. don't touch it, it doesn't increase attack surface.
### Qrexec call and policy ### 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 to be set by Dom0 via the `target=` redirection parameter, instead of
having to modify the client to target a different server via having to modify the client to target a different server via
`qrexec-client-vm`. `qrexec-client-vm`.
3. Target qube for client script must default to `@default`, but other targets 3. Target qube for client script must default to `@default`, but other
must be allowed via parameters. targets must be allowed via parameters.
### Qrexec socket services ### Qrexec socket services
@ -246,30 +248,31 @@ 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` Using `qusal.Service`, such as `qusal.Rsync`, `qusal.Syncthing`, `qusal.Ssh`
has the following advantages: has the following advantages:
- Usability: User recognizes the call per service name; * Usability: User recognizes the call per service name;
- Extensibility: Allows extending functionality for arguments added in the * Extensibility: Allows extending functionality for arguments added in the
future, no need to migrate user policy from `qubes.ConnectTCP`; future, no need to migrate user policy from `qubes.ConnectTCP`; is not
is not necessary; necessary;
Rules for server RPC service: Rules for server RPC service:
- Symlink `qubes.ConnectTCP` to `qusal.Service` if connecting to a local port; * Symlink `qubes.ConnectTCP` to `qusal.Service` if connecting to a local
- Use `qubes.ConnectTCP` directly when the user won't manage the policy for port;
the wanted call, such as `sys-syncthing-browser`, where it happens that only * Use `qubes.ConnectTCP` directly when the user won't manage the policy for
this qube will access the admin interface of `sys-syncthing`; the wanted call, such as `sys-syncthing-browser`, where it happens that
- Use `socat` to connect to remote hosts or UDS with path defined by the 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. service argument.
Rules for client RPC call: Rules for client RPC call:
- Use `systemd.socket` units, it does not require `socat`, it is not * 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 restricted to the use of `qubes.ConnectTCP` called by `qvm-connect-tcp`,
service can be properly logged and status verified by a service manager the service can be properly logged and status verified by a service
instead of forking socat to the background with a `rc.local` script and manager instead of forking socat to the background with a `rc.local`
finally, can be controlled by Qubes Services to enable or disable the unit script and finally, can be controlled by Qubes Services to enable or
with `ConditionPathExists=` instead of doing if-else statements in disable the unit with `ConditionPathExists=` instead of doing if-else
`rc.local`; statements in `rc.local`;
- Use of `socat` and `qvm-connect-tcp` is permitted for UDS and for * Use of `socat` and `qvm-connect-tcp` is permitted for UDS and for
instructional use as it is very short. instructional use as it is very short.
## Features ## 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 Some projects that uses this enhancement are `sys-pihole`, `sys-syncthing` and
`sys-cacher`. `sys-cacher`.
## Release new version ## Release new version
The following sections instruct how a contributor or maintainer can deploy qu The following sections instruct how a contributor or maintainer can deploy qu
@ -327,13 +329,13 @@ Qubes OS major releases might come with changes that can impact the project.
Some projects might use archives for lack of a better alternative. Dealing Some projects might use archives for lack of a better alternative. Dealing
with them can be troublesome. Prefer packages from repositories when possible. with them can be troublesome. Prefer packages from repositories when possible.
1. Subscribe to the vendor release announcement mailing list or RSS to receive 1. Subscribe to the vendor release announcement mailing list or RSS to
notifications of new versions. receive notifications of new versions.
2. Read the changelog, breaking changes and new features might be present. 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. 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 4. Install the new archive version on the testing qube. Regarding breaking
changes, most projects implement a migration on the next restart of the 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 daemon that rebuilds a database index for example, if they don't, deal
it. For new features, check if they should be added to the default with it. For new features, check if they should be added to the default
installation. installation.
5. Change the version of the archive, git tag or commit. 5. Change the version of the archive, git tag or commit.

22
docs/INSTALL.md
View File

@ -22,8 +22,8 @@ Qusal install and update guide.
You current setup needs to fulfill the following requisites: You current setup needs to fulfill the following requisites:
- Qubes OS R4.2 * Qubes OS R4.2
- Internet connection * Internet connection
### DomU Installation ### 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 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 clone and use your remote repository instead, the submodules will also be
from your fork). from your fork).
```sh ```sh
git clone --recurse-submodules https://github.com/ben-grande/qusal.git 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 1. Copy the repository `$file` from the DomU `$qube` to Dom0 (substitute
`CHANGEME` for the desired valued): `CHANGEME` for the desired valued):
```sh ```sh
qube="CHANGEME" # qube name where you downloaded the repository qube="CHANGEME" # qube name where you downloaded the repository
file="CHANGEME" # path to the repository in the qube 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: 2. Pass the maintainer's key from the qube to Dom0:
```sh ```sh
qvm-run --pass-io "${qube}" -- "cat /home/user/ben-code.asc" | tee /tmp/ben-code.asc 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 3. Verify that the key fingerprint matches
`DF38 3487 5B65 7587 13D9 2E91 A475 969D E4E3 71E3`. You can use `DF38 3487 5B65 7587 13D9 2E91 A475 969D E4E3 71E3`. You can use
Sequoia-PGP or GnuPG for the fingerprint verification: Sequoia-PGP or GnuPG for the fingerprint verification:
```sh ```sh
gpg --show-keys /tmp/ben-code.asc gpg --show-keys /tmp/ben-code.asc
# or # 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: 4. Import the verified key to your keyring:
```sh ```sh
gpg --import /tmp/ben-code.asc 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) 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: and expect a good signature, be surprised otherwise:
```sh ```sh
git verify-commit HEAD git verify-commit HEAD
git submodule foreach git verify-commit HEAD git submodule foreach git verify-commit HEAD
``` ```
6. Copy the project to the Salt directories: 6. Copy the project to the Salt directories:
```sh ```sh
~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh ~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh
``` ```
@ -97,6 +104,7 @@ demonstrated below.
### DomU Update ### DomU Update
Update the repository state in your DomU: Update the repository state in your DomU:
```sh ```sh
git -C ~/src/qusal fetch --recurse-submodules git -C ~/src/qusal fetch --recurse-submodules
``` ```
@ -112,6 +120,7 @@ with the sys-git formula.
2. Install `git` on Dom0, allow the Qrexec protocol to work in submodules and 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): clone the repository to `~/src/qusal` (only has to be run once):
```sh ```sh
mkdir -p ~/src mkdir -p ~/src
sudo qubesctl state.apply sys-git.install-client sudo qubesctl state.apply sys-git.install-client
@ -119,6 +128,7 @@ with the sys-git formula.
``` ```
3. Next updates will be pulling instead of cloning: 3. Next updates will be pulling instead of cloning:
```sh ```sh
git -C ~/src/qusal pull --recurse-submodules git -C ~/src/qusal pull --recurse-submodules
git -C ~/src/qusal submodule update --merge 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 4. Verify the commit or tag signature and expect a good signature, be
surprised otherwise (signature verification on submodules is skipped if surprised otherwise (signature verification on submodules is skipped if
checking out but not merging): checking out but not merging):
```sh ```sh
git verify-commit HEAD git verify-commit HEAD
git submodule foreach git verify-commit HEAD git submodule foreach git verify-commit HEAD
``` ```
5. Copy the project to the Salt directories: 5. Copy the project to the Salt directories:
``` ```
~/src/qusal/scripts/setup.sh ~/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. 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): 1. Install the helpers scripts and git on Dom0 (only has to be run once):
```sh ```sh
sudo qubesctl state.apply dom0.install-helpers sudo qubesctl state.apply dom0.install-helpers
sudo qubes-dom0-update git 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 2. Copy the repository `$file` from the DomU `$qube` to Dom0 (substitute
`CHANGEME` for the desired valued): `CHANGEME` for the desired valued):
```sh ```sh
qube="CHANGEME" # qube name where you downloaded the repository qube="CHANGEME" # qube name where you downloaded the repository
file="CHANGEME" # path to the repository in the qube 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 3. Verify the commit or tag signature and expect a good signature, be
surprised otherwise: surprised otherwise:
```sh ```sh
git verify-commit HEAD git verify-commit HEAD
git submodule foreach git verify-commit HEAD git submodule foreach git verify-commit HEAD
``` ```
4. Copy the project to the Salt directories: 4. Copy the project to the Salt directories:
```sh ```sh
~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh ~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh
``` ```
@ -189,7 +205,7 @@ provided a CLI program to rename qubes.
2. Rerun the formulas that targeted 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` 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. template to be used by the qubes managed by that specific formula.
3. Repeat for every template that needs to be upgraded. 4. Repeat for every template that needs to be upgraded.
### Upgrade a template in-place ### Upgrade a template in-place

18
docs/SALT.md
View File

@ -97,9 +97,9 @@ been done, changed or not.
The `cmd` state might still be needed in some circumstances: The `cmd` state might still be needed in some circumstances:
- When Qubes OS does not provide a module; * When Qubes OS does not provide a module;
- When SaltStack does provide a module; and * When SaltStack does provide a module; and
- When SaltStack module does not meet all requirements. * When SaltStack module does not meet all requirements.
## Examples ## 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. templates, do Jinja imports and run Jinja macros.
`create-keys.sls`: `create-keys.sls`:
```salt ```salt
{# Use Qubes OS Jinja Template to create qubes using 'qvm.vm' #} {# Use Qubes OS Jinja Template to create qubes using 'qvm.vm' #}
{% from "qvm/template.jinja" import load %} {% from "qvm/template.jinja" import load %}
@ -165,6 +166,7 @@ features:
``` ```
`install-keys.sls`: `install-keys.sls`:
```salt ```salt
{# Avoid applying the state by mistake to dom0 #} {# Avoid applying the state by mistake to dom0 #}
{% if grains['nodename'] != 'dom0' %} {% if grains['nodename'] != 'dom0' %}
@ -213,6 +215,7 @@ keys-installed-os-specific:
``` ```
`appmenus-keys.sls`: `appmenus-keys.sls`:
```salt ```salt
{# From our Jinja template sync-appmenus, import 'sync_appmenus' macro #} {# From our Jinja template sync-appmenus, import 'sync_appmenus' macro #}
{% from 'utils/macros/sync-appmenus.sls' import sync_appmenus %} {% 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`. After you have created the states above, copy them to Dom0 in `/srv/salt`.
Create the qube: Create the qube:
```sh ```sh
sudo qubesctl state.apply create-keys sudo qubesctl state.apply create-keys
``` ```
Install packages in the qube template: Install packages in the qube template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-keys state.apply install-keys sudo qubesctl --skip-dom0 --targets=tpl-keys state.apply install-keys
``` ```
Make the application menus appear after the requirements are installed: Make the application menus appear after the requirements are installed:
```sh ```sh
sudo qubesctl state.apply appmenus-keys 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), 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: these are the common mistakes that you may commit. Use an editor that:
- Shows when tabs have been used instead of spaces; * Shows when tabs have been used instead of spaces;
- Highlights syntax for Salt, Jinja, Python, YAML and Shellscript; and * Highlights syntax for Salt, Jinja, Python, YAML and Shellscript; and
- Lints your file at will or when saving it; * Lints your file at will or when saving it;
For further debugging information on Qusal, read our For further debugging information on Qusal, read our
[troubleshooting guide](TROUBLESHOOT.md). [troubleshooting guide](TROUBLESHOOT.md).

17
docs/TROUBLESHOOT.md
View File

@ -24,9 +24,9 @@ typo in the configuration.
Therefore, it is recommended to: Therefore, it is recommended to:
- Check if there is a rule for the service you want to call that would either * Check if there is a rule for the service you want to call that would
result in `ask` or `allow`; and either result in `ask` or `allow`; and
- Check again and again if you made a typo in the policy. * 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` 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 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`. `qusal.GitInit`.
On `dom0`, watch the Qrexec policy logs: On `dom0`, watch the Qrexec policy logs:
```sh ```sh
sudo journalctl -fu qubes-qrexec-policy-daemon | cut -d " " -f 7- sudo journalctl -fu qubes-qrexec-policy-daemon | cut -d " " -f 7-
``` ```
If you ave many simultaneous calls being shown, get on the important ones: If you ave many simultaneous calls being shown, get on the important ones:
```sh ```sh
sudo journalctl -fu qubes-qrexec-policy-daemon | cut -d " " -f 7- \ sudo journalctl -fu qubes-qrexec-policy-daemon | cut -d " " -f 7- \
| grep -e qubes.GetDate -e qubes.Filecopy | grep -e qubes.GetDate -e qubes.Filecopy
``` ```
You can emulate the call from `dom0`: You can emulate the call from `dom0`:
```sh ```sh
qrexec-policy dev @default qubes.GetDate qrexec-policy dev @default qubes.GetDate
``` ```
On the qube making the call, run the `qrexec-client-vm` command directly On the qube making the call, run the `qrexec-client-vm` command directly
rather than using a wrapper around it: rather than using a wrapper around it:
```sh ```sh
qrexec-client-vm @default qubes.GetDate 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. page for a variety of problems you may encounter.
A nice summary of the states can be seen with the `--show-output` argument: A nice summary of the states can be seen with the `--show-output` argument:
```
```sh
sudo qubesctl --show-output state.apply pkg.uptodate sudo qubesctl --show-output state.apply pkg.uptodate
``` ```
Ending the Salt call with `-l debug` argument gives the most detailed output Ending the Salt call with `-l debug` argument gives the most detailed output
(may contain private information): (may contain private information):
```
```sh
sudo qubesctl state.apply pkg.uptodate -l debug 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 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 a specific qube. In this example we use `tpl-qubes-builder`, substitute for
the qube being managed: the qube being managed:
```sh ```sh
sudo qubesctl state.apply dom0.helpers sudo qubesctl state.apply dom0.helpers
qvm-mgmt tpl-qubes-builder qvm-mgmt tpl-qubes-builder

9
salt/ansible/README.md
View File

@ -14,25 +14,30 @@ Install Ansible and use it on the "ansible" app qube.
## Installation ## Installation
- Top * Top:
```sh ```sh
sudo qubesctl top.enable ansible sudo qubesctl top.enable ansible
sudo qubesctl --targets=tpl-ansible,ansible,ansible-minion state.apply sudo qubesctl --targets=tpl-ansible,ansible,ansible-minion state.apply
sudo qubesctl top.disable ansible sudo qubesctl top.disable ansible
``` ```
- State * State
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply ansible.create sudo qubesctl state.apply ansible.create
sudo qubesctl --skip-dom0 --targets=tpl-ansible state.apply ansible.install sudo qubesctl --skip-dom0 --targets=tpl-ansible state.apply ansible.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
From the control node `ansible`, test connection to the managed node From the control node `ansible`, test connection to the managed node
`ansible-minion`: `ansible-minion`:
```sh ```sh
ssh -p 1840 user@127.0.0.1 ssh -p 1840 user@127.0.0.1
``` ```

30
salt/browser/README.md
View File

@ -21,7 +21,8 @@ Firefox, Firefox-ESR, Mullvad-Browser, W3M or Lynx.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable browser sudo qubesctl top.enable browser
sudo qubesctl --targets=tpl-browser,dvm-browser state.apply sudo qubesctl --targets=tpl-browser,dvm-browser state.apply
@ -29,14 +30,17 @@ sudo qubesctl top.disable browser
sudo qubesctl state.apply browser.appmenus sudo qubesctl state.apply browser.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply browser.create sudo qubesctl state.apply browser.create
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install
sudo qubesctl --skip-dom0 --targets=dvm-browser state.apply browser.configure sudo qubesctl --skip-dom0 --targets=dvm-browser state.apply browser.configure
sudo qubesctl state.apply browser.appmenus sudo qubesctl state.apply browser.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
### Choose your browser ### 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 Instead of running the state `browser.install`, you can select which browser
to install: to install:
- Chromium: * Chromium:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-chromium sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-chromium
``` ```
- Chrome: * Chrome:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-chrome sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-chrome
``` ```
- Firefox: * Firefox:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-firefox sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-firefox
``` ```
- Firefox-ESR: * Firefox-ESR:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-firefox-esr sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-firefox-esr
``` ```
- Mullvad-Browser: * Mullvad-Browser:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-mullvad sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-mullvad
``` ```
* W3M:
- W3M:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-w3m sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-w3m
``` ```
- Lynx: * Lynx:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-lynx sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install-lynx
``` ```
Do not forget to sync the `appmenus`: Do not forget to sync the `appmenus`:
```sh ```sh
sudo qubesctl state.apply browser.appmenus 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 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` want to set your preferred browser as the default browser in `tpl-browser`
targeting the desired desktop file: targeting the desired desktop file:
```sh ```sh
xdg-settings set default-web-browser firefox-esr.desktop xdg-settings set default-web-browser firefox-esr.desktop
``` ```

8
salt/debian-minimal/README.md
View File

@ -15,19 +15,23 @@ it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable debian-minimal sudo qubesctl top.enable debian-minimal
sudo qubesctl --targets=debian-12-minimal state.apply sudo qubesctl --targets=debian-12-minimal state.apply
sudo qubesctl top.disable debian-minimal sudo qubesctl top.disable debian-minimal
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply debian-minimal.create sudo qubesctl state.apply debian-minimal.create
sudo qubesctl --skip-dom0 --targets=debian-12-minimal state.apply debian-minimal.install sudo qubesctl --skip-dom0 --targets=debian-12-minimal state.apply debian-minimal.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/debian-xfce/README.md
View File

@ -14,19 +14,23 @@ Creates the Debian Xfce Template as well as a Disposable Template based on it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable debian-xfce sudo qubesctl top.enable debian-xfce
sudo qubesctl --targets=debian-12-xfce state.apply sudo qubesctl --targets=debian-12-xfce state.apply
sudo qubesctl top.disable debian-xfce sudo qubesctl top.disable debian-xfce
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply debian-xfce.create sudo qubesctl state.apply debian-xfce.create
sudo qubesctl --skip-dom0 --targets=debian-12-xfce state.apply debian-xfce.install sudo qubesctl --skip-dom0 --targets=debian-12-xfce state.apply debian-xfce.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/debian/README.md
View File

@ -14,19 +14,23 @@ Creates the Debian template as well as a Disposable Template based on it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable debian sudo qubesctl top.enable debian
sudo qubesctl --targets=debian-12 state.apply sudo qubesctl --targets=debian-12 state.apply
sudo qubesctl top.disable debian sudo qubesctl top.disable debian
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply debian.create sudo qubesctl state.apply debian.create
sudo qubesctl --skip-dom0 --targets=debian-12 state.apply debian.install sudo qubesctl --skip-dom0 --targets=debian-12 state.apply debian.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

25
salt/dev/README.md
View File

@ -18,7 +18,8 @@ allows.
## Installation ## Installation
- Top * Top:
```sh ```sh
sudo qubesctl top.enable dev sudo qubesctl top.enable dev
sudo qubesctl --targets=tpl-dev,dvm-dev,dev state.apply sudo qubesctl --targets=tpl-dev,dvm-dev,dev state.apply
@ -29,8 +30,10 @@ if test -n "${proxy_target}"; then
fi fi
``` ```
- State * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply dev.create sudo qubesctl state.apply dev.create
sudo qubesctl --skip-dom0 --targets=tpl-dev state.apply dev.install 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 sudo qubesctl --skip-dom0 --targets="${proxy_target}" state.apply sys-net.install-proxy
fi fi
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
If you want some Python goodies, you can install them: If you want some Python goodies, you can install them:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-dev state.apply dev.install-python-tools 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 (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 proxy available on a `netvm` that is not deployed by Qusal, install the Qusal
TCP proxy on the templates of your `netvm`: TCP proxy on the templates of your `netvm`:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-net.install-proxy 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 Allow qube `dev` to `connect` to `github.com:22` via `disp-sys-net` but not to
any other host or via any other qube: any other host or via any other qube:
```qrexecpolicy ```qrexecpolicy
qusal.ConnectTCP +github.com+22 dev @default allow target=disp-sys-net qusal.ConnectTCP +github.com+22 dev @default allow target=disp-sys-net
qusal.ConnectTCP * dev @anyvm deny qusal.ConnectTCP * dev @anyvm deny
@ -74,13 +81,13 @@ qusal.ConnectTCP * dev @anyvm deny
The development qube `dev` can be used for: The development qube `dev` can be used for:
- code development; * code development;
- building programs; * building programs;
- signing commits, tags, pushes and verifying with split-gpg; * 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 local qube repository with split-git; and
- fetching and pushing to and from remote repository with split-ssh-agent and * fetching and pushing to and from remote repository with split-ssh-agent
without direct network connection, you can open port to the desired SSH or and without direct network connection, you can open port to the desired
HTTP server. SSH or HTTP server.
As the `dev` qube has no netvm, configure the Qrexec policy to allow or ask 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 calls to the `qusal.ConnectTCP` RPC service, so the qube can communicate with

1
salt/dev/install.sls
View File

@ -45,6 +45,7 @@ include:
- gitlint - gitlint
- pylint - pylint
- yamllint - yamllint
- markdowlint
## Debian doesn't have: salt-lint ## Debian doesn't have: salt-lint
{% set pkg = { {% set pkg = {

9
salt/docker/README.md
View File

@ -16,21 +16,26 @@ Setup docker in Qubes OS with the Docker repository.
TODO: remove installation steps or provide a docker qube. TODO: remove installation steps or provide a docker qube.
- Top * Top:
```sh ```sh
sudo qubesctl top.enable docker sudo qubesctl top.enable docker
sudo qubesctl --targets=tpl-qubes-builder state.apply sudo qubesctl --targets=tpl-qubes-builder state.apply
sudo qubesctl top.disable docker sudo qubesctl top.disable docker
``` ```
- State * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply docker.install sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply docker.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Enable the Docker and/or Podman service for qubes that will use it: Enable the Docker and/or Podman service for qubes that will use it:
```sh ```sh
qvm-features QUBE service.docker 1 qvm-features QUBE service.docker 1
qvm-features QUBE service.podman 1 qvm-features QUBE service.podman 1

16
salt/dom0/README.md
View File

@ -16,7 +16,8 @@ etc.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable dom0 sudo qubesctl top.enable dom0
sudo qubesctl state.apply sudo qubesctl state.apply
@ -24,20 +25,25 @@ sudo qubesctl top.disable dom0
sudo qubesctl --skip-dom0 --templates --standalones state.apply update.qubes-vm sudo qubesctl --skip-dom0 --templates --standalones state.apply update.qubes-vm
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply dom0 sudo qubesctl state.apply dom0
sudo qubesctl --skip-dom0 --templates --standalones state.apply update.qubes-vm sudo qubesctl --skip-dom0 --templates --standalones state.apply update.qubes-vm
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
If you need to develop in Dom0, install some goodies (bare bones): If you need to develop in Dom0, install some goodies (bare bones):
```sh ```sh
sudo qubesctl state.apply dom0.install-dev sudo qubesctl state.apply dom0.install-dev
``` ```
To forward ports from qubes to the external world: To forward ports from qubes to the external world:
```sh ```sh
sudo qubesctl state.apply dom0.port-forward 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: Instead of running the state `dom0`, you can select which states to apply:
- Window Manager i3: * Window Manager i3:
```sh ```sh
sudo qubesctl state.apply dom0.desktop-i3,dom0.desktop-i3-settings sudo qubesctl state.apply dom0.desktop-i3,dom0.desktop-i3-settings
``` ```
- Window Manager AwesomeWM: * Window Manager AwesomeWM:
```sh ```sh
sudo qubesctl state.apply dom0.desktop-awesome sudo qubesctl state.apply dom0.desktop-awesome
``` ```

2
salt/dotfiles

@ -1 +1 @@
Subproject commit 46d0753329cfdc0fcb57e4575dc831c1c6951a72 Subproject commit 56191dab6da297a48d3df41b65c1f0ae15e37ae1

15
salt/electrum/README.md
View File

@ -31,7 +31,8 @@ usage from ever connecting to the internet.
## Installation ## Installation
- Top * Top:
```sh ```sh
sudo qubesctl top.enable electrum sudo qubesctl top.enable electrum
sudo qubesctl --targets=tpl-electrum-builder,tpl-electrum,disp-electrum-builder,electrum,electrum-hot state.apply 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 sudo qubesctl state.apply electrum.appmenus
``` ```
- State * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply electrum.create sudo qubesctl state.apply electrum.create
sudo qubesctl --skip-dom0 --targets=tpl-electrum-builder state.apply electrum.install-builder 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 --skip-dom0 --targets=electrum-hot state.apply electrum.configure-hot
sudo qubesctl state.apply electrum.appmenus sudo qubesctl state.apply electrum.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
@ -75,24 +79,28 @@ our netvm qube is named `sys-net`.
In the qube `dom0`, allow `electrum` to connect to `sys-net` port 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`: `50002` via Qrexec Policy in the file `/etc/qubes/policy.d/30-user.policy`:
```qrexecpolicy ```qrexecpolicy
qubes.ConnectTCP +50002 electrum @default allow target=sys-net qubes.ConnectTCP +50002 electrum @default allow target=sys-net
``` ```
In the qube `sys-net`, add the `socat` command to the file In the qube `sys-net`, add the `socat` command to the file
`/rw/config/rc.local`: `/rw/config/rc.local`:
```sh ```sh
socat TCP4-LISTEN:50002,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:50002 & 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 In the qube `electrum`, add the `qvm-connect-tcp` command to the file
`/rw/config/rc.local`: `/rw/config/rc.local`:
```sh ```sh
qvm-connect-tcp ::50002 qvm-connect-tcp ::50002
``` ```
In the qube `electrum`, run as the user `user` the electrum configuration In the qube `electrum`, run as the user `user` the electrum configuration
commands: commands:
```sh ```sh
electrum --offline setconfig auto_connect false electrum --offline setconfig auto_connect false
electrum --offline setconfig oneserver true 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: If you used a plain-text port, no SSL:
```sh ```sh
electrum --offline setconfig server 127.0.0.1:50001:t 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 ## Credits
- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) * [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin)

8
salt/element/README.md
View File

@ -15,7 +15,8 @@ Matrix account.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable element sudo qubesctl top.enable element
sudo qubesctl --targets=tpl-element state.apply sudo qubesctl --targets=tpl-element state.apply
@ -23,13 +24,16 @@ sudo qubesctl top.disable element
sudo qubesctl state.apply element.appmenus sudo qubesctl state.apply element.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply element.create sudo qubesctl state.apply element.create
sudo qubesctl --skip-dom0 --targets=tpl-element state.apply element.install sudo qubesctl --skip-dom0 --targets=tpl-element state.apply element.install
sudo qubesctl state.apply element.appmenus sudo qubesctl state.apply element.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

9
salt/fedora-minimal/README.md
View File

@ -8,7 +8,6 @@ Fedora Minimal Template in Qubes OS.
* [Installation](#installation) * [Installation](#installation)
* [Usage](#usage) * [Usage](#usage)
## Description ## Description
Creates the Fedora Minimal template as well as a Disposable Template based on Creates the Fedora Minimal template as well as a Disposable Template based on
@ -16,7 +15,8 @@ it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable fedora-minimal sudo qubesctl top.enable fedora-minimal
sudo qubesctl --targets=fedora-40-minimal state.apply 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 sudo qubesctl state.apply fedora-minimal.prefs
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply fedora-minimal.create sudo qubesctl state.apply fedora-minimal.create
sudo qubesctl --skip-dom0 --targets=fedora-40-minimal state.apply fedora-minimal.install sudo qubesctl --skip-dom0 --targets=fedora-40-minimal state.apply fedora-minimal.install
sudo qubesctl state.apply fedora-minimal.prefs sudo qubesctl state.apply fedora-minimal.prefs
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/fedora-xfce/README.md
View File

@ -14,19 +14,23 @@ Creates the Fedora Xfce template as well as a Disposable Template based on it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable fedora-xfce sudo qubesctl top.enable fedora-xfce
sudo qubesctl --targets=fedora-40-xfce state.apply sudo qubesctl --targets=fedora-40-xfce state.apply
sudo qubesctl top.disable fedora-xfce sudo qubesctl top.disable fedora-xfce
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply fedora-xfce.create sudo qubesctl state.apply fedora-xfce.create
sudo qubesctl --skip-dom0 --targets=fedora-40-xfce state.apply fedora-xfce.install sudo qubesctl --skip-dom0 --targets=fedora-40-xfce state.apply fedora-xfce.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/fedora/README.md
View File

@ -14,19 +14,23 @@ Creates the Fedora template as well as a Disposable Template based on it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable fedora sudo qubesctl top.enable fedora
sudo qubesctl --targets=fedora-40 state.apply sudo qubesctl --targets=fedora-40 state.apply
sudo qubesctl top.disable fedora sudo qubesctl top.disable fedora
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply fedora.create sudo qubesctl state.apply fedora.create
sudo qubesctl --skip-dom0 --targets=fedora-40 state.apply fedora.install sudo qubesctl --skip-dom0 --targets=fedora-40 state.apply fedora.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/fetcher/README.md
View File

@ -21,20 +21,24 @@ Supported protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS,
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable fetcher sudo qubesctl top.enable fetcher
sudo qubesctl --targets=tpl-fetcher,dvm-fetcher state.apply sudo qubesctl --targets=tpl-fetcher,dvm-fetcher state.apply
sudo qubesctl top.disable fetcher sudo qubesctl top.disable fetcher
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply fetcher.create sudo qubesctl state.apply fetcher.create
sudo qubesctl --skip-dom0 --targets=tpl-fetcher state.apply fetcher.install sudo qubesctl --skip-dom0 --targets=tpl-fetcher state.apply fetcher.install
sudo qubesctl --skip-dom0 --targets=dvm-fetcher state.apply fetcher.configure-dvm sudo qubesctl --skip-dom0 --targets=dvm-fetcher state.apply fetcher.configure-dvm
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

33
salt/kicksecure-minimal/README.md
View File

@ -17,19 +17,23 @@ on it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable kicksecure-minimal sudo qubesctl top.enable kicksecure-minimal
sudo qubesctl --targets=kicksecure-17-minimal state.apply sudo qubesctl --targets=kicksecure-17-minimal state.apply
sudo qubesctl top.disable kicksecure-minimal sudo qubesctl top.disable kicksecure-minimal
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply kicksecure-minimal.create sudo qubesctl state.apply kicksecure-minimal.create
sudo qubesctl --skip-dom0 --targets=kicksecure-17-minimal state.apply kicksecure-minimal.install sudo qubesctl --skip-dom0 --targets=kicksecure-17-minimal state.apply kicksecure-minimal.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
### Kicksecure Developers Installation ### 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 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 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`): Qube, to report bugs upstream (get a terminal with `qvm-console-dispvm`):
```sh ```sh
sudo qubesctl --skip-dom0 --targets=kicksecure-17-minimal state.apply kicksecure-minimal.install-developers 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: Choose the `kernel` according to the `virt_mode` you want for the template:
- `hvm`: * `hvm`:
```sh ```sh
sudo qubesctl state.apply kicksecure-minimal.kernel-hvm sudo qubesctl state.apply kicksecure-minimal.kernel-hvm
``` ```
- `pvh`: * `pvh`:
```sh ```sh
sudo qubesctl state.apply kicksecure-minimal.kernel-pv 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 ```sh
sudo qubesctl state.apply kicksecure-minimal.kernel-default 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, After you have ran the developers SaltFile, when reporting bugs upstream,
share the following information of the customizations made by this formula: share the following information of the customizations made by this formula:
- `hardened-malloc`: * `hardened-malloc`:
```
```txt
libhardened_malloc.so libhardened_malloc.so
``` ```
- `hide-hardware-info`: * `hide-hardware-info`:
```
```sh
sysfs_whitelist=0 sysfs_whitelist=0
cpuionfo_whitelist=0 cpuionfo_whitelist=0
``` ```
- `permission-hardener`: * `permission-hardener`:
```
```sh
whitelists_disable_all=true whitelists_disable_all=true
``` ```

27
salt/mail/README.md
View File

@ -74,7 +74,8 @@ exploitation, as `msmtp` still needs to parse the mail to be sent.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable mail reader 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 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 sudo qubesctl state.apply mail.appmenus,reader.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply mail.create sudo qubesctl state.apply mail.create
sudo qubesctl --skip-dom0 --targets=tpl-reader state.apply reader.install 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 --skip-dom0 --targets=dvm-mail-sender state.apply mail.configure-sender
sudo qubesctl state.apply mail.appmenus,reader.appmenus sudo qubesctl state.apply mail.appmenus,reader.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
@ -124,26 +128,31 @@ mails will be done in `disp-mail-fetcher`.
#### fdm Configuration #### fdm Configuration
Copy example configuration file to where the program can read automatically: Copy example configuration file to where the program can read automatically:
```sh ```sh
cp ~/.fdm.conf.example ~/.fdm.conf cp ~/.fdm.conf.example ~/.fdm.conf
``` ```
Edit the configuration according to your needs: Edit the configuration according to your needs:
```sh ```sh
editor ~/.fdm.conf editor ~/.fdm.conf
``` ```
Check the connection is working: Check the connection is working:
```sh ```sh
fdm -kv poll fdm -kv poll
``` ```
Fetch mail: Fetch mail:
```sh ```sh
fdm -kv fetch fdm -kv fetch
``` ```
If the fetch was successful, enable the fetch scheduler: If the fetch was successful, enable the fetch scheduler:
```sh ```sh
systemctl --user enable fdm.timer systemctl --user enable fdm.timer
systemctl --user start fdm.timer systemctl --user start fdm.timer
@ -155,26 +164,31 @@ Copy `~/.mpoprc.example` to `~/.mpoprc` and edit the configuration
according to your needs. according to your needs.
Copy example configuration file to where the program can read automatically: Copy example configuration file to where the program can read automatically:
```sh ```sh
cp ~/.mporc.example ~/.mpoprc cp ~/.mporc.example ~/.mpoprc
``` ```
Edit the configuration according to your needs: Edit the configuration according to your needs:
```sh ```sh
editor ~/.mpoprc editor ~/.mpoprc
``` ```
Check the connection is working: Check the connection is working:
```sh ```sh
mpop --debug --auth-only mpop --debug --auth-only
``` ```
Fetch mail: Fetch mail:
```sh ```sh
mpop mpop
``` ```
If the fetch was successful, enable the fetch scheduler: If the fetch was successful, enable the fetch scheduler:
```sh ```sh
systemctl --user enable mpop.timer systemctl --user enable mpop.timer
systemctl --user start 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 Inbox to Reader Qube
Send the inbox to the reader: Send the inbox to the reader:
```sh ```sh
qusal-send-inbox 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 Queue to Sender Qube
Send the queued mail to the sender: Send the queued mail to the sender:
```sh ```sh
qusal-send-mail qusal-send-mail
``` ```
@ -231,16 +247,19 @@ mails are done in `disp-mail-sender`.
#### msmtp Configuration #### msmtp Configuration
Copy example configuration file to where the program can read automatically: Copy example configuration file to where the program can read automatically:
```sh ```sh
cp ~/.msmtprc.example ~/.msmtprc cp ~/.msmtprc.example ~/.msmtprc
``` ```
Edit the configuration according to your needs: Edit the configuration according to your needs:
```sh ```sh
editor ~/.msmtprc editor ~/.msmtprc
``` ```
Test the connection to the SMTP server: Test the connection to the SMTP server:
```sh ```sh
msmtp --serverinfo msmtp --serverinfo
``` ```
@ -248,15 +267,17 @@ msmtp --serverinfo
#### Send emails to SMTP server #### Send emails to SMTP server
List the queued mails: List the queued mails:
```sh ```sh
msmtp-queue -d msmtp-queue -d
``` ```
Send selected mails from the queue to the SMTP server: Send selected mails from the queue to the SMTP server:
```sh ```sh
msmtp-queue -R msmtp-queue -R
``` ```
## Credits ## Credits
- [Unman](https://github.com/unman/notes/blob/master/SplitMutt.md) * [Unman](https://github.com/unman/notes/blob/master/SplitMutt.md)

10
salt/media/README.md
View File

@ -16,20 +16,24 @@ files in a named disposable "disp-media" via MIME configuration.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable media sudo qubesctl top.enable media
sudo qubesctl --targets=tpl-media,media state.apply sudo qubesctl --targets=tpl-media,media state.apply
sudo qubesctl top.disable media sudo qubesctl top.disable media
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply media.create sudo qubesctl state.apply media.create
sudo qubesctl --skip-dom0 --targets=tpl-media state.apply media.install sudo qubesctl --skip-dom0 --targets=tpl-media state.apply media.install
sudo qubesctl --skip-dom0 --targets=media state.apply media.configure sudo qubesctl --skip-dom0 --targets=media state.apply media.configure
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
@ -47,4 +51,4 @@ You can personalize `mpv` by editing `$XDG_CONFIG_HOME/mpv/mpv.conf`.
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/tree/main/multimedia) * [Unman](https://github.com/unman/shaker/tree/main/multimedia)

8
salt/mgmt/README.md
View File

@ -16,7 +16,8 @@ of a qube or for Salt Management on DomUs.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable mgmt sudo qubesctl top.enable mgmt
sudo qubesctl --targets=tpl-mgmt state.apply sudo qubesctl --targets=tpl-mgmt state.apply
@ -24,13 +25,16 @@ sudo qubesctl top.disable mgmt
sudo qubesctl state.apply mgmt.prefs sudo qubesctl state.apply mgmt.prefs
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply mgmt.create sudo qubesctl state.apply mgmt.create
sudo qubesctl --skip-dom0 --targets=tpl-mgmt state.apply mgmt.install sudo qubesctl --skip-dom0 --targets=tpl-mgmt state.apply mgmt.install
sudo qubesctl state.apply mgmt.prefs sudo qubesctl state.apply mgmt.prefs
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

9
salt/mirage-builder/README.md
View File

@ -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 is the best verification we can get for Mirage Firewall. If you don't trust
the hosting provider however, don't install this package. the hosting provider however, don't install this package.
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable mirage-builder sudo qubesctl top.enable mirage-builder
sudo qubesctl --targets=tpl-mirage-builder,mirage-builder state.apply sudo qubesctl --targets=tpl-mirage-builder,mirage-builder state.apply
sudo qubesctl top.disable mirage-builder sudo qubesctl top.disable mirage-builder
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply mirage-builder.create 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=tpl-mirage-builder state.apply mirage-builder.install
sudo qubesctl --skip-dom0 --targets=mirage-builder state.apply mirage-builder.configure sudo qubesctl --skip-dom0 --targets=mirage-builder state.apply mirage-builder.configure
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## 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 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 already being sourced by your shell profile. Because of this, when calling
`opam-init`, use it together with the option `--no-setup`: `opam-init`, use it together with the option `--no-setup`:
```sh ```sh
opam init --no-setup opam init --no-setup
``` ```

8
salt/opentofu/README.md
View File

@ -15,19 +15,23 @@ of Terraform.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable opentofu sudo qubesctl top.enable opentofu
sudo qubesctl --targets=tpl-opentofu state.apply sudo qubesctl --targets=tpl-opentofu state.apply
sudo qubesctl top.disable opentofu sudo qubesctl top.disable opentofu
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply opentofu.create sudo qubesctl state.apply opentofu.create
sudo qubesctl --skip-dom0 --targets=tpl-opentofu state.apply opentofu.install sudo qubesctl --skip-dom0 --targets=tpl-opentofu state.apply opentofu.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

19
salt/qubes-builder/README.md
View File

@ -11,6 +11,7 @@ Setup Qubes OS Builder V2 in Qubes OS itself.
* [Pulling new commits](#pulling-new-commits) * [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) * [Add PGP public key to qubes-builder GPG home directory](#add-pgp-public-key-to-qubes-builder-gpg-home-directory)
* [Builder configuration](#builder-configuration) * [Builder configuration](#builder-configuration)
* [Build Qusal](#build-qusal)
## Description ## 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 After you've pulled the commit including the `.gitmodules` once, future
installations won't have this issue. installations won't have this issue.
- Top * Top:
```sh ```sh
sudo qubesctl top.enable qubes-builder sudo qubesctl top.enable qubes-builder
sudo qubesctl --targets=tpl-qubes-builder,dvm-qubes-builder,qubes-builder state.apply 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 sudo qubesctl state.apply qubes-builder.prefs
``` ```
- State * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply qubes-builder.create sudo qubesctl state.apply qubes-builder.create
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply qubes-builder.install 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=dvm-qubes-builder state.apply qubes-builder.configure-qubes-executor
sudo qubesctl --skip-dom0 --targets=qubes-builder state.apply qubes-builder.configure sudo qubesctl --skip-dom0 --targets=qubes-builder state.apply qubes-builder.configure
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
If you plan to write for a long time and analyze logs on the builder qube, it If you plan to write for a long time and analyze logs on the builder qube, it
is recommended to install some development goodies: is recommended to install some development goodies:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply qubes-builder.install-dev sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder state.apply qubes-builder.install-dev
``` ```
If you plan on building Qusal packages (Development only): If you plan on building Qusal packages (Development only):
```sh ```sh
sudo qubesctl --skip-dom0 --targets=qubes-builder state.apply qubes-builder.configure-qusal 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. automatically verified before merging them to your git index.
Pull `qubes-builderv2` commits: Pull `qubes-builderv2` commits:
```sh ```sh
git pull git pull
``` ```
Initialize and merge submodules: Initialize and merge submodules:
```
```sh
git submodule update --init git submodule update --init
git submodule update --merge 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 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: default, import their key to the GPG home directory of qubes-builder:
```sh ```sh
gpg-qubes-builder --import /path/to/key 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 When using the Qubes Executor, configure the `builder.yml` `dispvm` option to
either `dom0` or `dvm-qubes-builder`: either `dom0` or `dvm-qubes-builder`:
```yaml ```yaml
include: include:
- example-configs/desired-config.yml - example-configs/desired-config.yml
@ -123,6 +134,7 @@ executor:
gpg-client: gpg gpg-client: gpg
``` ```
Setting the Disposable VM to Dom0 works because it will use the Setting the Disposable VM to Dom0 works because it will use the
`default_dispvm` preference of `qubes-builder`, which is `dvm-qubes-builder`. `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. You can easily build Qusal as a default configuration is provided.
Place only the following in `builder.yml`: Place only the following in `builder.yml`:
```yaml ```yaml
include: include:
- ../qusal-builder/qusal.yml - ../qusal-builder/qusal.yml

10
salt/reader/README.md
View File

@ -18,7 +18,8 @@ necessary packages will be installed in the template.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable reader sudo qubesctl top.enable reader
sudo qubesctl --targets=tpl-reader,dvm-reader state.apply sudo qubesctl --targets=tpl-reader,dvm-reader state.apply
@ -26,14 +27,17 @@ sudo qubesctl top.disable reader
sudo qubesctl state.apply reader.appmenus sudo qubesctl state.apply reader.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply reader.create sudo qubesctl state.apply reader.create
sudo qubesctl --skip-dom0 --targets=tpl-reader state.apply reader.install sudo qubesctl --skip-dom0 --targets=tpl-reader state.apply reader.install
sudo qubesctl --skip-dom0 --targets=dvm-reader state.apply reader.configure sudo qubesctl --skip-dom0 --targets=dvm-reader state.apply reader.configure
sudo qubesctl state.apply reader.appmenus sudo qubesctl state.apply reader.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
@ -49,4 +53,4 @@ you want before the disposable makes a connection.
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/tree/main/reader) * [Unman](https://github.com/unman/shaker/tree/main/reader)

8
salt/remmina/README.md
View File

@ -16,7 +16,8 @@ you prefer to use an app qube, a qube named "remmina" will also be created.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable remmina sudo qubesctl top.enable remmina
sudo qubesctl --targets=tpl-remmina state.apply sudo qubesctl --targets=tpl-remmina state.apply
@ -24,13 +25,16 @@ sudo qubesctl top.disable remmina
sudo qubesctl state.apply remmina.appmenus sudo qubesctl state.apply remmina.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply remmina.create sudo qubesctl state.apply remmina.create
sudo qubesctl --skip-dom0 --targets=tpl-remmina state.apply remmina.install sudo qubesctl --skip-dom0 --targets=tpl-remmina state.apply remmina.install
sudo qubesctl state.apply remmina.appmenus sudo qubesctl state.apply remmina.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/signal/README.md
View File

@ -14,7 +14,8 @@ Install Signal Desktop and creates an app qube named "signal".
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable signal sudo qubesctl top.enable signal
sudo qubesctl --targets=tpl-signal,signal state.appply sudo qubesctl --targets=tpl-signal,signal state.appply
@ -22,14 +23,17 @@ sudo qubesctl top.disable signal
sudo qubesctl state.apply signal.appmenus sudo qubesctl state.apply signal.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply signal.create sudo qubesctl state.apply signal.create
sudo qubesctl --skip-dom0 --targets=tpl-signal state.apply signal.install sudo qubesctl --skip-dom0 --targets=tpl-signal state.apply signal.install
sudo qubesctl --skip-dom0 --targets=signal state.apply signal.configure sudo qubesctl --skip-dom0 --targets=signal state.apply signal.configure
sudo qubesctl state.apply signal.appmenus sudo qubesctl state.apply signal.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

12
salt/ssh/README.md
View File

@ -18,20 +18,24 @@ in as a one time connection or to an untrusted host use a DispVM based on
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable ssh sudo qubesctl top.enable ssh
sudo qubesctl --targets=tpl-ssh,dvm-ssh,ssh state.apply sudo qubesctl --targets=tpl-ssh,dvm-ssh,ssh state.apply
sudo qubesctl top.disable ssh sudo qubesctl top.disable ssh
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply ssh.create sudo qubesctl state.apply ssh.create
sudo qubesctl --skip-dom0 --targets=tpl-ssh state.apply ssh.install sudo qubesctl --skip-dom0 --targets=tpl-ssh state.apply ssh.install
sudo qubesctl --skip-dom0 --targets=dvm-ssh,ssh state.apply ssh.configure sudo qubesctl --skip-dom0 --targets=dvm-ssh,ssh state.apply ssh.configure
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
@ -42,7 +46,7 @@ preserving the SSH configuration client side.
The client qube can enhanced by being: The client qube can enhanced by being:
- sys-ssh-agent's client and not storing the SSH keys on the client; or * 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-git's client and fetching from qubes and push to remote servers.
The server requires the OpenSSH server to be installed. The server requires the OpenSSH server to be installed.

27
salt/sys-audio/README.md
View File

@ -25,28 +25,34 @@ the necessary packages for bluetooth with the provided state.
## Installation ## Installation
- Top * Top:
```sh ```sh
sudo qubesctl top.enable sys-audio sudo qubesctl top.enable sys-audio
sudo qubesctl --targets=tpl-sys-audio,dvm-sys-audio state.apply sudo qubesctl --targets=tpl-sys-audio,dvm-sys-audio state.apply
sudo qubesctl top.disable sys-audio sudo qubesctl top.disable sys-audio
``` ```
- State * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-audio.create 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=tpl-sys-audio state.apply sys-audio.install
sudo qubesctl --skip-dom0 --targets=dvm-sys-audio state.apply sys-audio.configure-dvm sudo qubesctl --skip-dom0 --targets=dvm-sys-audio state.apply sys-audio.configure-dvm
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
If you want to autostart the AudioVM on boot, you may run: If you want to autostart the AudioVM on boot, you may run:
```sh ```sh
sudo qubesctl state.apply sys-audio.autostart sudo qubesctl state.apply sys-audio.autostart
``` ```
If you need Bluetooth support, install the dependencies: If you need Bluetooth support, install the dependencies:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-sys-audio state.apply sys-audio.install-bluetooth 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: Audio control basics:
- Left click toggles the volume; and * Left click toggles the volume; and
- Scrolling the mouse from left to right changes the volume; * Scrolling the mouse from left to right changes the volume;
For more advanced features, right click the icon and click on `Open Mixer` or For more advanced features, right click the icon and click on `Open Mixer` or
`Prefences`. For greater control, use the command `amixer`. `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. 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: To connect the client to audio server, restart the client's Pipewire service:
```sh ```sh
systemctl --user restart pipewire 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 speaker, normal operation to attach the device to the same or any other qube
will fail. To be able to use the device again: will fail. To be able to use the device again:
- Restart the AudioVM `disp-sys-audio`; * Restart the AudioVM `disp-sys-audio`;
- Restart the audio client; and * Restart the audio client; and
- Attach the device to the audio client. * Attach the device to the audio client.
### How to use USB devices ### 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. system security.
First, start the qube holding the USB stack: First, start the qube holding the USB stack:
```sh ```sh
qvm-start disp-sys-usb qvm-start disp-sys-usb
``` ```
Identify you Bluetooth controller: Identify you Bluetooth controller:
```
```sh
qvm-usb list disp-sys-usb qvm-usb list disp-sys-usb
``` ```
If you haven't identified the device, run `lsusb` in the USB stack server: If you haven't identified the device, run `lsusb` in the USB stack server:
```sh ```sh
qvm-run -p disp-sys-usb -- lsusb qvm-run -p disp-sys-usb -- lsusb
``` ```
Permanently attach the Bluetooth controller to the AudioVM (change `DEVID` for Permanently attach the Bluetooth controller to the AudioVM (change `DEVID` for
the one you identified above): the one you identified above):
```sh ```sh
qvm-usb attach --persistent disp-sys-audio disp-sys-usb:DEVID qvm-usb attach --persistent disp-sys-audio disp-sys-usb:DEVID
``` ```

58
salt/sys-bitcoin/README.md
View File

@ -46,7 +46,8 @@ At least `1TB` of disk space is required. At block `829054` (2024-02-05),
## Installation ## Installation
- Top * Top:
```sh ```sh
sudo qubesctl top.enable sys-bitcoin sudo qubesctl top.enable sys-bitcoin
sudo qubesctl --targets=sys-bitcoin-gateway,tpl-sys-bitcoin,disp-sys-bitcoin-builder,sys-bitcoin,bitcoin state.apply 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 sudo qubesctl state.apply sys-bitcoin.appmenus
``` ```
- State * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-bitcoin.create sudo qubesctl state.apply sys-bitcoin.create
sudo qubesctl --skip-dom0 --targets=sys-bitcoin-gateway state.apply sys-bitcoin.configure-gateway 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 --skip-dom0 --targets=bitcoin state.apply sys-bitcoin.configure-client
sudo qubesctl state.apply sys-bitcoin.appmenus sudo qubesctl state.apply sys-bitcoin.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
If you prefer to build from source (will take approximately 1 hour to build): If you prefer to build from source (will take approximately 1 hour to build):
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-sys-bitcoin state.apply sys-bitcoin.install-source 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 sudo qubesctl --skip-dom0 --targets=disp-bitcoin-builder state.apply sys-bitcoin.configure-builder-source
``` ```
If you want to relay blocks (listening node): If you want to relay blocks (listening node):
```sh ```sh
sudo qubesctl --skip-dom0 --targets=sys-bitcoin-gateway state.apply sys-bitcoin.configure-gateway-listen 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 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: Add the tag `bitcoin-client` to the client and install in the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-bitcoin.install-client sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-bitcoin.install-client
``` ```
## Usage ## Usage
The qube `sys-bitcoin` can: The qube `sys-bitcoin` can:
- Index the Bitcoin blockchain connecting to peers over Tor; * Index the Bitcoin blockchain connecting to peers over Tor;
- Connect to a remote Bitcoin RPC reachable over Tor; and * Connect to a remote Bitcoin RPC reachable over Tor; and
- Broadcast transactions over Tor. * Broadcast transactions over Tor.
The qube `bitcoin` can: The qube `bitcoin` can:
- Create wallet addresses; and * Create wallet addresses; and
- Sign transactions. * Sign transactions.
### Custom daemon parameters ### 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 You can enable pruning in `/home/user/.bitcoin/conf.d/bitcoin.conf.local` by
specifying how many `MiB` of block files to retain: specifying how many `MiB` of block files to retain:
```cfg ```cfg
prune=550 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, 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 you just need to reduce the memory available to the `sys-bitcoin` qube. From
`dom0`, run: `dom0`, run:
```sh ```sh
qvm-prefs sys-bitcoin memory 1000 qvm-prefs sys-bitcoin memory 1000
``` ```
@ -137,20 +145,20 @@ interface for the Bitcoin Core Wallet.
You may wish to connect to a remote Bitcoin node with RPC available to: 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 * Lower disk space usage and to lower resource consumption by not having
multiple Bitcoin blockchains; multiple Bitcoin blockchains;
- Avoid changing scripts and configurations that expect the connection to be * Avoid changing scripts and configurations that expect the connection to
working on `127.0.0.1:8332`, such as the Qrexec policy for connecting be working on `127.0.0.1:8332`, such as the Qrexec policy for connecting
Bitcoind RPC to the Electrum Servers. Bitcoind RPC to the Electrum Servers.
But there are huge disadvantages to this method: 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). * [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 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 transport encryption to connect to your Bitcoin RPC. If you run bitcoind
`sys-bitcoin`, you do not have to worry about transport encryption as on `sys-bitcoin`, you do not have to worry about transport encryption as
communication is done securely via Qrexec. communication is done securely via Qrexec.
- Bitcoin configuration cannot be changed remotely, therefore adding RPC * Bitcoin configuration cannot be changed remotely, therefore adding RPC
Authentication for clients such as Electrum Servers have to be done Authentication for clients such as Electrum Servers have to be done
manually. manually.
@ -162,16 +170,17 @@ it is intended for advanced users only.
On the remote node: On the remote node:
- You must set in the node's `bitcoin.conf`, the following options to bind to * You must set in the node's `bitcoin.conf`, the following options to bind
the external interface: `rpcbind`, `bind` (Electrs), to the external interface: `rpcbind`, `bind` (Electrs),
`whitelist=download@<ADDR>` (ElectRS), `zmqpubhashblock` (Fulcrum) and allow `whitelist=download@<ADDR>` (ElectRS), `zmqpubhashblock` (Fulcrum) and
connections of the external IP of your upstream netvm via `rpcallowip`. allow connections of the external IP of your upstream netvm via
- Open the configured ports of the previous settings in the firewall to be `rpcallowip`.
* Open the configured ports of the previous settings in the firewall to be
reachable by the Qubes system. reachable by the Qubes system.
- Generate RPC credentials (see `bitcoin/share/rpcauth/rpcauth.py`), add * Generate RPC credentials (see `bitcoin/share/rpcauth/rpcauth.py`), add
`rpcauth=` option to `bitcoin.conf` and save the `user` and `password` for `rpcauth=` option to `bitcoin.conf` and save the `user` and `password` for
later. later.
- Restart bitcoind to apply the configuration changes. * Restart bitcoind to apply the configuration changes.
#### Connect the qube to the remote node #### 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 In `dom0`, create the user Qrexec policy to target the qube `sys-net` in
`/etc/qubes/policy.d/30-user.policy`: `/etc/qubes/policy.d/30-user.policy`:
```qrexecpolicy ```qrexecpolicy
## Getting Auth doesn't work with remote node. ## Getting Auth doesn't work with remote node.
qusal.BitcoinAuthGet * @anyvm @anyvm deny 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 In the qube `sys-net`, add the `socat` command (only the ones you need) to the
file `/rw/config/rc.local`: file `/rw/config/rc.local`:
```sh ```sh
## RPC ## RPC
socat TCP-LISTEN:8332,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8332 & 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`, In the Electrum Server qubes or any Bitcoin Client, `sys-electrumx`,
`sys-electrs`, `sys-fulcrum`, add the `qvm-connect-tcp` command to the file `sys-electrs`, `sys-fulcrum`, add the `qvm-connect-tcp` command to the file
`/rw/config/rc.local`: `/rw/config/rc.local`:
```sh ```sh
## RPC ## RPC
qvm-connect-tcp ::8332 qvm-connect-tcp ::8332
@ -236,4 +248,4 @@ If you have done this, please share a guide.
## Credits ## Credits
- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) * [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin)

36
salt/sys-cacher/README.md
View File

@ -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. next time you want to upgrade your system packages.
When you install this package, qubes will be tagged with "updatevm-sys-cacher" 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 <https://>
in your repository definitions, the entries will be changed in the templates 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 <http://HTTPS///>. This is so that the request to the proxy is plain
text, and the proxy will then make the request via https. text, and the proxy will then make the request via https.
This change will be done automatically for every template that exists and is 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: The caching proxy supports:
- Debian and derivatives (but not Whonix) * Debian and derivatives (but not Whonix)
- Fedora and derivatives * Fedora and derivatives
- Arch Linux and derivatives * Arch Linux and derivatives
## Installation ## Installation
Installation may take a long time as it will target all templates unless you Installation may take a long time as it will target all templates unless you
specify otherwise. specify otherwise.
- Top * Top:
```sh ```sh
sudo qubesctl top.enable sys-cacher browser sudo qubesctl top.enable sys-cacher browser
sudo qubesctl --targets=tpl-browser,sys-cacher-browser,tpl-sys-cacher,sys-cacher state.apply 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 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:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-cacher.create sudo qubesctl state.apply sys-cacher.create
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install 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 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 sudo qubesctl --skip-dom0 --targets="$(qvm-ls --no-spinner --raw-list --tags updatevm-sys-cacher | tr "\n" ",")" state.apply sys-cacher.install-client
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Access control ## Access control
@ -72,6 +76,7 @@ can do so.
Allow qubes with tag `whonix-updatevm` to use the proxy in `sys-alt-whonix` 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`. and qube `dev` to use the proxy in `disp-sys-net`.
```qrexecpolicy ```qrexecpolicy
qubes.UpdatesProxy * @tag:whonix-updatevm @default allow target=sys-alt-whonix qubes.UpdatesProxy * @tag:whonix-updatevm @default allow target=sys-alt-whonix
qubes.UpdatesProxy * @tag:whonix-updatevm @anyvm deny 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 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 administrative access to the cacher qube. You should add the following to the
end of `sys-cacher` rc.local: end of `sys-cacher` rc.local:
```sh ```sh
echo "AdminAuth: username:password" | tee /etc/qusal-apt-cacher-ng/zzz_security.conf echo "AdminAuth: username:password" | tee /etc/qusal-apt-cacher-ng/zzz_security.conf
``` ```
Where username and password are HTTP Auth strings. Where username and password are HTTP Auth strings.
### Connect to the cacher via IP instead of Qrexec ### 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. setting `sys-cacher` as the netvm of the client qube.
Set `sys-cacher` as the netvm of your qube: Set `sys-cacher` as the netvm of your qube:
```sh ```sh
qvm-prefs QUBE netvm sys-cacher qvm-prefs QUBE netvm sys-cacher
``` ```
Enable the service `netvm-cacher`: Enable the service `netvm-cacher`:
```sh ```sh
qvm-features QUBE service.netvm-cacher 1 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 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 non-TemplateVMs updates or simply make them functional again, the qube will
need the `service.updates-proxy-setup` feature set: need the `service.updates-proxy-setup` feature set:
```sh ```sh
qvm-tags QUBE add updatevm-sys-cacher qvm-tags QUBE add updatevm-sys-cacher
qvm-features QUBE service.updates-proxy-setup 1 qvm-features QUBE service.updates-proxy-setup 1
sudo qubesctl --skip-dom0 --targets=QUBE state.apply sys-cacher.install-client sudo qubesctl --skip-dom0 --targets=QUBE state.apply sys-cacher.install-client
``` ```
Don't forget to restart the qube. Don't forget to restart the qube.
If you don't want or can't restart the qube, such as DispVMs, where you would If you don't want or can't restart the qube, such as DispVMs, where you would
lose the current session: lose the current session:
```sh ```sh
qvm-tags QUBE add updatevm-sys-cacher qvm-tags QUBE add updatevm-sys-cacher
qvm-features QUBE service.updates-proxy-setup 1 qvm-features QUBE service.updates-proxy-setup 1
@ -153,7 +165,8 @@ systemctl restart qubes-updates-proxy-forwarder.socket"
## Uninstallation ## Uninstallation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-cacher.deinit sudo qubesctl top.enable sys-cacher.deinit
sudo qubesctl --targets="$(qvm-ls --no-spinner --raw-list --tags updatevm-sys-cacher | tr "\n" ",")" state.apply 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 sudo qubesctl state.apply sys-cacher.untag
``` ```
- State: * State:
```sh ```sh
sudo qubesctl state.apply sys-cacher.remove-policy 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 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 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: from the templates that you don't want to cache packages:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=QUBE state.apply sys-cacher.uninstall-client sudo qubesctl --skip-dom0 --targets=QUBE state.apply sys-cacher.uninstall-client
qvm-tags QUBE del updatevm-sys-cacher 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 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 fail. Get a full list of unsupported qubes (**warning**: there may be false
positives of supported qubes being listed): positives of supported qubes being listed):
```sh ```sh
sudo qubesctl --show-output state.apply sys-cacher.list-extra-tag sudo qubesctl --show-output state.apply sys-cacher.list-extra-tag
``` ```
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/tree/main/cacher) * [Unman](https://github.com/unman/shaker/tree/main/cacher)

10
salt/sys-electrs/README.md
View File

@ -26,7 +26,8 @@ At least `200GB` of disk space is required.
This formula depends on [sys-bitcoin](../sys-bitcoin/README.md). This formula depends on [sys-bitcoin](../sys-bitcoin/README.md).
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-electrs sudo qubesctl top.enable sys-electrs
sudo qubesctl --targets=tpl-electrs-builder,tpl-sys-electrs,disp-electrs-builder,sys-electrs state.apply 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 sudo qubesctl state.apply sys-electrs.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-electrs.create sudo qubesctl state.apply sys-electrs.create
sudo qubesctl --skip-dom0 --targets=tpl-electrs-builder state.apply sys-electrs.install-builder 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 --skip-dom0 --targets=sys-electrs state.apply sys-electrs.configure
sudo qubesctl state.apply sys-electrs.appmenus sudo qubesctl state.apply sys-electrs.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
@ -58,4 +62,4 @@ file, else Electrs will fail to start.
## Credits ## Credits
- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) * [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin)

10
salt/sys-electrumx/README.md
View File

@ -26,7 +26,8 @@ At least `200GB` of disk space is required.
This formula depends on [sys-bitcoin](../sys-bitcoin/README.md). This formula depends on [sys-bitcoin](../sys-bitcoin/README.md).
- Top * Top:
```sh ```sh
sudo qubesctl top.enable sys-electrumx sudo qubesctl top.enable sys-electrumx
sudo qubesctl --targets=tpl-electrumx-builder,tpl-sys-electrumx,disp-electrumx-builder,sys-electrumx state.apply 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 sudo qubesctl state.apply sys-electrumx.appmenus
``` ```
- State * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-electrumx.create sudo qubesctl state.apply sys-electrumx.create
sudo qubesctl --skip-dom0 --targets=tpl-electrumx-builder state.apply sys-electrumx.install-builder 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 --skip-dom0 --targets=sys-electrumx state.apply sys-electrumx.configure
sudo qubesctl state.apply sys-electrumx.appmenus sudo qubesctl state.apply sys-electrumx.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
@ -61,4 +65,4 @@ ElectrumX server.
## Credits ## Credits
- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin) * [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin)

9
salt/sys-firewall/README.md
View File

@ -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 or yours `default_netvm` and check if DNS is working, after that, proceed with
the installation. the installation.
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-firewall sudo qubesctl top.enable sys-firewall
sudo qubesctl --targets=tpl-sys-firewall state.apply 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 sudo qubesctl state.apply sys-firewall.prefs-disp
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-firewall.create sudo qubesctl state.apply sys-firewall.create
sudo qubesctl --skip-dom0 --targets=tpl-sys-firewall state.apply sys-firewall.install sudo qubesctl --skip-dom0 --targets=tpl-sys-firewall state.apply sys-firewall.install
sudo qubesctl state.apply sys-firewall.prefs-disp sudo qubesctl state.apply sys-firewall.prefs-disp
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Alternatively, if you prefer to have an app qube as the firewall: Alternatively, if you prefer to have an app qube as the firewall:
```sh ```sh
sudo qubesctl state.apply sys-firewall.prefs sudo qubesctl state.apply sys-firewall.prefs
``` ```

43
salt/sys-git/README.md
View File

@ -26,9 +26,9 @@ and Init. This is an implementation of split-git.
The following alternatives will be compared against each other and this The following alternatives will be compared against each other and this
implementation: implementation:
- [Rudd-O/git-remote-qubes](https://github.com/Rudd-O/git-remote-qubes) * [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) * [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) * [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 | | | 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 ## Installation
- Top * Top:
```sh ```sh
sudo qubesctl top.enable sys-git sudo qubesctl top.enable sys-git
sudo qubesctl --targets=tpl-sys-git,sys-git state.apply sudo qubesctl --targets=tpl-sys-git,sys-git state.apply
sudo qubesctl top.disable sys-git sudo qubesctl top.disable sys-git
``` ```
- State * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-git.create 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=tpl-sys-git state.apply sys-git.install
sudo qubesctl --skip-dom0 --targets=sys-git state.apply sys-git.configure sudo qubesctl --skip-dom0 --targets=sys-git state.apply sys-git.configure
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Installation on the client template: Installation on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-dev state.apply sys-git.install-client 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__: __Recommended usage__:
- __Init__: Argument useful when allowing a qube to always create a * __Init__: Argument useful when allowing a qube to always create a
repository on the server. * repository on the server.
- __Fetch__: Fetch can be allowed by less trusted qubes. * __Fetch__: Fetch can be allowed by less trusted qubes.
- __Push__: Push should only be made by 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`: Allow qube `dev` to `Fetch` from `sys-git`, but ask to `Push` and `Init`:
```qrexecpolicy ```qrexecpolicy
qusal.GitFetch * dev @default allow target=sys-git qusal.GitFetch * dev @default allow target=sys-git
qusal.GitPush * dev @default ask target=sys-git default_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 Allow qube `untrusted` to `Fetch` `repo` if using target name `sys-git` but
deny `Push` and `Init` to any other qube: deny `Push` and `Init` to any other qube:
```qrexecpolicy ```qrexecpolicy
qusal.GitFetch +repo untrusted sys-git ask target=sys-git default_target=sys-git qusal.GitFetch +repo untrusted sys-git ask target=sys-git default_target=sys-git
qusal.GitFetch * untrusted @anyvm deny 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: Deny `Fetch`, `Push` and `Init` from any qube to any other qube:
```qrexecpolicy ```qrexecpolicy
qusal.GitFetch * @anyvm @anyvm deny qusal.GitFetch * @anyvm @anyvm deny
qusal.GitPush * @anyvm @anyvm deny qusal.GitPush * @anyvm @anyvm deny
@ -141,19 +149,22 @@ qusal.GitInit * @anyvm @anyvm deny
There are a few constraints regarding repositories: There are a few constraints regarding repositories:
- Must be created under `/home/user/src` in `sys-git`; * Must be created under `/home/user/src` in `sys-git`;
- Names must have only letters, numbers, hyphen, underscore and dot. Must not * Names must have only letters, numbers, hyphen, underscore and dot. Must
begin or end with dot, hyphen and underscore. not begin or end with dot, hyphen and underscore.
In `sys-git`, create bare repositories under `/home/user/src`. In `sys-git`, create bare repositories under `/home/user/src`.
From the `server`: From the `server`:
```sh ```sh
git init --bare ~/src/X.git git init --bare ~/src/X.git
``` ```
You must use the `.git` prefix to indicate a bare repository. You must use the `.git` prefix to indicate a bare repository.
Or from the `client`, if the `qusal.GitInit` policy allows: Or from the `client`, if the `qusal.GitInit` policy allows:
```sh ```sh
cd ~/path/to/repo cd ~/path/to/repo
git init-qrexec git init-qrexec
@ -167,22 +178,26 @@ token and the `<REPO>` field is the name of the repository that exists on
`sys-git` under `/home/user/src`. `sys-git` under `/home/user/src`.
Clone an existing repository: Clone an existing repository:
```sh ```sh
git clone qrexec://@default/qubes-doc git clone qrexec://@default/qubes-doc
``` ```
Or Initialize a new repository: Or Initialize a new repository:
```sh ```sh
git init qubes-doc git init qubes-doc
cd qubes-doc cd qubes-doc
``` ```
Add a remote using the Qrexec protocol: Add a remote using the Qrexec protocol:
```sh ```sh
git remote add sg qrexec://@default/qubes-doc git remote add sg qrexec://@default/qubes-doc
``` ```
Test fetching from the newly added remote: Test fetching from the newly added remote:
```sh ```sh
git fetch sg git fetch sg
``` ```
@ -190,15 +205,17 @@ git fetch sg
Make changes to the git repository as you normally would on any system. Make changes to the git repository as you normally would on any system.
Push to the server and set it as the default upstream: Push to the server and set it as the default upstream:
```sh ```sh
git push -u sg main git push -u sg main
``` ```
Following pushes will be simpler: Following pushes will be simpler:
```sh ```sh
git push git push
``` ```
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/tree/main/git) * [Unman](https://github.com/unman/shaker/tree/main/git)

15
salt/sys-mirage-firewall/README.md
View File

@ -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 We have built the Unikernel locally and verified that the upstream checksum
and local checksum matched when comparing the same release. and local checksum matched when comparing the same release.
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-mirage-firewall sudo qubesctl top.enable sys-mirage-firewall
sudo qubesctl state.apply sudo qubesctl state.apply
sudo qubesctl top.disable sys-mirage-firewall sudo qubesctl top.disable sys-mirage-firewall
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-mirage-firewall.create sudo qubesctl state.apply sys-mirage-firewall.create
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
Set qubes `netvm` to `disp-sys-mirage-firewall`: Set qubes `netvm` to `disp-sys-mirage-firewall`:
```sh ```sh
qvm-prefs --set QUBE netvm disp-sys-mirage-firewall 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`. To test the firewall, apply rules with `qvm-firewall`.
For monitoring, inspect the Unikernel console: For monitoring, inspect the Unikernel console:
```sh ```sh
sudo xl console disp-sys-mirage-firewall sudo xl console disp-sys-mirage-firewall
``` ```
Exit the console with `Ctrl-]`. Exit the console with `Ctrl-]`.
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/tree/main/mirage) * [Unman](https://github.com/unman/shaker/tree/main/mirage)
- [Thien Tran](https://privsec.dev/posts/qubes/firewalling-with-mirageos-on-qubes-os/) * [Thien Tran](https://privsec.dev/posts/qubes/firewalling-with-mirageos-on-qubes-os/)

11
salt/sys-net/README.md
View File

@ -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 Debian or Fedora. Before starting, turn on the `default_netvm` and check if
DNS is working, after that, proceed with the installation. DNS is working, after that, proceed with the installation.
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-net sudo qubesctl top.enable sys-net
sudo qubesctl --targets=tpl-sys-net state.apply 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 sudo qubesctl state.apply sys-net.prefs-disp
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-net.create sudo qubesctl state.apply sys-net.create
sudo qubesctl --skip-dom0 --targets=tpl-sys-net state.apply sys-net.install sudo qubesctl --skip-dom0 --targets=tpl-sys-net state.apply sys-net.install
sudo qubesctl state.apply sys-net.prefs-disp sudo qubesctl state.apply sys-net.prefs-disp
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
If you need to debug a net qube, install some helper tools: If you need to debug a net qube, install some helper tools:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-sys-net state.apply sys-net.install-debug 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: If you prefer to have an app qube as the net qube:
```sh ```sh
sudo qubesctl state.apply sys-net.prefs 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. for a call to occur. Some examples are represented below.
Qube `dev` can ask to connect to `github.com:22` from `disp-sys-net`: Qube `dev` can ask to connect to `github.com:22` from `disp-sys-net`:
```qrexecpolicy ```qrexecpolicy
qusal.ConnectTCP +github.com+22 dev @default ask target=disp-sys-net qusal.ConnectTCP +github.com+22 dev @default ask target=disp-sys-net
qusal.ConnectTCP * dev @anyvm deny qusal.ConnectTCP * dev @anyvm deny

14
salt/sys-pgp/README.md
View File

@ -17,7 +17,8 @@ and access to them is made from the client through Qrexec.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-pgp sudo qubesctl top.enable sys-pgp
sudo qubesctl --targets=tpl-sys-pgp,sys-pgp state.apply 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 sudo qubesctl state.apply sys-pgp.prefs
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-pgp.create 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=tpl-sys-pgp state.apply sys-pgp.install
sudo qubesctl --skip-dom0 --targets=sys-pgp state.apply sys-pgp.configure sudo qubesctl --skip-dom0 --targets=sys-pgp state.apply sys-pgp.configure
sudo qubesctl state.apply sys-pgp.prefs sudo qubesctl state.apply sys-pgp.prefs
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Install on the client template: Install on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-qubes-builder,tpl-dev state.apply sys-pgp.install-client 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: The client qube requires the split GPG client service to be enabled:
```sh ```sh
qvm-features QUBE service.split-gpg2-client 1 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`. it to use split-gpg in `sys-pgp`.
Allow the `work` qubes to access `sys-pgp`, but not other qubes: Allow the `work` qubes to access `sys-pgp`, but not other qubes:
```qrexecpolicy ```qrexecpolicy
qubes.Gpg2 * work sys-pgp ask default_target=sys-pgp qubes.Gpg2 * work sys-pgp ask default_target=sys-pgp
qubes.Gpg2 * work @default ask target=sys-pgp 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/<QUBE>`. at `~/.gnupg/split-gpg/<QUBE>`.
On `dom0`, enabled the service `split-gpg2-client` for the client qube `dev`: On `dom0`, enabled the service `split-gpg2-client` for the client qube `dev`:
```sh ```sh
qvm-features dev service.split-gpg2-client 1 qvm-features dev service.split-gpg2-client 1
``` ```
On the qube `sys-pgp`, generate or import keys for the client qube `dev`: On the qube `sys-pgp`, generate or import keys for the client qube `dev`:
```sh ```sh
mkdir -p ~/.gnupg/split-gpg/dev mkdir -p ~/.gnupg/split-gpg/dev
gpg --homedir ~/.gnupg/split-gpg/dev --import /path/to/secret.key 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: On the qube `dev`, import the public part of your key:
```sh ```sh
gpg --import /path/to/public.key gpg --import /path/to/public.key
``` ```

23
salt/sys-pihole/README.md
View File

@ -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 best verification we can get for Pi-Hole. If you don't trust the hosting
provider however, don't install this package. provider however, don't install this package.
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-pihole browser sudo qubesctl top.enable sys-pihole browser
sudo qubesctl --targets=tpl-browser,sys-pihole-browser,sys-pihole state.apply 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 sudo qubesctl state.apply sys-pihole.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-pihole.create sudo qubesctl state.apply sys-pihole.create
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install 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 --skip-dom0 --targets=sys-pihole-browser state.apply sys-pihole.configure-browser
sudo qubesctl state.apply sys-pihole.appmenus sudo qubesctl state.apply sys-pihole.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
If you want to change the global preferences `updatevm` and `default_netvm` 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 and the per-qube preference `netvm` of all qubes from `sys-firewall` to
`sys-pihole`, run: `sys-pihole`, run:
```sh ```sh
sudo qubesctl state.apply sys-pihole.prefs 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: Pi-hole will be installed with the following settings:
- The DNS provider is Quad9 (filtered, DNSSEC) * The DNS provider is Quad9 (filtered, DNSSEC)
- Steven Black's Unified Hosts List is included * Steven Black's Unified Hosts List is included
- Query logging is enabled to show everything. * Query logging is enabled to show everything.
### Torified Pi-Hole ### Torified Pi-Hole
If you want to combine Pi-Hole with Tor, then you should reconfigure your 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: 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 ### Local DNS server
If you want sys-pihole to use itself to resolve DNS queries, enable the If you want sys-pihole to use itself to resolve DNS queries, enable the
service `local-dns-server` from Dom0 to sys-pihole: service `local-dns-server` from Dom0 to sys-pihole:
```sh ```sh
qvm-features sys-pihole service.local-dns-server 1 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, If you encounter problems with DNS after having upstream netvm route changes,
restart Pi-hole DNS from sys-pihole: restart Pi-hole DNS from sys-pihole:
```sh ```sh
pihole restartdns pihole restartdns
``` ```
## Credits ## Credits
- [Patrizio Tufarolo](https://blog.tufarolo.eu/how-to-configure-pihole-in-qubesos-proxyvm/) * [Patrizio Tufarolo](https://blog.tufarolo.eu/how-to-configure-pihole-in-qubesos-proxyvm/)
- [Unman](https://github.com/unman/shaker/tree/main/pihole) * [Unman](https://github.com/unman/shaker/tree/main/pihole)

20
salt/sys-print/README.md
View File

@ -40,7 +40,8 @@ qube that has access to the printer.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-print sudo qubesctl top.enable sys-print
sudo qubesctl --targets=tpl-sys-print state.apply 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 sudo qubesctl state.apply sys-print.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-print.create sudo qubesctl state.apply sys-print.create
sudo qubesctl --skip-dom0 --targets=tpl-sys-print state.apply sys-print.install sudo qubesctl --skip-dom0 --targets=tpl-sys-print state.apply sys-print.install
sudo qubesctl state.apply sys-print.appmenus sudo qubesctl state.apply sys-print.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
If you want to install all printer drivers: If you want to install all printer drivers:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-sys-print state.apply sys-print.install-driver-all sudo qubesctl --skip-dom0 --targets=tpl-sys-print state.apply sys-print.install-driver-all
``` ```
On the client template: On the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-print.install-client sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-print.install-client
``` ```
The client qube requires the split Print service to be enabled: The client qube requires the split Print service to be enabled:
```sh ```sh
qvm-features QUBE service.print-client 1 qvm-features QUBE service.print-client 1
``` ```
@ -76,21 +83,23 @@ qvm-features QUBE service.print-client 1
**_Default policy_** (qusal.Print RPC service): **_Default policy_** (qusal.Print RPC service):
- Clients with tag `print-client` are `allowed` to call servers with tag * Clients with tag `print-client` are `allowed` to call servers with tag
`print-server`, defaulting to `sys-print`. `print-server`, defaulting to `sys-print`.
- `All` clients can `ask` servers with tag `print-server`, defaulting to * `All` clients can `ask` servers with tag `print-server`, defaulting to
`sys-print`. `sys-print`.
`Asking` can spawn multiple requests depending on the client, usage of `allow` `Asking` can spawn multiple requests depending on the client, usage of `allow`
is recommended for trusted clients. is recommended for trusted clients.
Add the tag `print-client` to the qube requesting the print content: Add the tag `print-client` to the qube requesting the print content:
```sh ```sh
qvm-tags QUBE add print-client qvm-tags QUBE add print-client
``` ```
As the call will default to `sys-print`, you can enforce the use of As the call will default to `sys-print`, you can enforce the use of
`disp-sys-print` via policy and not any other qube: `disp-sys-print` via policy and not any other qube:
```qrexecpolicy ```qrexecpolicy
qusal.Print * @tag:print-client @default allow target=disp-sys-print qusal.Print * @tag:print-client @default allow target=disp-sys-print
qusal.Print * @tag:print-client @anyvm deny 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`. configuration, use `disp-sys-print`.
On `sys-print` or `disp-sys-print`, add your printer: On `sys-print` or `disp-sys-print`, add your printer:
```sh ```sh
system-config-printer system-config-printer
``` ```
@ -116,4 +126,4 @@ browser and target the desired printer.
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/tree/main/sys-print) * [Unman](https://github.com/unman/shaker/tree/main/sys-print)

17
salt/sys-rsync/README.md
View File

@ -26,29 +26,35 @@ the user.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-rsync sudo qubesctl top.enable sys-rsync
sudo qubesctl --targets=tpl-sys-rsync,sys-rsync state.apply sudo qubesctl --targets=tpl-sys-rsync,sys-rsync state.apply
sudo qubesctl top.disable sys-rsync sudo qubesctl top.disable sys-rsync
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-rsync.create 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=tpl-sys-rsync state.apply sys-rsync.install
sudo qubesctl --skip-dom0 --targets=sys-rsync state.apply sys-rsync.configure sudo qubesctl --skip-dom0 --targets=sys-rsync state.apply sys-rsync.configure
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Install on the client template: Install on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-rsync.install-client sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-rsync.install-client
``` ```
The client qube requires the Rsync forwarder service to be enabled: The client qube requires the Rsync forwarder service to be enabled:
```
```sh
qvm-features QUBE service.rsync-client 1 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 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 `/etc/qubes/policy.d/30-user.policy` to allow the service using the following
format: format:
```qrexecpolicy ```qrexecpolicy
qusal.Rsync * SOURCE @default allow target=TARGET 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`. The Rsync connection is available with the socket `localhost:1839`.
Rsync the server `shared` read/write directory: Rsync the server `shared` read/write directory:
```sh ```sh
rsync --port=1839 localhost::shared /LOCAL/PATH/TO/RSYNC rsync --port=1839 localhost::shared /LOCAL/PATH/TO/RSYNC
``` ```
Rsync the server `archive` read-only directory: Rsync the server `archive` read-only directory:
```sh ```sh
rsync --port=1839 localhost::archive /LOCAL/PATH/TO/RSYNC rsync --port=1839 localhost::archive /LOCAL/PATH/TO/RSYNC
``` ```
## Credits ## Credits
- [Unman](https://github.com/unman/qubes-sync) * [Unman](https://github.com/unman/qubes-sync)

31
salt/sys-ssh-agent/README.md
View File

@ -52,23 +52,28 @@ A rogue client has full control of the allowed agent, therefore it can:
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-ssh-agent sudo qubesctl top.enable sys-ssh-agent
sudo qubesctl --targets=tpl-sys-ssh-agent,sys-ssh-agent state.apply sudo qubesctl --targets=tpl-sys-ssh-agent,sys-ssh-agent state.apply
sudo qubesctl top.disable sys-ssh-agent sudo qubesctl top.disable sys-ssh-agent
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-ssh-agent.create 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=tpl-sys-ssh-agent state.apply sys-ssh-agent.install
sudo qubesctl --skip-dom0 --targets=sys-ssh-agent state.apply sys-ssh-agent.configure sudo qubesctl --skip-dom0 --targets=sys-ssh-agent state.apply sys-ssh-agent.configure
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Installation on the client template: Installation on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-ssh-agent.install-client 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. for doing so.
Allow access to the specified agent based on the qube tag: Allow access to the specified agent based on the qube tag:
```qrexecpolicy ```qrexecpolicy
qusal.SshAgent +work @tag:work @default allow target=sys-ssh-agent qusal.SshAgent +work @tag:work @default allow target=sys-ssh-agent
qusal.SshAgent +work @anyvm @anyvm deny 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: Ask access from `untrusted` qubes to the untrusted agent:
```qrexecpolicy ```qrexecpolicy
qusal.SshAgent +untrusted untrusted @default ask target=sys-ssh-agent default_target=sys-ssh-agent qusal.SshAgent +untrusted untrusted @default ask target=sys-ssh-agent default_target=sys-ssh-agent
qusal.SshAgent +untrusted @anyvm @anyvm deny 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 ```qrexecpolicy
qusal.SshAgent +trusted trusted @default ask target=sys-ssh-agent-trusted default_target=sys-ssh-agent-trusted qusal.SshAgent +trusted trusted @default ask target=sys-ssh-agent-trusted default_target=sys-ssh-agent-trusted
qusal.SshAgent +trusted @anyvm @anyvm deny qusal.SshAgent +trusted @anyvm @anyvm deny
``` ```
Always recommended to end with an explicit deny rule: Always recommended to end with an explicit deny rule:
```qrexecpolicy ```qrexecpolicy
qusal.SshAgent * @anyvm @anyvm deny 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 Import preexisting keys to the agent directory or generate keys for a specific
agent: agent:
```sh ```sh
mkdir -m 0700 -p ~/.ssh/identities.d/<AGENT> mkdir -m 0700 -p ~/.ssh/identities.d/<AGENT>
ssh-keygen -t ed25519 -f ~/.ssh/identities.d/<AGENT>/id_example ssh-keygen -t ed25519 -f ~/.ssh/identities.d/<AGENT>/id_example
``` ```
You would do the following for the `work` agent: You would do the following for the `work` agent:
```sh ```sh
mkdir -m 0700 -p ~/.ssh/identities.d/work mkdir -m 0700 -p ~/.ssh/identities.d/work
ssh-keygen -t ed25519 -f ~/.ssh/identities.d/work/id_example 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 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`. `id_ed25519`, the option file should be named `id_ed25519.ssh-add-option`.
The `.ssh-add-option` file has the following format: The `.ssh-add-option` file has the following format:
```sh ```sh
# id_ed25519.ssh-add-option # id_ed25519.ssh-add-option
-q -t 600 -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 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 `~/.ssh/identities.d` directory so they aren't automatically added (substitute
AGENT, SECS, and LIFE for their appropriate values): AGENT, SECS, and LIFE for their appropriate values):
```sh ```sh
SSH_AUTH_SOCK="/run/user/1000/qusal-ssh-agent/<AGENT>.sock" ssh-add -t <SECS> -f <FILE> SSH_AUTH_SOCK="/run/user/1000/qusal-ssh-agent/<AGENT>.sock" ssh-add -t <SECS> -f <FILE>
``` ```
@ -158,6 +172,7 @@ SSH_AUTH_SOCK="/run/user/1000/qusal-ssh-agent/<AGENT>.sock" ssh-add -t <SECS> -f
The keys are added to the agent on the first call to that specific agent. 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 If you have added keys to the correct agent directory but haven't rebooted
yet, you will have to add the keys by executing: yet, you will have to add the keys by executing:
```sh ```sh
qvm-ssh-agent reload <AGENT> qvm-ssh-agent reload <AGENT>
qvm-ssh-agent reload work qvm-ssh-agent reload work
@ -166,6 +181,7 @@ qvm-ssh-agent reload work
#### Debug Agent side #### Debug Agent side
You can list agents and their keys with: You can list agents and their keys with:
```sh ```sh
qvm-ssh-agent ls <AGENT> qvm-ssh-agent ls <AGENT>
``` ```
@ -176,16 +192,19 @@ qvm-ssh-agent ls <AGENT>
Enable and start the connection to the SSH Agent via Qrexec for specified Enable and start the connection to the SSH Agent via Qrexec for specified
`<AGENT>`: `<AGENT>`:
```sh ```sh
sudo systemctl --no-block restart qusal-ssh-agent-forwarder@<AGENT>.service sudo systemctl --no-block restart qusal-ssh-agent-forwarder@<AGENT>.service
sudo systemctl --no-block restart qusal-ssh-agent-forwarder@personal.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 You can start the service on boot if you place the above line
`/rw/config/rc.local` of the client. `/rw/config/rc.local` of the client.
The ssh-agent socket will be at `/tmp/qusal-ssh-agent-forwarder/<AGENT>.sock`. The ssh-agent socket will be at `/tmp/qusal-ssh-agent-forwarder/<AGENT>.sock`.
You can test the connection is working with: You can test the connection is working with:
```sh ```sh
SSH_AUTH_SOCK="/tmp/qusal-ssh-agent-forwarder/personal.sock" ssh-add -l 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 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 variables to point to the `work` agent so every connection will use the same
agent: agent:
```sh ```sh
echo 'export SSH_AUTH_SOCK=/tmp/qusal-ssh-agent-forwarder/work.sock; echo 'export SSH_AUTH_SOCK=/tmp/qusal-ssh-agent-forwarder/work.sock;
SSH_AGENT_PID="$(pgrep -f "/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. the `IdentityAgent` option.
You can control the SSH agent via SSH command-line option: You can control the SSH agent via SSH command-line option:
```sh ```sh
ssh -o IdentityAgent=/tmp/qusal-ssh-agent-forwarder/personal.sock personal-site.com 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 ssh -o IdentityAgent=/tmp/qusal-ssh-agent-forwarder/work.sock work-site.com
``` ```
You can control the SSH agent via SSH configuration: You can control the SSH agent via SSH configuration:
```sshconfig ```sshconfig
Host personal Host personal
IdentityAgent /tmp/qusal-ssh-agent-forwarder/personal.sock IdentityAgent /tmp/qusal-ssh-agent-forwarder/personal.sock
@ -225,4 +248,4 @@ Host work
## Credits ## Credits
- [Unman](https://github.com/unman/qusal-ssh-agent) * [Unman](https://github.com/unman/qusal-ssh-agent)

16
salt/sys-ssh/README.md
View File

@ -27,28 +27,34 @@ server qube directly.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-ssh sudo qubesctl top.enable sys-ssh
sudo qubesctl --targets=tpl-sys-ssh,sys-ssh state.apply sudo qubesctl --targets=tpl-sys-ssh,sys-ssh state.apply
sudo qubesctl top.disable sys-ssh sudo qubesctl top.disable sys-ssh
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-ssh.create sudo qubesctl state.apply sys-ssh.create
sudo qubesctl --skip-dom0 --targets=tpl-sys-ssh state.apply sys-ssh.install sudo qubesctl --skip-dom0 --targets=tpl-sys-ssh state.apply sys-ssh.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Install on the client template: Install on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-ssh.install-client sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-ssh.install-client
``` ```
The client qube requires the SSH forwarder service to be enabled: The client qube requires the SSH forwarder service to be enabled:
```
```sh
qvm-features QUBE service.ssh-client 1 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 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 file `/etc/qubes/policy.d/30-user.policy` to allow the service using the
following format: following format:
```qrexecpolicy ```qrexecpolicy
qusal.Ssh * SOURCE @default allow target=TARGET 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 From the client, mount the server `/home/user` directory as a SSH File System
in the client `/home/user/sshfs` directory: in the client `/home/user/sshfs` directory:
```sh ```sh
mkdir ~/sshfs mkdir ~/sshfs
sshfs -p 1840 localhost:/home/user /home/user/sshfs sshfs -p 1840 localhost:/home/user /home/user/sshfs
@ -92,4 +100,4 @@ sshfs -p 1840 localhost:/home/user /home/user/sshfs
## Credits ## Credits
- [Unman](https://github.com/unman/qubes-sync) * [Unman](https://github.com/unman/qubes-sync)

18
salt/sys-syncthing/README.md
View File

@ -23,7 +23,8 @@ accessible externally.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-syncthing browser sudo qubesctl top.enable sys-syncthing browser
sudo qubesctl --targets=tpl-browser,sys-syncthing-browser,tpl-sys-syncthing,sys-syncthing state.apply 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 qvm-port-forward -a add -q sys-syncthing -n udp -p 22000
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-syncthing.create sudo qubesctl state.apply sys-syncthing.create
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install 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 tcp -p 22000
qvm-port-forward -a add -q sys-syncthing -n udp -p 22000 qvm-port-forward -a add -q sys-syncthing -n udp -p 22000
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Install Syncthing on the client template: Install Syncthing on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-syncthing.install-client sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-syncthing.install-client
``` ```
The client qube requires the split Syncthing and the Syncthing Daemon service The client qube requires the split Syncthing and the Syncthing Daemon service
to be enabled: to be enabled:
```sh ```sh
qvm-features QUBE service.syncthing-client 1 qvm-features QUBE service.syncthing-client 1
qvm-features QUBE service.syncthing-server 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 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 `/etc/qubes/policy.d/30-user.policy` to allow the service using the following
format: format:
```qrexecpolicy ```qrexecpolicy
qusal.Syncthing * SOURCE @default allow target=DESTINATION default_target=DEFAULT_DESTINATION 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 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 used by default. If this is incorrect, you must change it manually. In Dom0
run: run:
```sh ```sh
qvm-port-forward -a del -q sys-syncthing -n udp -p 22000 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 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 udp -p 22000
qvm-port-forward -a add -q sys-syncthing -n tcp -p 22000 qvm-port-forward -a add -q sys-syncthing -n tcp -p 22000
``` ```
This will let you choose the NIC. This will let you choose the NIC.
## Uninstallation ## Uninstallation
@ -110,14 +119,17 @@ must manually revert them. The Qrexec policy will be reverted to stop
Syncthing between qubes. Syncthing between qubes.
Uninstallation procedure: Uninstallation procedure:
<!-- pkg:begin:preun-uninstall --> <!-- pkg:begin:preun-uninstall -->
```sh ```sh
qvm-port-forward -a del -q sys-syncthing -n tcp -p 22000 qvm-port-forward -a del -q sys-syncthing -n tcp -p 22000
qvm-port-forward -a del -q sys-syncthing -n udp -p 22000 qvm-port-forward -a del -q sys-syncthing -n udp -p 22000
sudo qubesctl state.apply sys-syncthing.clean sudo qubesctl state.apply sys-syncthing.clean
``` ```
<!-- pkg:end:preun-uninstall --> <!-- pkg:end:preun-uninstall -->
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/tree/main/syncthing) * [Unman](https://github.com/unman/shaker/tree/main/syncthing)

60
salt/sys-usb/README.md
View File

@ -24,24 +24,29 @@ the USB controllers to different qubes is possible.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-usb sudo qubesctl top.enable sys-usb
sudo qubesctl --targets=tpl-sys-usb state.apply sudo qubesctl --targets=tpl-sys-usb state.apply
sudo qubesctl top.disable sys-usb sudo qubesctl top.disable sys-usb
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-usb.create sudo qubesctl state.apply sys-usb.create
sudo qubesctl --skip-dom0 --targets=tpl-sys-usb state.apply sys-usb.install sudo qubesctl --skip-dom0 --targets=tpl-sys-usb state.apply sys-usb.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
### Keyboard installation ### Keyboard installation
If you use an USB keyboard, also run: If you use an USB keyboard, also run:
```sh ```sh
sudo qubesctl state.apply sys-usb.keyboard sudo qubesctl state.apply sys-usb.keyboard
``` ```
@ -49,13 +54,16 @@ sudo qubesctl state.apply sys-usb.keyboard
### AudioVM installation ### AudioVM installation
If you plan to use `disp-sys-usb` as an AudioVM: If you plan to use `disp-sys-usb` as an AudioVM:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=tpl-sys-usb state.apply sys-audio.install 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 sudo qubesctl --skip-dom0 --targets=dvm-sys-usb state.apply sys-audio.configure-dvm
qvm-tags disp-sys-usb add audiovm qvm-tags disp-sys-usb add audiovm
qvm-features disp-sys-usb service.audiovm 1 qvm-features disp-sys-usb service.audiovm 1
``` ```
And set the qube preference `audiovm` to `disp-sys-usb`: And set the qube preference `audiovm` to `disp-sys-usb`:
```sh ```sh
qvm-prefs QUBE audiovm disp-sys-usb qvm-prefs QUBE audiovm disp-sys-usb
``` ```
@ -65,6 +73,7 @@ qvm-prefs QUBE audiovm disp-sys-usb
#### Client USB proxy installation #### Client USB proxy installation
Install the proxy on the client template: Install the proxy on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-proxy 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 #### Client cryptsetup installation
If the client requires decrypting a device, install on the client template: If the client requires decrypting a device, install on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-cryptsetup 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 #### Client CTAP installation
If the client requires a CTAP device, install on the client template: If the client requires a CTAP device, install on the client template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-fido sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-fido
``` ```
And enable the CTAP Proxy service for the client qubes: And enable the CTAP Proxy service for the client qubes:
```sh ```sh
qvm-features QUBE service.qubes-ctap-proxy 1 qvm-features QUBE service.qubes-ctap-proxy 1
``` ```
@ -91,8 +104,9 @@ qvm-features QUBE service.qubes-ctap-proxy 1
No extra services are implemented, consult upstream to learn how to use the No extra services are implemented, consult upstream to learn how to use the
following services: following services:
- `qubes.InputMouse`, `qubes.InputKeyboard`, `qubes.InputTablet`;
- `ctap.GetInfo`, `ctap.ClientPin`, `u2f.Register`, `u2f.Authenticate`, * `qubes.InputMouse`, `qubes.InputKeyboard`, `qubes.InputTablet`;
* `ctap.GetInfo`, `ctap.ClientPin`, `u2f.Register`, `u2f.Authenticate`,
`policy.RegisterArgument`. `policy.RegisterArgument`.
## Usage ## Usage
@ -115,31 +129,31 @@ Built-in microphones on the other hand, are directly attached to `dom0`.
To use these devices, there are two options: To use these devices, there are two options:
1. Attaching the device (USB passthrough) to the audio client: 1. Attaching the device (USB passthrough) to the audio client:
- Advantages: * Advantages:
- Easier setup as it doesn't require an AudioVM. * Easier setup as it doesn't require an AudioVM.
- Disadvantages: * Disadvantages:
- Increased latency; * Increased latency;
- Only one qube can use the device; and * Only one qube can use the device; and
- Less secure as it exposes the Audio stack to the client. * Less secure as it exposes the Audio stack to the client.
2. Leaving devices to the AudioVM (`(disp-)sys-usb` as AudioVM): 2. Leaving devices to the AudioVM (`(disp-)sys-usb` as AudioVM):
- Advantages: * Advantages:
- More secure as the devices are not on the client; * More secure as the devices are not on the client;
- Less latency; and * Less latency; and
- All audio clients will have the same audio capabilities. * All audio clients will have the same audio capabilities.
- Disadvantages: * Disadvantages:
- Some applications might not work due to not finding the device. * Some applications might not work due to not finding the device.
3. Using [video-companion](../video-companion/README.md) to access webcam: 3. Using [video-companion](../video-companion/README.md) to access webcam:
- Advantages: * Advantages:
- The most secure for client and server as the physical devices are * The most secure for client and server as the physical devices are
unmanaged; unmanaged;
- Least latency. * Least latency.
- Disadvantages: * Disadvantages:
- Can't use video-companion to screen share and share webcam at the * Can't use video-companion to screen share and share webcam at the
same time; and same time; and
- Does not cover audio. * Does not cover audio.
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/blob/main/sys-usb) * [Unman](https://github.com/unman/shaker/blob/main/sys-usb)

10
salt/sys-wireguard/README.md
View File

@ -16,20 +16,24 @@ other qubes through the VPN with fail closed mechanism.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable sys-wireguard sudo qubesctl top.enable sys-wireguard
sudo qubesctl --targets=tpl-sys-wireguard,sys-wireguard state.apply sudo qubesctl --targets=tpl-sys-wireguard,sys-wireguard state.apply
sudo qubesctl top.disable sys-wireguard sudo qubesctl top.disable sys-wireguard
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply sys-wireguard.create 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=tpl-sys-wireguard state.apply sys-wireguard.install
sudo qubesctl --skip-dom0 --targets=sys-wireguard state.apply sys-wireguard.configure sudo qubesctl --skip-dom0 --targets=sys-wireguard state.apply sys-wireguard.configure
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage
@ -45,4 +49,4 @@ To start using the VPN:
## Credits ## Credits
- [Unman](https://github.com/unman/shaker/tree/main/mullvad) * [Unman](https://github.com/unman/shaker/tree/main/mullvad)

8
salt/terraform/README.md
View File

@ -14,19 +14,23 @@ Install Terraform and use it on the "terraform" app qube.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable terraform sudo qubesctl top.enable terraform
sudo qubesctl --targets=tpl-terraform state.apply sudo qubesctl --targets=tpl-terraform state.apply
sudo qubesctl top.disable terraform sudo qubesctl top.disable terraform
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply terraform.create sudo qubesctl state.apply terraform.create
sudo qubesctl --skip-dom0 --targets=tpl-terraform state.apply terraform.install sudo qubesctl --skip-dom0 --targets=tpl-terraform state.apply terraform.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/usb/README.md
View File

@ -15,19 +15,23 @@ you can base disposable qubes, geared towards USB client usage.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable usb sudo qubesctl top.enable usb
sudo qubesctl --targets=tpl-usb state.apply sudo qubesctl --targets=tpl-usb state.apply
sudo qubesctl top.disable usb sudo qubesctl top.disable usb
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply usb.create sudo qubesctl state.apply usb.create
sudo qubesctl --skip-dom0 --targets=tpl-usb state.apply usb.install sudo qubesctl --skip-dom0 --targets=tpl-usb state.apply usb.install
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

3
salt/utils/tools/builder/README.md
View File

@ -16,10 +16,13 @@ building packages in UNIX distributions.
## Installation ## Installation
Install builder tools on templates: Install builder tools on templates:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS state.apply utils.tools.builder.core sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS state.apply utils.tools.builder.core
``` ```
Install documentation tools on templates: Install documentation tools on templates:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS state.apply utils.tools.builder.doc sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS state.apply utils.tools.builder.doc
``` ```

8
salt/utils/tools/zsh/README.md
View File

@ -15,19 +15,23 @@ warnings.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable utils.tools.zsh sudo qubesctl top.enable utils.tools.zsh
sudo qubesctl --targets=TARGET state.apply sudo qubesctl --targets=TARGET state.apply
sudo qubesctl top.disable utils.tools.zsh sudo qubesctl top.disable utils.tools.zsh
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl --skip-dom0 --targets=TEMPLATEVMS state.apply utils.tools.zsh.change-shell 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 sudo qubesctl --skip-dom0 --targets=APPVMS state.apply utils.tools.zsh.touch-zshrc
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/vault/README.md
View File

@ -16,7 +16,8 @@ keys.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable vault sudo qubesctl top.enable vault
sudo qubesctl --targets=tpl-vault state.apply sudo qubesctl --targets=tpl-vault state.apply
@ -24,13 +25,16 @@ sudo qubesctl top.disable vault
sudo qubesctl state.apply vault.appmenus sudo qubesctl state.apply vault.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply vault.create sudo qubesctl state.apply vault.create
sudo qubesctl --skip-dom0 --targets=tpl-vault state.apply vault.install sudo qubesctl --skip-dom0 --targets=tpl-vault state.apply vault.install
sudo qubesctl state.apply vault.appmenus sudo qubesctl state.apply vault.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

15
salt/video-companion/README.md
View File

@ -16,32 +16,38 @@ access them without compromising the domains.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable video-companion sudo qubesctl top.enable video-companion
sudo qubesctl state.apply sudo qubesctl state.apply
sudo qubesctl top.disable video-companion sudo qubesctl top.disable video-companion
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply video-companion.create sudo qubesctl state.apply video-companion.create
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
Installation on the server (sender) template: Installation on the server (sender) template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=QUBE state.apply video-companion.install-sender sudo qubesctl --skip-dom0 --targets=QUBE state.apply video-companion.install-sender
``` ```
Installation on the client (receiver) template: Installation on the client (receiver) template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=QUBE state.apply video-companion.install-receiver sudo qubesctl --skip-dom0 --targets=QUBE state.apply video-companion.install-receiver
``` ```
Installation for debugging on the client (receiver) template: Installation for debugging on the client (receiver) template:
```sh ```sh
sudo qubesctl --skip-dom0 --targets=QUBE state.apply video-companion.install-receiver-debug 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. therefore the client is responsible to initiate the call.
On the client, to get the screen of another qube: On the client, to get the screen of another qube:
```sh ```sh
qubes-video-companion screenshare qubes-video-companion screenshare
``` ```
On the client, to get the webcam of another qube: On the client, to get the webcam of another qube:
```sh ```sh
qubes-video-companion webcam qubes-video-companion webcam
``` ```
On the client, if you installed the debug utilities, call cheese to access the On the client, if you installed the debug utilities, call cheese to access the
shared screen or webcam: shared screen or webcam:
```sh ```sh
cheese cheese
``` ```

8
salt/whonix-gateway/README.md
View File

@ -15,7 +15,8 @@ it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable whonix-gateway sudo qubesctl top.enable whonix-gateway
sudo qubesctl --targets=whonix-gateway-17 state.apply 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 sudo qubesctl state.apply whonix-gateway.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply whonix-gateway.create sudo qubesctl state.apply whonix-gateway.create
sudo qubesctl --skip-dom0 --targets=whonix-gateway-17 state.apply whonix-gateway.install sudo qubesctl --skip-dom0 --targets=whonix-gateway-17 state.apply whonix-gateway.install
sudo qubesctl state.apply whonix-gateway.appmenus sudo qubesctl state.apply whonix-gateway.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

8
salt/whonix-workstation/README.md
View File

@ -15,7 +15,8 @@ based on it.
## Installation ## Installation
- Top: * Top:
```sh ```sh
sudo qubesctl top.enable whonix-workstation sudo qubesctl top.enable whonix-workstation
sudo qubesctl --targets=whonix-workstation-17 state.apply 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 sudo qubesctl state.apply whonix-workstation.appmenus
``` ```
- State: * State:
<!-- pkg:begin:post-install --> <!-- pkg:begin:post-install -->
```sh ```sh
sudo qubesctl state.apply whonix-workstation.create sudo qubesctl state.apply whonix-workstation.create
sudo qubesctl --skip-dom0 --targets=whonix-workstation-17 state.apply whonix-workstation.install sudo qubesctl --skip-dom0 --targets=whonix-workstation-17 state.apply whonix-workstation.install
sudo qubesctl state.apply whonix-workstation.appmenus sudo qubesctl state.apply whonix-workstation.appmenus
``` ```
<!-- pkg:end:post-install --> <!-- pkg:end:post-install -->
## Usage ## Usage

41
scripts/markdown-lint.sh Executable file
View File

@ -0,0 +1,41 @@
#!/bin/sh
## SPDX-FileCopyrightText: 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
##
## 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}

5
scripts/salt-lint.sh
View File

@ -7,11 +7,10 @@
# shellcheck disable=SC2086 # shellcheck disable=SC2086
set -eu set -eu
command -v salt-lint >/dev/null ||
{ printf >&2 "Missing program: salt-lint\n"; exit 1; }
command -v git >/dev/null || command -v git >/dev/null ||
{ printf "Missing program: git\n" >&2; exit 1; } { printf "Missing program: git\n" >&2; exit 1; }
cd "$(git rev-parse --show-toplevel)" || exit 1 cd "$(git rev-parse --show-toplevel)" || exit 1
./scripts/requires-program.sh salt-lint
possible_conf="${PWD}/.salt-lint" possible_conf="${PWD}/.salt-lint"
conf="" conf=""
@ -28,7 +27,7 @@ if test -n "${1-}"; then
files="" files=""
for f in "$@"; do for f in "$@"; do
test -f "$f" || continue test -f "$f" || continue
extension="$(echo "$f" | awk -F '.' '{print $NF}')" extension="${f##*.}"
case "$extension" in case "$extension" in
top|sls) files="$files $f";; top|sls) files="$files $f";;
*) continue;; *) continue;;

2
scripts/spec-gen.sh
View File

@ -29,7 +29,7 @@ get_scriptlet(){
scriptlet="$1" scriptlet="$1"
scriptlet="$(sed -n \ scriptlet="$(sed -n \
"/^<\!-- pkg:begin:${scriptlet} -->$/,/^<\!-- pkg:end:${scriptlet} -->$/p" \ "/^<\!-- 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 if test -z "${scriptlet}"; then
echo true echo true
return 0 return 0

3
scripts/spec-get.sh
View File

@ -106,7 +106,8 @@ fi
if test "${key}" = "summary"; then if test "${key}" = "summary"; then
summary="$(sed -n "/^# ${name}$/,/^## Table of Contents$/{ summary="$(sed -n "/^# ${name}$/,/^## Table of Contents$/{
/./!d; /^#/d; s/\.$//; p}" -- "${readme}")" /./!d; /^#/d; /^SPDX/d; /^<!--/d; /^-->/d; s/\.$//; p}" \
-- "${readme}")"
block_max_chars summary "${summary}" 70 block_max_chars summary "${summary}" 70
fi fi