Improve Salt documentation

[andrewdavidwong]

Our Salt documentation is here: https://www.qubes-os.org/doc/salt/

After reading this page, I have trouble comprehending:

• What exactly Salt is for (in the context of Qubes)
  • Does it allow us to do new things that were impossible before, or is it just supposed to make things we've already been doing easier?
  • If it's supposed to make things easier, why is there such an enormous learning curve? ("For more exhaustive documentation, visit official site, though we must warn you that it is not easy to read if you just start working with salt and know nothing.")
• Who Salt is meant for (in the context of Qubes)
  • People managing fleets of Qubes machines?
  • Qubes developers?
  • All users?
• From a user's perspective: whether it's worth my time and effort to learn more about it
  • The documentation reads like it's for Salt developers. It seems to assume that you already know what Salt is and how to use it. This suggests that, if you're just a regular user, Salt is not for you. Yet, on the mailing lists, Salt is talked about like it's a way to simplify things that we previously used the command line to accomplish, and users and sometimes told to execute salt commands as a way of achieving things.

Related thread: https://groups.google.com/d/topic/qubes-users/zqr2mOxrSBE/discussion

[andrewdavidwong]

Great explanation and examples: https://groups.google.com/d/msgid/qubes-users/20160511100846.GC25975%40mail-itl

[andrewdavidwong]

This should be either linked to or incorporated into the documentation:

https://www.qubes-os.org/news/2015/12/14/mgmt-stack/

[maxsu]

Thanks for finding those use cases. I found the salt documentation a bit abstract and general; it gets rather hectic/busy without first providing an easy entry-point or "hello world" case to allow a user to ease into creating their own states.

It turns out states by themselves can be pretty simple and I believe that before documenting the various salt states that are available it might be easier to link the user a simple tutorial. Something very simple for example:

• Here is how to configure a torrent client VM and route it through a dedicated VPN VM.

When I get around to doing that I'll write it up as a tutorial and push it to documentation as stand-alone tutorial or an inline example.

Imo this could really provide value to anyone daring to deploy Qubes in a development/operations type of environment (or just goofy enough to want to automate their personal work environment) - they'd certainly have their work cut out for them, so lets give them a basic starting point!

[andrewdavidwong]

Sounds good, @maxsu! Looking forward to the PR!

[tasket]

@maxsu I would like to see that as well, as I want to create a salt state to setup a VPN.

I've been trying to learn saltstack for a few weeks now, but the documentation is outright novice-hostile. It spouts off about advanced options in the second or third paragraphs of each topic and rarely returns to Earth. An unfortunate example:
https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html

To throw a little cold water on our 'appreciation' for salt, I thought I'd share this:
https://stevebennett.me/2014/02/17/one-week-of-salt-frustrations-and-reflections/
...the comments are pretty interesting as well. The upside is that the commiseration can lead to some constructive explanations and examples. It helps to know that salt syntax has an issue with inconsistency, so I can take a more 'cookbook' approach to learning it.

Recently, I thought I was making progress then realized salt states cannot refer to files with dots in them. So... why even try out the config?

As for Marek's two examples from qubes-users: One is heavily templated, the other is chopped-up into files with perplexingly generic names raising the question of where they should be saved and how they are executed. Also can't figure out why Qubes has salt dirs named with underscores, giving the impression the Qubes doc is referring to a salt configuration that is different than actual.

[adrelanos]

sudo qubesctl top.enabled
sudo qubesctl top.disabled
sudo qubesctl state.sls qvm.anon-whonix
sudo qubesctl --templates pkg.upgrade

This is what sudo qubesctl state.sls qvm.anon-whonix does:
https://www.whonix.org/wiki/Dev/Qubes#salt

Related:
#3447

[awokd]

the documentation is outright novice-hostile

This made me laugh but I have trouble bootstrapping myself from it too. I think Salt is even more important under R4.0, but don't have the skill set needed to update the document. Is @maxsu still out there?