From ec8a9f8003222c0510e141194b4b9fc8519ba03f Mon Sep 17 00:00:00 2001
From: Ben Grande <ben.grande.b@gmail.com>
Date: Tue, 18 Jun 2024 15:10:46 +0200
Subject: [PATCH] doc: add troubleshooting guide

---
 README.md               |  5 ++-
 docs/SALT.md            | 17 ++--------
 docs/TROUBLESHOOTING.md | 71 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 78 insertions(+), 15 deletions(-)
 create mode 100644 docs/TROUBLESHOOTING.md

diff --git a/README.md b/README.md
index f5deee60..a23e9606 100644
--- a/README.md
+++ b/README.md
@@ -50,9 +50,12 @@ Here are some of the Global Preferences we can manage:
 - **management_dispvm**: dvm-mgmt
 - **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall
 
-If you want to learn more about how we make decisions, take a look at our
+To learn more about how we make decisions, take a look at our
 [design document](docs/DESIGN.md).
 
+To troubleshoot issues, read our
+[troubleshooting document](docs/TROUBLESHOOTING.md).
+
 ## Installation
 
 ### Prerequisites
diff --git a/docs/SALT.md b/docs/SALT.md
index a2e4464b..772b1aab 100644
--- a/docs/SALT.md
+++ b/docs/SALT.md
@@ -242,23 +242,12 @@ Qusal macros. The above examples are based on our [vault formula](../salt/vault)
 
 ## Troubleshooting
 
-The Salt Project has [troubleshooting](https://docs.saltproject.io/en/latest/topics/troubleshooting/)
-page for a variety of problems you may encounter.
-
-A nice summary of the states can be seen with the `--show-output` argument:
-```
-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):
-```
-sudo qubesctl state.apply pkg.uptodate -l debug
-```
-
 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;
+
+For further debugging information on Qusal, read our
+[troubleshooting guide](TROUBLESHOOTING.md).
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
new file mode 100644
index 00000000..70b65c64
--- /dev/null
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,71 @@
+# Troubleshooting
+
+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)
+
+## Detect if your issue was already opened
+
+If you encounter any problems, search the project's
+[issue tracking system](https://github.com/ben-grande/qusal/issues?q=is%3Aissue+sort%3Aupdated-desc)
+for `Open` and `Closed` issues, sorted by `Recently updated`. For finer
+grained search, consult the
+[tracking system filter syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests#using-search-to-filter-issues-and-pull-requests).
+
+## Qrexec client shows Request refused
+
+The Qrexec call was denied, either by a missing rule, an explicit deny or a
+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.
+
+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
+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
+```
+
+## Salt wrapper qubesctl command fails
+
+The Salt Project has [troubleshooting](https://docs.saltproject.io/en/latest/topics/troubleshooting/)
+page for a variety of problems you may encounter.
+
+A nice summary of the states can be seen with the `--show-output` argument:
+```
+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):
+```
+sudo qubesctl state.apply pkg.uptodate -l debug
+```