doc: simplify installation command

Many people reported problems with the installation command, most of
them had typos, understandable due to the long command. Tar is available
even on minimal templates. Using tar is not more dangerous than using
qfile-unpacker in this case because the project has no signed archives
and passing a directory to dom0 is insecure, considering a git repo, an
attacker could find information in the .git directory or modify files
and add them to git exclude, which won't be noticed when verifying the
commit signature.

In the future, if a signed tarball were to be provided, qvm-run and pipe
would be used instead, making the command even simpler.
This commit is contained in:
Ben Grande 2025-01-08 14:38:48 +01:00
parent f196e2f492
commit a02997b89e
No known key found for this signature in database
GPG Key ID: 00C64E14F51F9E56
3 changed files with 39 additions and 15 deletions

View File

@ -4,11 +4,11 @@ Upstream-Contact: Benjamin Grande M. S. <ben.grande.b@gmail.com>
Source: https://github.com/ben-grande/qusal Source: https://github.com/ben-grande/qusal
Files: README.md */README.md docs/* .github/*_TEMPLATE/* .github/*.md Files: README.md */README.md docs/* .github/*_TEMPLATE/* .github/*.md
Copyright: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com> Copyright: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
License: CC-BY-SA-4.0 License: CC-BY-SA-4.0
Files: version salt/*/version dependencies/* .ecrc Files: version salt/*/version dependencies/* .ecrc
Copyright: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com> Copyright: 2023 - 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
License: CC0-1.0 License: CC0-1.0
Files: salt/electrum/files/client/keys/* Files: salt/electrum/files/client/keys/*

View File

@ -27,6 +27,12 @@ You current setup needs to fulfill the following requisites:
### DomU Installation ### DomU Installation
It is recommended to use separate qube from your normal operations as this
installation will eventually be copied to dom0. Apart from that, it is also
recommended to use a separate qube for fetching the signing keys, different
from the one acquiring Qusal. The separate qubes should be DispVM, but AppVM
or StandaloneVM will also work.
1. Install `git` in the qube, if it is an AppVM, install it it's the 1. Install `git` in the qube, if it is an AppVM, install it it's the
TemplateVM and restart the AppVM. TemplateVM and restart the AppVM.
@ -35,17 +41,24 @@ You current setup needs to fulfill the following requisites:
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 ~/qusal
``` ```
3. Copy the [maintainer's signing key](https://github.com/ben-grande/ben-grande/raw/main/DF3834875B65758713D92E91A475969DE4E371E3.asc) 3. Copy the [maintainer's signing key](https://github.com/ben-grande/ben-grande/raw/main/DF3834875B65758713D92E91A475969DE4E371E3.asc)
to your text editor and save the file to `/home/user/ben-code.asc`. to your text editor and save to the file `/home/user/ben-code.asc`.
### Dom0 Installation ### Dom0 Installation
Before copying anything to Dom0, read [Qubes OS warning about consequences of Before copying anything to Dom0, read [Qubes OS warning about consequences of
this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0). this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0).
<!--
qvm-run --no-gui --pass-io --localcmd="UPDATES_MAX_FILES=50000
/usr/libexec/qubes/qfile-dom0-unpacker \"${USER}\"
~/QubesIncoming/\"${qube}\"" \
"${qube}" /usr/lib/qubes/qfile-agent "${file}"
-->
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):
@ -53,16 +66,16 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d
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
qvm-run --pass-io --localcmd="UPDATES_MAX_FILES=10000 mkdir -p -- ~/QubesIncoming/"${qube}"
/usr/libexec/qubes/qfile-dom0-unpacker user qvm-run --no-gui --pass-io -- "${qube}" "tar -cf - -C ~ qusal" |
~/QubesIncoming/${qube}/qusal" \ tar -xf - -C ~/QubesIncoming/"${qube}"
"${qube}" /usr/lib/qubes/qfile-agent "${file}"
``` ```
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 --no-gui --pass-io -- "${qube}" "cat -- /home/user/ben-code.asc" |
tee -- /tmp/ben-code.asc >/dev/null
``` ```
3. Verify that the key fingerprint matches 3. Verify that the key fingerprint matches
@ -81,7 +94,13 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d
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. Enter the repository:
```sh
cd ~/QubesIncoming/"${qube}"/qusal
```
6. 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
@ -93,19 +112,20 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d
```sh ```sh
tag_list="$(git tag --points-at=HEAD)" tag_list="$(git tag --points-at=HEAD)"
verification=0 verified=0
for tag in ${tag_list}; do for tag in ${tag_list}; do
if git verify-tag "${tag}" if git verify-tag "${tag}"
verification=1 verified=1
break break
fi fi
done done
if test "${verification}" = "0"; then if test "${verified}" = "0"; then
printf '%s\n' "Failed to verify qusal" >&2
false false
fi fi
``` ```
6. Copy the project to the Salt directories: 7. Copy the project to the Salt directories:
```sh ```sh
~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh ~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh
@ -183,7 +203,7 @@ files from being tracked and signature verification won't catch it.
file="CHANGEME" # path to the repository in the qube file="CHANGEME" # path to the repository in the qube
rm -rf ~/QubesIncoming/"${qube}"/qusal rm -rf ~/QubesIncoming/"${qube}"/qusal
UPDATES_MAX_FILES=10000 qvm-copy-to-dom0 "${qube}" "${file}" UPDATES_MAX_FILES=50000 qvm-copy-to-dom0 "${qube}" "${file}"
``` ```
3. Verify the commit or tag signature as shown in 3. Verify the commit or tag signature as shown in

View File

@ -54,6 +54,10 @@ test "${xtrace}" = 0 || set -x
for file in ${files}; do for file in ${files}; do
test "${xtrace}" = 0 || set -x test "${xtrace}" = 0 || set -x
case "${file}" in
.reuse/dep5) continue;;
*) ;;
esac
file="${file#./}" file="${file#./}"
set +x set +x
awk -v year="${year}" -v email="${email}" -v file="${file}" -- ' awk -v year="${year}" -v email="${email}" -v file="${file}" -- '