From 17e5055accf833fd8d7fa5ec12710875b6315122 Mon Sep 17 00:00:00 2001
From: Jake Hunsaker <jhunsake@redhat.com>
Date: Thu, 9 Jul 2020 10:36:03 -0400
Subject: [docs] Update man page for sos.conf after configuration redesign

Updates the manpage for further changes to the configuration design of
sos. `man sos.conf` now includes information on non-root user overrides,
as well as information regarding the subdirectories under `/etc/sos/` or
`$HOME/.config/sos/`.

The `sos_extras` plugin docstring has been copied into the man page as
well for better coverage of how users are expected to use that plugin.
The docstring remains in place in the actual plugin as well.

Signed-off-by: Jake Hunsaker <jhunsake@redhat.com>
---
 man/en/sos-report.1 |  3 +++
 man/en/sos.conf.5   | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 76 insertions(+), 2 deletions(-)

(limited to 'man')

diff --git a/man/en/sos-report.1 b/man/en/sos-report.1
index 41758e79..f4de8083 100644
--- a/man/en/sos-report.1
+++ b/man/en/sos-report.1
@@ -116,6 +116,9 @@ Note: to set a description for the preset that is displayed with \fB--list-prese
 use the \fB--desc\fR option.
 
 Note: to set a behaviour note of the preset, use --note option.
+
+Note: The root filesystem, as seen by sos if running within a container, must be
+writable to save presets using this option.
 .TP
 .B \--del-preset DEL_PRESET
 Deletes the preset with name DEL_PRESET from the filesystem so that it can no
diff --git a/man/en/sos.conf.5 b/man/en/sos.conf.5
index 248af60c..442b699d 100644
--- a/man/en/sos.conf.5
+++ b/man/en/sos.conf.5
@@ -3,7 +3,76 @@
 sos.conf \- sosreport configuration
 .SH DESCRIPTION
 .sp
-sosreport uses a configuration file at /etc/sos/sos.conf.
+sosreport uses a configuration file at /etc/sos/sos.conf, and there are
+subdirectories under /etc/sos that are used for specific purposes.
+
+Note that non-root users may override options set in /etc/sos/sos.conf by creating
+their own sos.conf under $HOME/.config/sos.
+
+The order in which options are loaded is as follows:
+
+  1. System configuration file at /etc/sos/sos.conf
+  2. User-specific configuration file at $HOME/.config/sos/sos.conf (for sos
+     components that support non-root)
+  3. In the case of running \fBsos report\fR, presets either automatically loaded
+     due to system configuration, or specified via \fB--preset\fR
+  4. Command line values
+
+
+In other words, config files will override defaults, presets override config files,
+and command line values override presets and config files.
+
+.SH SUBDIRECTORIES
+The following subdirectories exist under /etc/sos and are used as noted below
+
+.TP
+\fBextras.d\fP
+This directory is used to store configuration files used by the sos_extras plugin.
+
+The plugin traverses this directory and for each file there it executes commands
+or collects files optionally with sizelimit.
+
+Expected content of an extras file is as follows:
+    - empty lines or those starting with '#' are ignored
+    - add_copy_spec called to lines starting by ':', optionally followed by
+      sizelimit
+    - otherwise, whole line will be executed as a command.
+    Example:
+    command1 --arg1 val1
+    command2
+    :/path/to/file
+    :/path/to/files* sizelimit
+
+    WARNING: be careful what files to collect or what commands to execute:
+    - avoid calling potentially dangerous or system altering commands, like:
+      - using multiple commands on a line (via pipes, semicolon etc.)
+      - executing commands on background
+      - setting env.variables (as those will be ignored)
+      - altering a system (not only by "rm -rf")
+    - be aware, no secret obfuscation is made
+.TP
+\fBgroups.d\fP
+This directory is used to store host group configuration files for \fBsos collect\fP.
+
+These files can specify any/all of the \fBmaster\fP, \fBnodes\fP, and \fBcluster-type\fP
+options.
+
+Users may create their own private host groups in $HOME/.config/sos/groups.d/. If
+a host group of the same name is saved in both the user's homedir and this directory,
+the homedir configuration file will have precedence. When run as non-root, \fBsos collect\fP
+will save host groups to the user's home dir, and create the necessary directory structure
+if required.
+
+Note that non-root users may load host groups defined under /etc/sos/groups.d/, but they
+may not write new groups or update existing groups saved there.
+
+.TP
+\fBpresets.d\fP
+This directory is used to store preset configuration files for \fBsos report\fP.
+
+Presets may be used to save standard sets of options. See \fBman sos-report\fP for
+more information.
+
 .SH PARAMETERS
 .sp
 There are sections for each sos component, as well as global values and
@@ -53,7 +122,7 @@ To disable the 'host' and 'filesys' plugins:
 .LP
 [report]
 .br
-noplugins = host,filesys
+skip-plugins = host,filesys
 .sp
 To disable rpm package verification in the RPM plugin:
 .LP
@@ -64,6 +133,8 @@ rpm.rpmva = off
 .SH FILES
 .sp
 /etc/sos/sos.conf
+.br
+$HOME/.config/sos/sos.conf (optional)
 .SH SEE ALSO
 .sp
 sos-report(1)
-- 
cgit