mirror of
https://github.com/ben-grande/qusal.git
synced 2025-08-07 21:52:29 -04:00
doc: lint markdown files
Only way to have a unified markdown syntax is to enforce the wanted syntax by linting the files. Don't rely on the many markdown syntaxes, be consistent.
This commit is contained in:
Ben Grande
parent
88d9ba525c
commit
383c840f2f
68 changed files with 1297 additions and 815 deletions
|
|
@ -4,12 +4,12 @@ Qusal bootstrap strategy.
|
|||
|
||||
## Table of Contents
|
||||
|
||||
* [Description](#description)
|
||||
* [Essential](#essential)
|
||||
* [Optional](#optional)
|
||||
* [Internet communication](#internet-communication)
|
||||
* [Files](#files)
|
||||
* [Admin](#admin)
|
||||
* [Description](#description)
|
||||
* [Essential](#essential)
|
||||
* [Optional](#optional)
|
||||
* [Internet communication](#internet-communication)
|
||||
* [Files](#files)
|
||||
* [Admin](#admin)
|
||||
|
||||
## Description
|
||||
|
||||
|
|
@ -22,75 +22,75 @@ matter in some circumstances, in those cases, it is noted in this page.
|
|||
|
||||
## Essential
|
||||
|
||||
- Base (order matters):
|
||||
- [dom0](../salt/dom0/README.md)
|
||||
- [debian-minimal](../salt/debian-minimal/README.md)
|
||||
- [fedora-minimal](../salt/fedora-minimal/README.md)
|
||||
- [mgmt](../salt/mgmt/README.md)
|
||||
- [sys-cacher](../salt/sys-cacher/README.md)
|
||||
* Base (order matters):
|
||||
* [dom0](../salt/dom0/README.md)
|
||||
* [debian-minimal](../salt/debian-minimal/README.md)
|
||||
* [fedora-minimal](../salt/fedora-minimal/README.md)
|
||||
* [mgmt](../salt/mgmt/README.md)
|
||||
* [sys-cacher](../salt/sys-cacher/README.md)
|
||||
|
||||
## Optional
|
||||
|
||||
### Internet communication
|
||||
|
||||
- PCI devices holders:
|
||||
- [sys-net](../salt/sys-net/README.md)
|
||||
- [sys-audio](../salt/sys-audio/README.md)
|
||||
- [sys-usb](../salt/sys-usb/README.md)
|
||||
* PCI devices holders:
|
||||
* [sys-net](../salt/sys-net/README.md)
|
||||
* [sys-audio](../salt/sys-audio/README.md)
|
||||
* [sys-usb](../salt/sys-usb/README.md)
|
||||
|
||||
- Firewall, DNS Sinkhole and VPN Tunnel:
|
||||
- [sys-firewall](../salt/sys-firewall/README.md)
|
||||
- [sys-mirage-firewall](../salt/sys-mirage-firewall/README.md)
|
||||
- [sys-pihole](../salt/sys-pihole/README.md)
|
||||
- [sys-wireguard](../salt/sys-wireguard/README.md)
|
||||
* Firewall, DNS Sinkhole and VPN Tunnel:
|
||||
* [sys-firewall](../salt/sys-firewall/README.md)
|
||||
* [sys-mirage-firewall](../salt/sys-mirage-firewall/README.md)
|
||||
* [sys-pihole](../salt/sys-pihole/README.md)
|
||||
* [sys-wireguard](../salt/sys-wireguard/README.md)
|
||||
|
||||
- Web browser and file retriever:
|
||||
- [browser](../salt/browser/README.md)
|
||||
- [fetcher](../salt/fetcher/README.md)
|
||||
* Web browser and file retriever:
|
||||
* [browser](../salt/browser/README.md)
|
||||
* [fetcher](../salt/fetcher/README.md)
|
||||
|
||||
- Instant messaging and E-Mail:
|
||||
- [mail](../salt/mail/README.md)
|
||||
- [signal](../salt/signal/README.md)
|
||||
- [element](../salt/element/README.md)
|
||||
* Instant messaging and E-Mail:
|
||||
* [mail](../salt/mail/README.md)
|
||||
* [signal](../salt/signal/README.md)
|
||||
* [element](../salt/element/README.md)
|
||||
|
||||
- Electronic cash:
|
||||
- [sys-bitcoin](../salt/sys-bitcoin/README.md)
|
||||
- [sys-electrumx](../salt/sys-electrumx/README.md)
|
||||
- [sys-electrs](../salt/sys-electrs/README.md)
|
||||
- [electrum](../salt/electrum/README.md)
|
||||
* Electronic cash:
|
||||
* [sys-bitcoin](../salt/sys-bitcoin/README.md)
|
||||
* [sys-electrumx](../salt/sys-electrumx/README.md)
|
||||
* [sys-electrs](../salt/sys-electrs/README.md)
|
||||
* [electrum](../salt/electrum/README.md)
|
||||
|
||||
### Files
|
||||
|
||||
- Passwords and TOTP:
|
||||
- [vault](../salt/vault/README.md)
|
||||
* Passwords and TOTP:
|
||||
* [vault](../salt/vault/README.md)
|
||||
|
||||
- Multimedia:
|
||||
- [reader](../salt/reader/README.md)
|
||||
- [media](../salt/media/README.md)
|
||||
- [sys-print](../salt/sys-print/README.md)
|
||||
- [video-companion](../salt/video-companion/README.md)
|
||||
* Multimedia:
|
||||
* [reader](../salt/reader/README.md)
|
||||
* [media](../salt/media/README.md)
|
||||
* [sys-print](../salt/sys-print/README.md)
|
||||
* [video-companion](../salt/video-companion/README.md)
|
||||
|
||||
- File sharing:
|
||||
- [usb](../salt/usb/README.md)
|
||||
- [sys-ssh](../salt/sys-ssh/README.md)
|
||||
- [sys-syncthing](../salt/sys-syncthing/README.md)
|
||||
- [sys-rsync](../salt/sys-rsync/README.md)
|
||||
* File sharing:
|
||||
* [usb](../salt/usb/README.md)
|
||||
* [sys-ssh](../salt/sys-ssh/README.md)
|
||||
* [sys-syncthing](../salt/sys-syncthing/README.md)
|
||||
* [sys-rsync](../salt/sys-rsync/README.md)
|
||||
|
||||
### Admin
|
||||
|
||||
- Remote administration:
|
||||
- [remmina](../salt/remmina/README.md)
|
||||
- [ssh](../salt/ssh/README.md)
|
||||
- [sys-ssh-agent](../salt/sys-ssh-agent/README.md)
|
||||
* Remote administration:
|
||||
* [remmina](../salt/remmina/README.md)
|
||||
* [ssh](../salt/ssh/README.md)
|
||||
* [sys-ssh-agent](../salt/sys-ssh-agent/README.md)
|
||||
|
||||
- Remote task execution and configuration management:
|
||||
- [ansible](../salt/ansible/README.md)
|
||||
- [docker](../salt/docker/README.md)
|
||||
- [opentofu](../salt/opentofu/README.md)
|
||||
- [terraform](../salt/terraform/README.md)
|
||||
* Remote task execution and configuration management:
|
||||
* [ansible](../salt/ansible/README.md)
|
||||
* [docker](../salt/docker/README.md)
|
||||
* [opentofu](../salt/opentofu/README.md)
|
||||
* [terraform](../salt/terraform/README.md)
|
||||
|
||||
- Coding:
|
||||
- [dev](../salt/dev/README.md)
|
||||
- [sys-pgp](../salt/sys-pgp/README.md)
|
||||
- [sys-git](../salt/sys-git/README.md)
|
||||
- [sys-ssh-agent](../salt/sys-ssh-agent/README.md)
|
||||
* Coding:
|
||||
* [dev](../salt/dev/README.md)
|
||||
* [sys-pgp](../salt/sys-pgp/README.md)
|
||||
* [sys-git](../salt/sys-git/README.md)
|
||||
* [sys-ssh-agent](../salt/sys-ssh-agent/README.md)
|
||||
|
|
|
|||
|
|
@ -4,11 +4,11 @@ Qusal contribution guidelines.
|
|||
|
||||
## Table of Contents
|
||||
|
||||
* [Respect](#respect)
|
||||
* [Starters](#starters)
|
||||
* [Environment](#environment)
|
||||
* [Issues](#issues)
|
||||
* [Lint](#lint)
|
||||
* [Respect](#respect)
|
||||
* [Starters](#starters)
|
||||
* [Environment](#environment)
|
||||
* [Issues](#issues)
|
||||
* [Lint](#lint)
|
||||
|
||||
## Respect
|
||||
|
||||
|
|
@ -50,31 +50,32 @@ packages below depending on the task:
|
|||
|
||||
General:
|
||||
|
||||
- git
|
||||
* git
|
||||
|
||||
For writing:
|
||||
|
||||
- editorconfig
|
||||
- editorconfig plugin for your editor
|
||||
- vim, [vim-jinja](https://github.com/ben-grande/vim-jinja),
|
||||
[vim-salt](https://github.com/ben-grande/vim-salt) (recommended)
|
||||
* editorconfig
|
||||
* editorconfig plugin for your editor
|
||||
* vim, [vim-jinja](https://github.com/ben-grande/vim-jinja),
|
||||
[vim-salt](https://github.com/ben-grande/vim-salt) (recommended)
|
||||
|
||||
For linting:
|
||||
|
||||
- pre-commit
|
||||
- gitlint
|
||||
- salt-lint
|
||||
- shellcheck
|
||||
- reuse
|
||||
* gitlint
|
||||
* markdownlint (ruby-mdl)
|
||||
* pre-commit
|
||||
* reuse
|
||||
* salt-lint
|
||||
* shellcheck
|
||||
|
||||
For building RPMs:
|
||||
|
||||
- sed (GNU sed)
|
||||
- dnf
|
||||
- dnf-plugins-core (dnf builddep)
|
||||
- rpm
|
||||
- rpmlint
|
||||
- rpmautospec (only available in Fedora)
|
||||
* sed (GNU sed)
|
||||
* dnf
|
||||
* dnf-plugins-core (dnf builddep)
|
||||
* rpm
|
||||
* rpmlint
|
||||
* rpmautospec (only available in Fedora)
|
||||
|
||||
## Issues
|
||||
|
||||
|
|
@ -90,12 +91,14 @@ already been sent, the maintainer has already read and both parties loses
|
|||
time.
|
||||
|
||||
Install the local hooks:
|
||||
|
||||
```sh
|
||||
pre-commit install
|
||||
gitlint install-hook
|
||||
```
|
||||
|
||||
To run pre-commit linters:
|
||||
|
||||
```sh
|
||||
pre-commit run
|
||||
```
|
||||
|
|
|
|||
306
docs/DESIGN.md
306
docs/DESIGN.md
|
|
@ -4,27 +4,27 @@ Qusal design document.
|
|||
|
||||
## Table of Contents
|
||||
|
||||
* [Goal](#goal)
|
||||
* [Documentation](#documentation)
|
||||
* [Format](#format)
|
||||
* [Readme](#readme)
|
||||
* [Access Control](#access-control)
|
||||
* [State file naming](#state-file-naming)
|
||||
* [State ID](#state-id)
|
||||
* [Qube preferences](#qube-preferences)
|
||||
* [Qube naming](#qube-naming)
|
||||
* [Qube label](#qube-label)
|
||||
* [Qube menu](#qube-menu)
|
||||
* [Qube features](#qube-features)
|
||||
* [Qube connections](#qube-connections)
|
||||
* [Qrexec call and policy](#qrexec-call-and-policy)
|
||||
* [Qrexec socket services](#qrexec-socket-services)
|
||||
* [Features](#features)
|
||||
* [Browser isolation from the managed service](#browser-isolation-from-the-managed-service)
|
||||
* [Release new version](#release-new-version)
|
||||
* [Qubes OS major release upgrade](#qubes-os-major-release-upgrade)
|
||||
* [Template major release upgrade](#template-major-release-upgrade)
|
||||
* [Archive or Build from source major release upgrade](#archive-or-build-from-source-major-release-upgrade)
|
||||
* [Goal](#goal)
|
||||
* [Documentation](#documentation)
|
||||
* [Format](#format)
|
||||
* [Readme](#readme)
|
||||
* [Access Control](#access-control)
|
||||
* [State file naming](#state-file-naming)
|
||||
* [State ID](#state-id)
|
||||
* [Qube preferences](#qube-preferences)
|
||||
* [Qube naming](#qube-naming)
|
||||
* [Qube label](#qube-label)
|
||||
* [Qube menu](#qube-menu)
|
||||
* [Qube features](#qube-features)
|
||||
* [Qube connections](#qube-connections)
|
||||
* [Qrexec call and policy](#qrexec-call-and-policy)
|
||||
* [Qrexec socket services](#qrexec-socket-services)
|
||||
* [Features](#features)
|
||||
* [Browser isolation from the managed service](#browser-isolation-from-the-managed-service)
|
||||
* [Release new version](#release-new-version)
|
||||
* [Qubes OS major release upgrade](#qubes-os-major-release-upgrade)
|
||||
* [Template major release upgrade](#template-major-release-upgrade)
|
||||
* [Archive or Build from source major release upgrade](#archive-or-build-from-source-major-release-upgrade)
|
||||
|
||||
## Goal
|
||||
|
||||
|
|
@ -55,7 +55,8 @@ provided via extra states that needs to be installed per the user discretion.
|
|||
Markdown code must follow
|
||||
[Google's Markdown style guide](https://google.github.io/styleguide/docguide/style.html).
|
||||
Any discrepancies with Google's style guide must be fixed or documented here
|
||||
with clear motive.
|
||||
with clear motive. Although some of Google's style guide is optional, we
|
||||
enforce some for stylistic purpose via documentation lint tools.
|
||||
|
||||
Documentation must not duplicate itself, but reference one another.
|
||||
Reproducing instructions that can be found in upstream documentation is
|
||||
|
|
@ -69,19 +70,19 @@ modify the documentation constantly to keep up with upstream.
|
|||
|
||||
Every project should have a README.md with at least the following sections:
|
||||
|
||||
- Table of Contents;
|
||||
- Description;
|
||||
- Installation;
|
||||
- Access Control (if Qrexec policy changed);
|
||||
- Usage; and
|
||||
- Credits (if sourced).
|
||||
* Table of Contents;
|
||||
* Description;
|
||||
* Installation;
|
||||
* Access Control (if Qrexec policy changed);
|
||||
* Usage; and
|
||||
* Credits (if sourced).
|
||||
|
||||
#### Access Control
|
||||
|
||||
- It must document default policy and RPC services the user can or should
|
||||
edit.
|
||||
- It must not document RPC services of other formulas unless the resolution of
|
||||
the rule is `deny`.
|
||||
* It must document default policy and RPC services the user can or should
|
||||
edit.
|
||||
* It must not document RPC services of other formulas unless the resolution
|
||||
of the rule is `deny`.
|
||||
|
||||
### State file naming
|
||||
|
||||
|
|
@ -98,8 +99,8 @@ Every project should have a README.md with at least the following sections:
|
|||
|
||||
1. State IDs must use `-` as separator, not `_`. The underline is allowed in
|
||||
case the features it is changing has underline, such as `default_netvm`.
|
||||
2. State IDs must always have the project ID, thus allowing to target multiple
|
||||
states to the same minion from different projects without having
|
||||
2. State IDs must always have the project ID, thus allowing to target
|
||||
multiple states to the same minion from different projects without having
|
||||
conflicting IDs.
|
||||
|
||||
### Qube preferences
|
||||
|
|
@ -110,12 +111,12 @@ We differ from upstream especially by placing the `dvm` part as the prefix of
|
|||
DispVM Templates. This is to easy parsing when the qube type is the first
|
||||
part of its name and no exceptions.
|
||||
|
||||
- **TemplateVM**: `tpl-NAME`
|
||||
- **StandaloneVM**: `NAME`
|
||||
- **AppVM**: `NAME`
|
||||
- **DispVM**: `disp-NAME`
|
||||
- **DispVM Template (AppVM)**: `dvm-NAME`
|
||||
- **Service qubes (not a class)**: `sys-NAME`
|
||||
* **TemplateVM**: `tpl-NAME`
|
||||
* **StandaloneVM**: `NAME`
|
||||
* **AppVM**: `NAME`
|
||||
* **DispVM**: `disp-NAME`
|
||||
* **DispVM Template (AppVM)**: `dvm-NAME`
|
||||
* **Service qubes (not a class)**: `sys-NAME`
|
||||
|
||||
We recommend that for user created qubes, use the domain in the prefix of the
|
||||
qube. An AppVM for personal banking will be named `personal-banking`, an
|
||||
|
|
@ -131,44 +132,44 @@ the same as you trust your vault. The following method tries to fix this
|
|||
problem, domain name is in the prefix of the qube, the label is solely
|
||||
related to trustworthiness of the data it is dealing with.
|
||||
|
||||
- **Black**:
|
||||
- **Trust**: Ultimate.
|
||||
- **Description**: You must trust Dom0, Templates, Vaults, Management
|
||||
* **Black**:
|
||||
* **Trust**: Ultimate.
|
||||
* **Description**: You must trust Dom0, Templates, Vaults, Management
|
||||
qubes, these qubes control your system and hold valuable information.
|
||||
- **Examples**: dom0, tpl-ssh, vault, dvm-mgmt.
|
||||
- **Gray**:
|
||||
- **Trust**: Fully.
|
||||
- **Description**: Trusted storage with extra RPC services that allow
|
||||
* **Examples**: dom0, tpl-ssh, vault, dvm-mgmt.
|
||||
* **Gray**:
|
||||
* **Trust**: Fully.
|
||||
* **Description**: Trusted storage with extra RPC services that allow
|
||||
certain operations to be made by the client and executed on the server
|
||||
or may build components for other qubes.
|
||||
- **Examples**: sys-cacher, sys-git, sys-pgp, sys-ssh-agent, qubes-builder.
|
||||
- **Purple**:
|
||||
- **Trust**: Very much.
|
||||
- **Description**: Has the ability to manager remote servers via encrypted
|
||||
connections and depend on authorization provided by another qube.
|
||||
Examples: ansible, dev, ssh, terraform.
|
||||
- **Blue**:
|
||||
- **Trust**: Much.
|
||||
- **Description**: TODO
|
||||
- **Examples**: TODO
|
||||
- **Green**:
|
||||
- **Trust**: Trusted.
|
||||
- **Description**: TODO
|
||||
- **Examples**: TODO
|
||||
- **Yellow**:
|
||||
- **Trust**: Relatively trusted.
|
||||
- **Description**: TODO
|
||||
- **Examples**: TODO
|
||||
- **Orange**:
|
||||
- **Trust**: Slight.
|
||||
- **Description**: Controls the network flow of data to the client,
|
||||
* **Examples**: sys-cacher, sys-git, sys-pgp, sys-ssh-agent, qubes-builder.
|
||||
* **Purple**:
|
||||
* **Trust**: Very much.
|
||||
* **Description**: Has the ability to manager remote servers via encrypted
|
||||
connections and depend on authorization provided by another qube.
|
||||
Examples: ansible, dev, ssh, terraform.
|
||||
* **Blue**:
|
||||
* **Trust**: Much.
|
||||
* **Description**: TODO
|
||||
* **Examples**: TODO
|
||||
* **Green**:
|
||||
* **Trust**: Trusted.
|
||||
* **Description**: TODO
|
||||
* **Examples**: TODO
|
||||
* **Yellow**:
|
||||
* **Trust**: Relatively trusted.
|
||||
* **Description**: TODO
|
||||
* **Examples**: TODO
|
||||
* **Orange**:
|
||||
* **Trust**: Slight.
|
||||
* **Description**: Controls the network flow of data to the client,
|
||||
normally a firewall.
|
||||
- **Examples**: sys-firewall, sys-vpn, sys-pihole.
|
||||
- **Red**:
|
||||
- **Trust**: Untrusted.
|
||||
- **Description**: Holds untrusted data (PCI devices, untrusted
|
||||
* **Examples**: sys-firewall, sys-vpn, sys-pihole.
|
||||
* **Red**:
|
||||
* **Trust**: Untrusted.
|
||||
* **Description**: Holds untrusted data (PCI devices, untrusted
|
||||
programs, disposables for opening untrusted files or web pages).
|
||||
- **Examples**: sys-net, sys-usb, dvm-browser.
|
||||
* **Examples**: sys-net, sys-usb, dvm-browser.
|
||||
|
||||
#### Qube menu
|
||||
|
||||
|
|
@ -192,38 +193,39 @@ add a state to run a script during boot to unmask and start a specific
|
|||
service. The method below is most of the times combined with `systemd.unit`
|
||||
`ConditionPathExists=` to enable the service conditionally.
|
||||
|
||||
- Server's service name must match the syntax: `service-server` (example:
|
||||
`rsync-server`, `syncthing-server`);
|
||||
- Client's service name must match the syntax: `service-client` (example:
|
||||
`ssh-client`;
|
||||
- Local program's service name must match the syntax: `service` (example:
|
||||
`docker`, `podman`.
|
||||
* Server's service name must match the syntax: `service-server` (example:
|
||||
`rsync-server`, `syncthing-server`);
|
||||
* Client's service name must match the syntax: `service-client` (example:
|
||||
`ssh-client`;
|
||||
* Local program's service name must match the syntax: `service` (example:
|
||||
`docker`, `podman`.
|
||||
|
||||
### Qube connections
|
||||
|
||||
There are several ways a qube can connect to another, either directly with
|
||||
Xen or with Qrexec. If something is not required, we remove it.
|
||||
|
||||
- `template` is always required:
|
||||
- When required, must be set to the custom-made template;
|
||||
- When not possible to use, prefer StandaloneVMs instead.
|
||||
- `audiovm` is rarely required on the majority of the projects:
|
||||
- When required, set it to `"*default*"` to honor the global preferences.
|
||||
- When not required, must be set to None;
|
||||
- `netvm` is required on a lot of projects.
|
||||
- When required, must not be managed to honor the global preferences. If
|
||||
it requires a custom networking scheme, the state must make sure that
|
||||
the netvm exists;
|
||||
- When not required, must be set to None.
|
||||
- `default_dispvm` is nice to have:
|
||||
- When required, must guarantee that the network follows the same chain as
|
||||
the calling qube in the default configuration;
|
||||
- When not required, must be set to None.
|
||||
- `management_dispvm` is always required:
|
||||
- When required, should not be managed to honor the global preferences,
|
||||
* `template` is always required:
|
||||
* When required, must be set to the custom-made template;
|
||||
* When not possible to use, prefer StandaloneVMs instead.
|
||||
* `audiovm` is rarely required on the majority of the projects:
|
||||
* When required, set it to `"*default*"` to honor the global
|
||||
preferences.
|
||||
* When not required, must be set to None;
|
||||
* `netvm` is required on a lot of projects.
|
||||
* When required, must not be managed to honor the global preferences. If
|
||||
it requires a custom networking scheme, the state must make sure that
|
||||
the netvm exists;
|
||||
* When not required, must be set to None.
|
||||
* `default_dispvm` is nice to have:
|
||||
* When required, must guarantee that the network follows the same chain
|
||||
as the calling qube in the default configuration;
|
||||
* When not required, must be set to None.
|
||||
* `management_dispvm` is always required:
|
||||
* When required, should not be managed to honor the global preferences,
|
||||
but it can make sense to set a custom management qube for debugging.
|
||||
- When not required, such as on qubes that don't work through Salt, don't
|
||||
touch it, it doesn't increase attack surface.
|
||||
* When not required, such as on qubes that don't work through Salt,
|
||||
don't touch it, it doesn't increase attack surface.
|
||||
|
||||
### Qrexec call and policy
|
||||
|
||||
|
|
@ -232,8 +234,8 @@ Xen or with Qrexec. If something is not required, we remove it.
|
|||
to be set by Dom0 via the `target=` redirection parameter, instead of
|
||||
having to modify the client to target a different server via
|
||||
`qrexec-client-vm`.
|
||||
3. Target qube for client script must default to `@default`, but other targets
|
||||
must be allowed via parameters.
|
||||
3. Target qube for client script must default to `@default`, but other
|
||||
targets must be allowed via parameters.
|
||||
|
||||
### Qrexec socket services
|
||||
|
||||
|
|
@ -246,31 +248,32 @@ wants to connect in the server. We will refer to Unix Domains Sockets as
|
|||
Using `qusal.Service`, such as `qusal.Rsync`, `qusal.Syncthing`, `qusal.Ssh`
|
||||
has the following advantages:
|
||||
|
||||
- Usability: User recognizes the call per service name;
|
||||
- Extensibility: Allows extending functionality for arguments added in the
|
||||
future, no need to migrate user policy from `qubes.ConnectTCP`;
|
||||
is not necessary;
|
||||
* Usability: User recognizes the call per service name;
|
||||
* Extensibility: Allows extending functionality for arguments added in the
|
||||
future, no need to migrate user policy from `qubes.ConnectTCP`; is not
|
||||
necessary;
|
||||
|
||||
Rules for server RPC service:
|
||||
|
||||
- Symlink `qubes.ConnectTCP` to `qusal.Service` if connecting to a local port;
|
||||
- Use `qubes.ConnectTCP` directly when the user won't manage the policy for
|
||||
the wanted call, such as `sys-syncthing-browser`, where it happens that only
|
||||
this qube will access the admin interface of `sys-syncthing`;
|
||||
- Use `socat` to connect to remote hosts or UDS with path defined by the
|
||||
service argument.
|
||||
* Symlink `qubes.ConnectTCP` to `qusal.Service` if connecting to a local
|
||||
port;
|
||||
* Use `qubes.ConnectTCP` directly when the user won't manage the policy for
|
||||
the wanted call, such as `sys-syncthing-browser`, where it happens that
|
||||
only this qube will access the admin interface of `sys-syncthing`;
|
||||
* Use `socat` to connect to remote hosts or UDS with path defined by the
|
||||
service argument.
|
||||
|
||||
Rules for client RPC call:
|
||||
|
||||
- Use `systemd.socket` units, it does not require `socat`, it is not
|
||||
restricted to the use of `qubes.ConnectTCP` called by `qvm-connect-tcp`, the
|
||||
service can be properly logged and status verified by a service manager
|
||||
instead of forking socat to the background with a `rc.local` script and
|
||||
finally, can be controlled by Qubes Services to enable or disable the unit
|
||||
with `ConditionPathExists=` instead of doing if-else statements in
|
||||
`rc.local`;
|
||||
- Use of `socat` and `qvm-connect-tcp` is permitted for UDS and for
|
||||
instructional use as it is very short.
|
||||
* Use `systemd.socket` units, it does not require `socat`, it is not
|
||||
restricted to the use of `qubes.ConnectTCP` called by `qvm-connect-tcp`,
|
||||
the service can be properly logged and status verified by a service
|
||||
manager instead of forking socat to the background with a `rc.local`
|
||||
script and finally, can be controlled by Qubes Services to enable or
|
||||
disable the unit with `ConditionPathExists=` instead of doing if-else
|
||||
statements in `rc.local`;
|
||||
* Use of `socat` and `qvm-connect-tcp` is permitted for UDS and for
|
||||
instructional use as it is very short.
|
||||
|
||||
## Features
|
||||
|
||||
|
|
@ -287,7 +290,6 @@ the browser is compromised, it can compromise the server.
|
|||
Some projects that uses this enhancement are `sys-pihole`, `sys-syncthing` and
|
||||
`sys-cacher`.
|
||||
|
||||
|
||||
## Release new version
|
||||
|
||||
The following sections instruct how a contributor or maintainer can deploy qu
|
||||
|
|
@ -296,44 +298,44 @@ The following sections instruct how a contributor or maintainer can deploy qu
|
|||
|
||||
Qubes OS major releases might come with changes that can impact the project.
|
||||
|
||||
1. Subscribe to the
|
||||
[qubes-announce](https://www.qubes-os.org/support/#qubes-announce) mailing
|
||||
list to receive notification of new Qubes OS releases.
|
||||
2. Keep up changelogs, especially notices of deprecation, new packages being
|
||||
added or modifications to those packages that affects our states.
|
||||
3. Install the new Qubes OS version.
|
||||
4. Install all formulas.
|
||||
5. Change the supported or minimum required version of Qubes OS.
|
||||
1. Subscribe to the
|
||||
[qubes-announce](https://www.qubes-os.org/support/#qubes-announce) mailing
|
||||
list to receive notification of new Qubes OS releases.
|
||||
2. Keep up changelogs, especially notices of deprecation, new packages being
|
||||
added or modifications to those packages that affects our states.
|
||||
3. Install the new Qubes OS version.
|
||||
4. Install all formulas.
|
||||
5. Change the supported or minimum required version of Qubes OS.
|
||||
|
||||
### Template major release upgrade
|
||||
|
||||
1. Subscribe to the
|
||||
[qubes-announce](https://www.qubes-os.org/support/#qubes-announce) mailing
|
||||
list to receive notifications of new templates.
|
||||
2. Install the new template version.
|
||||
3. Clone template to a new testing name of your choice.
|
||||
4. Install all formulas on the testing template and see which states failed.
|
||||
Most of the times, the state will fail due to a change in package name
|
||||
(occurs when package has version in the name) or a deprecation of a
|
||||
package.
|
||||
5. Check if there are new packages that are useful to each specified formula.
|
||||
The best way is to see the `Recommends` and `Suggests` fields of the main
|
||||
package that is installed.
|
||||
6. Install all formulas as instructed in each of their documents.
|
||||
7. Change the version of the base template.
|
||||
1. Subscribe to the
|
||||
[qubes-announce](https://www.qubes-os.org/support/#qubes-announce) mailing
|
||||
list to receive notifications of new templates.
|
||||
2. Install the new template version.
|
||||
3. Clone template to a new testing name of your choice.
|
||||
4. Install all formulas on the testing template and see which states failed.
|
||||
Most of the times, the state will fail due to a change in package name
|
||||
(occurs when package has version in the name) or a deprecation of a
|
||||
package.
|
||||
5. Check if there are new packages that are useful to each specified formula.
|
||||
The best way is to see the `Recommends` and `Suggests` fields of the main
|
||||
package that is installed.
|
||||
6. Install all formulas as instructed in each of their documents.
|
||||
7. Change the version of the base template.
|
||||
|
||||
### Archive or Build from source major release upgrade
|
||||
|
||||
Some projects might use archives for lack of a better alternative. Dealing
|
||||
with them can be troublesome. Prefer packages from repositories when possible.
|
||||
|
||||
1. Subscribe to the vendor release announcement mailing list or RSS to receive
|
||||
notifications of new versions.
|
||||
2. Read the changelog, breaking changes and new features might be present.
|
||||
3. Clone the qube that uses the archive to a new testing name of your choice.
|
||||
4. Install the new archive version on the testing qube. Regarding breaking
|
||||
changes, most projects implement a migration on the next restart of the
|
||||
daemon that rebuilds a database index for example, if they don't, deal with
|
||||
it. For new features, check if they should be added to the default
|
||||
installation.
|
||||
5. Change the version of the archive, git tag or commit.
|
||||
1. Subscribe to the vendor release announcement mailing list or RSS to
|
||||
receive notifications of new versions.
|
||||
2. Read the changelog, breaking changes and new features might be present.
|
||||
3. Clone the qube that uses the archive to a new testing name of your choice.
|
||||
4. Install the new archive version on the testing qube. Regarding breaking
|
||||
changes, most projects implement a migration on the next restart of the
|
||||
daemon that rebuilds a database index for example, if they don't, deal
|
||||
with it. For new features, check if they should be added to the default
|
||||
installation.
|
||||
5. Change the version of the archive, git tag or commit.
|
||||
|
|
|
|||
|
|
@ -4,17 +4,17 @@ Qusal install and update guide.
|
|||
|
||||
## Table of Contents
|
||||
|
||||
* [Installation](#installation)
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [DomU Installation](#domu-installation)
|
||||
* [Dom0 Installation](#dom0-installation)
|
||||
* [Update](#update)
|
||||
* [DomU Update](#domu-update)
|
||||
* [Dom0 Update with Git](#dom0-update-with-git)
|
||||
* [Dom0 Update by literally copying the git repository](#dom0-update-by-literally-copying-the-git-repository)
|
||||
* [Template upgrade](#template-upgrade)
|
||||
* [Clean install](#clean-install)
|
||||
* [Upgrade a template in-place](#upgrade-a-template-in-place)
|
||||
* [Installation](#installation)
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [DomU Installation](#domu-installation)
|
||||
* [Dom0 Installation](#dom0-installation)
|
||||
* [Update](#update)
|
||||
* [DomU Update](#domu-update)
|
||||
* [Dom0 Update with Git](#dom0-update-with-git)
|
||||
* [Dom0 Update by literally copying the git repository](#dom0-update-by-literally-copying-the-git-repository)
|
||||
* [Template upgrade](#template-upgrade)
|
||||
* [Clean install](#clean-install)
|
||||
* [Upgrade a template in-place](#upgrade-a-template-in-place)
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -22,8 +22,8 @@ Qusal install and update guide.
|
|||
|
||||
You current setup needs to fulfill the following requisites:
|
||||
|
||||
- Qubes OS R4.2
|
||||
- Internet connection
|
||||
* Qubes OS R4.2
|
||||
* Internet connection
|
||||
|
||||
### DomU Installation
|
||||
|
||||
|
|
@ -33,6 +33,7 @@ You current setup needs to fulfill the following requisites:
|
|||
2. Clone the repository (if you made a fork, fork the submodule(s) before
|
||||
clone and use your remote repository instead, the submodules will also be
|
||||
from your fork).
|
||||
|
||||
```sh
|
||||
git clone --recurse-submodules https://github.com/ben-grande/qusal.git
|
||||
```
|
||||
|
|
@ -47,6 +48,7 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d
|
|||
|
||||
1. Copy the repository `$file` from the DomU `$qube` to Dom0 (substitute
|
||||
`CHANGEME` for the desired valued):
|
||||
|
||||
```sh
|
||||
qube="CHANGEME" # qube name where you downloaded the repository
|
||||
file="CHANGEME" # path to the repository in the qube
|
||||
|
|
@ -58,6 +60,7 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d
|
|||
```
|
||||
|
||||
2. Pass the maintainer's key from the qube to Dom0:
|
||||
|
||||
```sh
|
||||
qvm-run --pass-io "${qube}" -- "cat /home/user/ben-code.asc" | tee /tmp/ben-code.asc
|
||||
```
|
||||
|
|
@ -65,6 +68,7 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d
|
|||
3. Verify that the key fingerprint matches
|
||||
`DF38 3487 5B65 7587 13D9 2E91 A475 969D E4E3 71E3`. You can use
|
||||
Sequoia-PGP or GnuPG for the fingerprint verification:
|
||||
|
||||
```sh
|
||||
gpg --show-keys /tmp/ben-code.asc
|
||||
# or
|
||||
|
|
@ -72,18 +76,21 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d
|
|||
```
|
||||
|
||||
4. Import the verified key to your keyring:
|
||||
|
||||
```sh
|
||||
gpg --import /tmp/ben-code.asc
|
||||
```
|
||||
|
||||
5. Verify the [commit or tag signature](https://www.qubes-os.org/security/verifying-signatures/#how-to-verify-signatures-on-git-repository-tags-and-commits)
|
||||
and expect a good signature, be surprised otherwise:
|
||||
|
||||
```sh
|
||||
git verify-commit HEAD
|
||||
git submodule foreach git verify-commit HEAD
|
||||
```
|
||||
|
||||
6. Copy the project to the Salt directories:
|
||||
|
||||
```sh
|
||||
~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh
|
||||
```
|
||||
|
|
@ -97,6 +104,7 @@ demonstrated below.
|
|||
### DomU Update
|
||||
|
||||
Update the repository state in your DomU:
|
||||
|
||||
```sh
|
||||
git -C ~/src/qusal fetch --recurse-submodules
|
||||
```
|
||||
|
|
@ -112,13 +120,15 @@ with the sys-git formula.
|
|||
|
||||
2. Install `git` on Dom0, allow the Qrexec protocol to work in submodules and
|
||||
clone the repository to `~/src/qusal` (only has to be run once):
|
||||
|
||||
```sh
|
||||
mkdir -p ~/src
|
||||
sudo qubesctl state.apply sys-git.install-client
|
||||
git clone --recurse-submodules qrexec://@default/qusal.git ~/src/qusal
|
||||
```
|
||||
|
||||
3. Next updates will be pulling instead of cloning:
|
||||
3. Next updates will be pulling instead of cloning:
|
||||
|
||||
```sh
|
||||
git -C ~/src/qusal pull --recurse-submodules
|
||||
git -C ~/src/qusal submodule update --merge
|
||||
|
|
@ -127,12 +137,14 @@ with the sys-git formula.
|
|||
4. Verify the commit or tag signature and expect a good signature, be
|
||||
surprised otherwise (signature verification on submodules is skipped if
|
||||
checking out but not merging):
|
||||
|
||||
```sh
|
||||
git verify-commit HEAD
|
||||
git submodule foreach git verify-commit HEAD
|
||||
```
|
||||
|
||||
5. Copy the project to the Salt directories:
|
||||
|
||||
```
|
||||
~/src/qusal/scripts/setup.sh
|
||||
```
|
||||
|
|
@ -147,6 +159,7 @@ project had a signed archive. The `.git/info/exclude` can exclude modified
|
|||
files from being tracked and signature verification won't catch it.
|
||||
|
||||
1. Install the helpers scripts and git on Dom0 (only has to be run once):
|
||||
|
||||
```sh
|
||||
sudo qubesctl state.apply dom0.install-helpers
|
||||
sudo qubes-dom0-update git
|
||||
|
|
@ -154,6 +167,7 @@ files from being tracked and signature verification won't catch it.
|
|||
|
||||
2. Copy the repository `$file` from the DomU `$qube` to Dom0 (substitute
|
||||
`CHANGEME` for the desired valued):
|
||||
|
||||
```sh
|
||||
qube="CHANGEME" # qube name where you downloaded the repository
|
||||
file="CHANGEME" # path to the repository in the qube
|
||||
|
|
@ -164,12 +178,14 @@ files from being tracked and signature verification won't catch it.
|
|||
|
||||
3. Verify the commit or tag signature and expect a good signature, be
|
||||
surprised otherwise:
|
||||
|
||||
```sh
|
||||
git verify-commit HEAD
|
||||
git submodule foreach git verify-commit HEAD
|
||||
```
|
||||
|
||||
4. Copy the project to the Salt directories:
|
||||
|
||||
```sh
|
||||
~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh
|
||||
```
|
||||
|
|
@ -183,13 +199,13 @@ Template upgrade refers to template major releases upgrade.
|
|||
As we use Salt, doing clean installs are easy. Unfortunately QubesOS does not
|
||||
provided a CLI program to rename qubes.
|
||||
|
||||
1. Open `Qube Manager`, select the template you want to upgrade and rename it
|
||||
adding the suffix `-old`. The `Qube Manager` will change the `template`
|
||||
preference of qubes based on the chosen template.
|
||||
2. Rerun the formulas that targeted the chosen template.
|
||||
3. If the formula fails, use `Qubes Template Switcher` to set the `-old`
|
||||
template to be used by the qubes managed by that specific formula.
|
||||
3. Repeat for every template that needs to be upgraded.
|
||||
1. Open `Qube Manager`, select the template you want to upgrade and rename it
|
||||
adding the suffix `-old`. The `Qube Manager` will change the `template`
|
||||
preference of qubes based on the chosen template.
|
||||
2. Rerun the formulas that targeted the chosen template.
|
||||
3. If the formula fails, use `Qubes Template Switcher` to set the `-old`
|
||||
template to be used by the qubes managed by that specific formula.
|
||||
4. Repeat for every template that needs to be upgraded.
|
||||
|
||||
### Upgrade a template in-place
|
||||
|
||||
|
|
@ -204,9 +220,9 @@ data can be present in the root volume, in-place upgrades are easier for this
|
|||
qube class instead of doing a migration of specific folders and files to the
|
||||
new qube.
|
||||
|
||||
1. If you still want to do upgrade in-place, refer to upstream guides, for
|
||||
[Debian](https://www.qubes-os.org/doc/templates/debian/in-place-upgrade)
|
||||
and
|
||||
[Fedora](https://www.qubes-os.org/doc/templates/fedora/in-place-upgrade).
|
||||
2. Rerun the formulas that targeted the chosen template.
|
||||
3. Repeat for every template that needs to be upgraded.
|
||||
1. If you still want to do upgrade in-place, refer to upstream guides, for
|
||||
[Debian](https://www.qubes-os.org/doc/templates/debian/in-place-upgrade)
|
||||
and
|
||||
[Fedora](https://www.qubes-os.org/doc/templates/fedora/in-place-upgrade).
|
||||
2. Rerun the formulas that targeted the chosen template.
|
||||
3. Repeat for every template that needs to be upgraded.
|
||||
|
|
|
|||
34
docs/SALT.md
34
docs/SALT.md
|
|
@ -4,14 +4,14 @@ Qusal SaltStack development guide.
|
|||
|
||||
## Table of Contents
|
||||
|
||||
* [What this guide is](#what-this-guide-is)
|
||||
* [Resources](#resources)
|
||||
* [Minion Configuration](#minion-configuration)
|
||||
* [Jinja](#jinja)
|
||||
* [Targetting Minions](#targetting-minions)
|
||||
* [Idempotence](#idempotence)
|
||||
* [Examples](#examples)
|
||||
* [Troubleshooting](#troubleshooting)
|
||||
* [What this guide is](#what-this-guide-is)
|
||||
* [Resources](#resources)
|
||||
* [Minion Configuration](#minion-configuration)
|
||||
* [Jinja](#jinja)
|
||||
* [Targetting Minions](#targetting-minions)
|
||||
* [Idempotence](#idempotence)
|
||||
* [Examples](#examples)
|
||||
* [Troubleshooting](#troubleshooting)
|
||||
|
||||
## What this guide is
|
||||
|
||||
|
|
@ -97,9 +97,9 @@ been done, changed or not.
|
|||
|
||||
The `cmd` state might still be needed in some circumstances:
|
||||
|
||||
- When Qubes OS does not provide a module;
|
||||
- When SaltStack does provide a module; and
|
||||
- When SaltStack module does not meet all requirements.
|
||||
* When Qubes OS does not provide a module;
|
||||
* When SaltStack does provide a module; and
|
||||
* When SaltStack module does not meet all requirements.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -111,6 +111,7 @@ make sure to install Qusal before, it is required to create the base
|
|||
templates, do Jinja imports and run Jinja macros.
|
||||
|
||||
`create-keys.sls`:
|
||||
|
||||
```salt
|
||||
{# Use Qubes OS Jinja Template to create qubes using 'qvm.vm' #}
|
||||
{% from "qvm/template.jinja" import load %}
|
||||
|
|
@ -165,6 +166,7 @@ features:
|
|||
```
|
||||
|
||||
`install-keys.sls`:
|
||||
|
||||
```salt
|
||||
{# Avoid applying the state by mistake to dom0 #}
|
||||
{% if grains['nodename'] != 'dom0' %}
|
||||
|
|
@ -213,6 +215,7 @@ keys-installed-os-specific:
|
|||
```
|
||||
|
||||
`appmenus-keys.sls`:
|
||||
|
||||
```salt
|
||||
{# From our Jinja template sync-appmenus, import 'sync_appmenus' macro #}
|
||||
{% from 'utils/macros/sync-appmenus.sls' import sync_appmenus %}
|
||||
|
|
@ -223,16 +226,19 @@ keys-installed-os-specific:
|
|||
After you have created the states above, copy them to Dom0 in `/srv/salt`.
|
||||
|
||||
Create the qube:
|
||||
|
||||
```sh
|
||||
sudo qubesctl state.apply create-keys
|
||||
```
|
||||
|
||||
Install packages in the qube template:
|
||||
|
||||
```sh
|
||||
sudo qubesctl --skip-dom0 --targets=tpl-keys state.apply install-keys
|
||||
```
|
||||
|
||||
Make the application menus appear after the requirements are installed:
|
||||
|
||||
```sh
|
||||
sudo qubesctl state.apply appmenus-keys
|
||||
```
|
||||
|
|
@ -245,9 +251,9 @@ Qusal macros. The above examples are based on our [vault formula](../salt/vault)
|
|||
You may face some [YAML idiosyncrasies](https://docs.saltproject.io/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html),
|
||||
these are the common mistakes that you may commit. Use an editor that:
|
||||
|
||||
- Shows when tabs have been used instead of spaces;
|
||||
- Highlights syntax for Salt, Jinja, Python, YAML and Shellscript; and
|
||||
- Lints your file at will or when saving it;
|
||||
* Shows when tabs have been used instead of spaces;
|
||||
* Highlights syntax for Salt, Jinja, Python, YAML and Shellscript; and
|
||||
* Lints your file at will or when saving it;
|
||||
|
||||
For further debugging information on Qusal, read our
|
||||
[troubleshooting guide](TROUBLESHOOT.md).
|
||||
|
|
|
|||
|
|
@ -4,10 +4,10 @@ Qusal troubleshooting guidelines.
|
|||
|
||||
## Table of Contents
|
||||
|
||||
* [Detect if your issue was already opened](#detect-if-your-issue-was-already-opened)
|
||||
* [Qrexec client shows Request refused](#qrexec-client-shows-request-refused)
|
||||
* [Salt wrapper qubesctl command fails](#salt-wrapper-qubesctl-command-fails)
|
||||
* [Get Salt management information](#get-salt-management-information)
|
||||
* [Detect if your issue was already opened](#detect-if-your-issue-was-already-opened)
|
||||
* [Qrexec client shows Request refused](#qrexec-client-shows-request-refused)
|
||||
* [Salt wrapper qubesctl command fails](#salt-wrapper-qubesctl-command-fails)
|
||||
* [Get Salt management information](#get-salt-management-information)
|
||||
|
||||
## Detect if your issue was already opened
|
||||
|
||||
|
|
@ -24,9 +24,9 @@ typo in the configuration.
|
|||
|
||||
Therefore, it is recommended to:
|
||||
|
||||
- Check if there is a rule for the service you want to call that would either
|
||||
result in `ask` or `allow`; and
|
||||
- Check again and again if you made a typo in the policy.
|
||||
* Check if there is a rule for the service you want to call that would
|
||||
either result in `ask` or `allow`; and
|
||||
* Check again and again if you made a typo in the policy.
|
||||
|
||||
The examples below will use the qube `dev` and the RPC service `qubes.GetDate`
|
||||
and other common Qrexec RPC services as an example, substitute them with the
|
||||
|
|
@ -34,23 +34,27 @@ qube and service you intend to use, such as qube `code` and service
|
|||
`qusal.GitInit`.
|
||||
|
||||
On `dom0`, watch the Qrexec policy logs:
|
||||
|
||||
```sh
|
||||
sudo journalctl -fu qubes-qrexec-policy-daemon | cut -d " " -f 7-
|
||||
```
|
||||
|
||||
If you ave many simultaneous calls being shown, get on the important ones:
|
||||
|
||||
```sh
|
||||
sudo journalctl -fu qubes-qrexec-policy-daemon | cut -d " " -f 7- \
|
||||
| grep -e qubes.GetDate -e qubes.Filecopy
|
||||
```
|
||||
|
||||
You can emulate the call from `dom0`:
|
||||
|
||||
```sh
|
||||
qrexec-policy dev @default qubes.GetDate
|
||||
```
|
||||
|
||||
On the qube making the call, run the `qrexec-client-vm` command directly
|
||||
rather than using a wrapper around it:
|
||||
|
||||
```sh
|
||||
qrexec-client-vm @default qubes.GetDate
|
||||
```
|
||||
|
|
@ -61,13 +65,15 @@ The Salt Project has [troubleshooting](https://docs.saltproject.io/en/latest/top
|
|||
page for a variety of problems you may encounter.
|
||||
|
||||
A nice summary of the states can be seen with the `--show-output` argument:
|
||||
```
|
||||
|
||||
```sh
|
||||
sudo qubesctl --show-output state.apply pkg.uptodate
|
||||
```
|
||||
|
||||
Ending the Salt call with `-l debug` argument gives the most detailed output
|
||||
(may contain private information):
|
||||
```
|
||||
|
||||
```sh
|
||||
sudo qubesctl state.apply pkg.uptodate -l debug
|
||||
```
|
||||
|
||||
|
|
@ -79,6 +85,7 @@ Let's gather some information about it.
|
|||
Get information about the global `management_dispvm` and the same property of
|
||||
a specific qube. In this example we use `tpl-qubes-builder`, substitute for
|
||||
the qube being managed:
|
||||
|
||||
```sh
|
||||
sudo qubesctl state.apply dom0.helpers
|
||||
qvm-mgmt tpl-qubes-builder
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue