From a59a35860c55c78379edd2b57419a1a8f3d9ea87 Mon Sep 17 00:00:00 2001
From: Ben Grande <ben.grande.b@gmail.com>
Date: Fri, 15 Mar 2024 17:14:06 +0100
Subject: [PATCH] doc: troubleshoot salt

---
 docs/SALT.md | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/docs/SALT.md b/docs/SALT.md
index 86c5faf..a31ae28 100644
--- a/docs/SALT.md
+++ b/docs/SALT.md
@@ -222,18 +222,41 @@ After you have created the states above, copy them to Dom0 in `/srv/salt`.
 
 Create the qube:
 ```sh
-qubesctl state.apply create-keys
+sudo qubesctl state.apply create-keys
 ```
 
 Install packages in the qube template:
 ```sh
-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:
 ```sh
-qubesctl state.apply appmenus-keys
+sudo qubesctl state.apply appmenus-keys
 ```
 
 Congratulations, you have applied you first desired state with the benefit of
 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;