6ec0768f13
- Remove OpenVPN code comments; - Reorganize rules for easier reading; - Server can connect without having client attached; - Systemd service for easier monitoring of wg-quick; and - Firewall also restarts wg-quick and apply new endpoint rules. |
||
---|---|---|
.github | ||
.reuse | ||
docs | ||
LICENSES | ||
minion.d | ||
rpm_spec/template | ||
salt | ||
scripts | ||
.editorconfig | ||
.gitignore | ||
.gitlint | ||
.gitmodules | ||
.pre-commit-config.yaml | ||
.qubesbuilder | ||
.qubesbuilder.template | ||
.salt-lint | ||
.yamllint | ||
README.md |
qusal
Salt Formulas for Qubes OS.
Warning
Warning: Not ready for production, development only. Breaking changes can and will be introduced in the meantime. You've been warned.
Table of Contents
Description
Qusal is a Free and Open Source security-focused project that provides SaltStack Formulas for Qubes OS users to complete various daily tasks, such as web browsing, video-calls, remote administration, coding, network tunnels and much more, which are easy to install and maintains low attack surface.
We not only provide a single solution for each project, but also provides alternative when they differ, such as for networking, you could use a VPN, DNS Sink-hole, Mirage Unikernel or the standard Qubes Firewall for managing the network chain and the connections the clients connected to these NetVMs are allowed to make.
Here are some of the Global Preferences we can manage:
- clockvm: disp-sys-net, sys-net
- default_audiovm: disp-sys-audio
- default_dispvm: dvm-reader
- default_netvm: sys-pihole, sys-firewall or disp-sys-firewall
- management_dispvm: dvm-mgmt
- updatevm: sys-pihole, sys-firewall or disp-sys-firewall
To learn more about how we make decisions, take a look at our design document.
To troubleshoot issues, read our troubleshooting document.
Installation
Prerequisites
You current setup needs to fulfill the following requisites:
- Qubes OS R4.2
- Internet connection
DomU Installation
-
Install
git
in the qube, if it is an AppVM, install it it's the TemplateVM and restart the AppVM. -
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).
git clone --recurse-submodules https://github.com/ben-grande/qusal.git
-
Copy the maintainer's signing key to your text editor and save the file to
/home/user/ben-code.asc
.
Dom0 Installation
Before copying anything to Dom0, read Qubes OS warning about consequences of this procedure.
-
Copy the repository
$file
from the DomU$qube
to Dom0 (substituteCHANGEME
for the desired valued):qube="CHANGEME" # qube name where you downloaded the repository file="CHANGEME" # path to the repository in the qube qvm-run --pass-io --localcmd="UPDATES_MAX_FILES=10000 /usr/libexec/qubes/qfile-dom0-unpacker user ~/QubesIncoming/${qube}/qusal" \ "${qube}" /usr/lib/qubes/qfile-agent "${file}"
-
Pass the maintainer's key from the qube to Dom0:
qvm-run --pass-io "${qube}" -- "cat /home/user/ben-code.asc" | tee /tmp/ben-code.asc
-
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:gpg --show-keys /tmp/ben-code.asc # or #sq inspect ben-code.asc
-
Import the verified key to your keyring:
gpg --import /tmp/ben-code.asc
-
Verify the commit or tag signature and expect a good signature, be surprised otherwise:
git verify-commit HEAD git submodule foreach git verify-commit HEAD
-
Copy the project to the Salt directories:
~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh
Update
To update, you can copy the repository again to dom0 as instructed in the installation section above or you can use easier methods demonstrated below.
DomU Update
Update the repository state in your DomU:
git -C ~/src/qusal fetch --recurse-submodules
Dom0 Update with Git
This method is more secure than literally copying the whole directory of the repository to dom0 but the setup is more involved. Requires some familiarity with the sys-git formula.
-
Install the sys-git formula and push the repository to the git server.
-
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):mkdir -p ~/src sudo qubesctl state.apply sys-git.install-client git clone --recurse-submodules qrexec://@default/qusal.git ~/src/qusal
-
Next updates will be pulling instead of cloning:
git -C ~/src/qusal pull --recurse-submodules git -C ~/src/qusal submodule update --merge
-
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):
git verify-commit HEAD git submodule foreach git verify-commit HEAD
-
Copy the project to the Salt directories:
~/src/qusal/scripts/setup.sh
Dom0 Update by literally copying the git repository
This method is similar to the installation method, but easier to type. This
method is less secure than Git over Qrexec because it copies the whole
repository, including the .git
directory which holds files that are not
tracked by git. It would be easier to distrust the downloader qube if the
project had a signed archive. The .git/info/exclude
can exclude modified
files from being tracked and signature verification won't catch it.
-
Install the helpers scripts and git on Dom0 (only has to be run once):
sudo qubesctl state.apply dom0.install-helpers sudo qubes-dom0-update git
-
Copy the repository
$file
from the DomU$qube
to Dom0 (substituteCHANGEME
for the desired valued):qube="CHANGEME" # qube name where you downloaded the repository file="CHANGEME" # path to the repository in the qube rm -rf ~/QubesIncoming/"${qube}"/qusal UPDATES_MAX_FILES=10000 qvm-copy-to-dom0 "${qube}" "${file}"
-
Verify the commit or tag signature and expect a good signature, be surprised otherwise:
git verify-commit HEAD git submodule foreach git verify-commit HEAD
-
Copy the project to the Salt directories:
~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh
Usage
Qusal is now installed. Please read the README.md of each project in the salt directory for further information on how to install the desired package. If you are unsure how to start, get some ideas from our bootstrap guide.
The intended behavior is to enforce the state of qubes and their services. If you modify the qubes and their services and apply the state again, conflicting configurations will be overwritten. To enforce your state, write a SaltFile to specify the desired state and call it after the ones provided by this project.
If you want to edit the access control of any service, you
should always use the Qrexec policy at /etc/qubes/policy.d/30-user.policy
,
as this file will take precedence over the packaged policies.
Please note that when you allow more Qrexec calls than the default shipped by Qubes OS, you are increasing the attack surface of the target, normally to a valuable qube that can hold secrets or pristine data. A compromise of the client qube can extend to the server, therefore configure the installation according to your threat model.
Contribute
There are several ways to contribute to this project. Spread the word, help on user support, review opened issues, fix typos, implement new features, donations.
Please take a look at our contribution guidelines before contributing code or to the documentation, it holds important information on how the project is structured, why some design decisions were made and what can be improved.
Donate
This project can only survive through donations. If you like what we have done, please consider donating. Contact us for donation address.
This project depends on Qubes OS, consider donating to upstream.
Support
Free Support
Free support will be provided on a best effort basis. If you want something, open an issue and patiently wait for a reply, the project is best developed in the open so anyone can search for past issues.
Paid Support
Paid consultation services can be provided. Request a quote from us.
Contact
You must not contact for free support.
Credits
I stand on the shoulders of giants. This would not be possible without people contributing to Qubes OS SaltStack formulas. Honorable mention(s): unman.
Legal
This project is REUSE-compliant. It is difficult to list all licenses and copyrights and keep them up-to-date here.
The easiest way to get the copyright and license of the project with the reuse tool:
reuse spdx
You can also check these information manually by looking in the file header,
a companion .license
file or in .reuse/dep5
.
All licenses are present in the LICENSES directory.
Note that submodules have their own licenses and copyrights statements, please check each one individually using the same methods described above for a full statement.