aboutsummaryrefslogtreecommitdiffstats
path: root/man/en
diff options
context:
space:
mode:
authorJake Hunsaker <jhunsake@redhat.com>2020-05-21 16:32:06 -0400
committerJake Hunsaker <jhunsake@redhat.com>2020-06-17 12:11:29 -0400
commitaf0f418b7f5fd677cf153b97c7a8f980b5728aaf (patch)
tree7041590882f8375b7b611ffba83a33ad3ff36772 /man/en
parentf812812b60c10d8e64a8993851f9b24a674e629c (diff)
downloadsos-af0f418b7f5fd677cf153b97c7a8f980b5728aaf.tar.gz
[docs] Add manpage for sos clean
Adds a manpage for `sos clean`, with a link for `sos mask`. Updates `man sos` as well to include the options moved into the global group as part of the SoSCleaner patchset. Related: #1987 Signed-off-by: Jake Hunsaker <jhunsake@redhat.com>
Diffstat (limited to 'man/en')
-rw-r--r--man/en/sos-clean.164
l---------man/en/sos-mask.11
-rw-r--r--man/en/sos.150
3 files changed, 115 insertions, 0 deletions
diff --git a/man/en/sos-clean.1 b/man/en/sos-clean.1
new file mode 100644
index 00000000..729c812f
--- /dev/null
+++ b/man/en/sos-clean.1
@@ -0,0 +1,64 @@
+.TH SOS CLEAN 1 "Thu May 21 2020"
+.SH NAME
+sos clean - Obfuscate sensitive data from one or more sosreports
+.SH SYNOPSIS
+.B sos clean TARGET [options]
+ [\-\-map]
+ [\-\-jobs]
+ [\-\-no-update]
+
+.SH DESCRIPTION
+\fBsos clean\fR or \fBsos mask\fR is an sos subcommand used to obfuscate sensitive information from
+previously generated sosreports that is not covered by the standard plugin-based post
+processing executed during report generation, for example IP addresses.
+.LP
+Data obfuscated via this utility is done so consistently, meaning for example an IP address of
+192.168.1.1 in an unprocessed sosreport that gets obfuscated to, for example, 100.0.0.1, will be
+changed to 100.0.0.1 in all occurences found in the report.
+
+Additionally, by default all such obfuscations are stored in "maps" that will be persistently
+saved to /etc/sos/cleaner/default_mappings and be re-used on subsequent runs.
+.LP
+This utility may also be used in-line with \fBsos report\fR and \fB sos collect\fR by specifying the
+\fB\-\-clean\fR or \fB\-\-mask\fR option.
+.LP
+When called directly via \fBsos clean\fR, the obfuscated archive is written as an additional file,
+meaning the original unprocessed report still remains on the filesystem. When called via \fBreport\fR or
+\fBcollect\fR, the changes are done in-line and thus only an obfuscated archive is written and available.
+In either case, a mapping file containing the relationships between unprocessed and obfuscated elements will
+be written in the same location as the resulting archive. This mapping file should be kept private
+by system administrators.
+
+.SH REQUIRED ARGUMENTS
+.B TARGET
+.TP
+The path to the archive that is to be obfuscated. This may be an archive or an unbuilt sos temporary
+directory. If an archive, it will first be extracted and then after obfuscation is complete re-compressed
+using the same compression method as the original.
+
+.SH OPTIONS
+
+.TP
+.B \-\-map FILE
+Provide a location to a valid mapping file to use as a reference for existing obfuscation pairs.
+If one is found, the contents are loaded before parsing is started. This allows consistency between
+runs of this command for obfuscated pairs. By default, sos will write the generated private map file
+to /etc/sos/cleaner/default_mapping so that consistency is maintained by default. Users may use this
+option to reference a map file from a different run (perhaps one that was done on another system).
+
+Default: /etc/sos/cleaner/default_mapping
+.TP
+.B \-\-jobs JOBS
+The number of concurrent archives to process, if more than one. If this utility is called by
+\fBsos collect\fR then the value of the jobs option for that utility will be used here.
+
+Default: 4
+.TP
+.B \-\-no-update
+Do not write the mapping file contents to /etc/sos/cleaner/default_mapping
+.SH MAINTAINER
+.nf
+Jake Hunsaker <jhunsake@redhat.com>
+.fi
+.SH AUTHORS & CONTRIBUTORS
+See \fBAUTHORS\fR file in the package documentation.
diff --git a/man/en/sos-mask.1 b/man/en/sos-mask.1
new file mode 120000
index 00000000..1a9baf9d
--- /dev/null
+++ b/man/en/sos-mask.1
@@ -0,0 +1 @@
+sos-clean.1 \ No newline at end of file
diff --git a/man/en/sos.1 b/man/en/sos.1
index 0444dba4..af1a5287 100644
--- a/man/en/sos.1
+++ b/man/en/sos.1
@@ -49,10 +49,57 @@ See \fBsos collect --help\fR and \fBman sos-collect\fR for more information.
May also be invoked via the alias \fBsos collector\fR or the deprecated command
\fBsos-collector\fR.
+.TP
+.B clean|mask
+This subcommand takes input of either 1) an sosreport tarball, 2) a collection
+of sosreport tarballs such as from \fBcollect\fR, or 3) the unpackaged
+directory of an sosreport and obfuscates potentially sensitive system information
+that is not covered by the standard postprocessing of \fBsos report\fR.
+
+Such data includes IP addresses, networks, MAC addresses, and more. Data obfuscated
+by this command will remain consistent throughout the report and across reports provided
+in the same invocation. Additionally, care is taken to maintain network topology relationships
+between matched data items.
+
+See \fB sos clean --help\fR and \fBman sos-clean\fR for more information.
+
+May be invoked via either \fBsos clean\fR, \fBsos mask\fR, or via the \fB--clean\fR or \fB --mask\fR options
+for \fBreport\fR and \fBcollect\fR.
+
.SH GLOBAL OPTIONS
sos components provide their own set of options, however the following are available
to be set across all components.
+.B \-\-batch
+Do not prompt interactively, user will not be prompted for any data
+.TP
+.B \--encrypt-key KEY
+Encrypts the resulting archive that sosreport produces using GPG. KEY must be
+an existing key in the user's keyring as GPG does not allow for keyfiles.
+KEY can be any value accepted by gpg's 'recipient' option.
+
+Note that the user running sosreport must match the user owning the keyring
+from which keys will be obtained. In particular this means that if sudo is
+used to run sosreport, the keyring must also be set up using sudo
+(or direct shell access to the account).
+
+Users should be aware that encrypting the final archive will result in sos
+using double the amount of temporary disk space - the encrypted archive must be
+written as a separate, rather than replacement, file within the temp directory
+that sos writes the archive to. However, since the encrypted archive will be
+the same size as the original archive, there is no additional space consumption
+once the temporary directory is removed at the end of execution.
+
+This means that only the encrypted archive is present on disk after sos
+finishes running.
+
+If encryption fails for any reason, the original unencrypted archive is
+preserved instead.
+.TP
+.B \--encrypt-pass PASS
+The same as \--encrypt-key, but use the provided PASS for symmetric encryption
+rather than key-pair encryption.
+.TP
.B \--config-file CONFIG
Specify alternate configuration file.
.TP
@@ -72,6 +119,9 @@ additional debugging messages.
.B \-q, \--quiet
Only log fatal errors to stderr.
.TP
+.B \-z, \-\-compression-type {auto|xz|gzip}
+Compression type to use when compression the final archive output
+.TP
.B \--help
Display usage message.
.SH MAINTAINER