1sos(1)                      General Commands Manual                     sos(1)
2
3
4

NAME

6       sos  - A unified tool for collecting system logs and other debug infor‐
7       mation
8

SYNOPSIS

10       sos component [options]
11
12

DESCRIPTION

14       sos is a diagnostic data collection utility, used by system administra‐
15       tors,  support representatives, and the like to assist in troubleshoot‐
16       ing issues with a system or group of systems.
17
18       The most well known function is  sos report or sosreport as it was pre‐
19       viously known.
20
21       An  sos archive is typically requested by support organizations to col‐
22       lect baseline configuration and system data from  which  to  begin  the
23       troubleshooting process.
24
25
26

COMPONENTS

28       sos supports several subcommands or components. Each provides a differ‐
29       ent set of information for the user. Supported components are  as  fol‐
30       lows
31
32
33       report Report generates an archive of system information including con‐
34              figuration files and command output. Information included in the
35              report  is  based  upon plugins that are activated automatically
36              when certain criteria, such as installed packages,  files,  ser‐
37              vices, or system architecture is detected.
38
39              See sos report --help and man sos-report for more information.
40
41              May  also be invoked via the alias rep or the deprecated command
42              sosreport.
43
44
45       collect
46              Collect is used to capture reports on multiple systems  simulta‐
47              neously.  These systems can either be defined by the user at the
48              command line and/or defined by clustering software  that  exists
49              either on the local system or on a "primary" system that is able
50              to inform about other nodes in the cluster.
51
52              When running collect, sos report  will  be  run  on  the  remote
53              nodes, and then the resulting archives will be copied from those
54              nodes to the local system running sos collect. Archives are then
55              removed from the remote systems.
56
57              See sos collect --help and man sos-collect for more information.
58
59              May  also  be  invoked via the alias sos collector or the depre‐
60              cated command sos-collector.
61
62
63       clean|cleaner|mask
64              This subcommand takes input of either 1) an  sosreport  tarball,
65              2)  a  collection of sosreport tarballs such as from collect, or
66              3) the unpackaged directory of an sosreport and  obfuscates  po‐
67              tentially  sensitive  system  information that is not covered by
68              the standard postprocessing of sos report.
69
70              Such data includes IP addresses, networks,  MAC  addresses,  and
71              more.  Data  obfuscated  by  this command will remain consistent
72              throughout the report and across reports provided  in  the  same
73              invocation.  Additionally,  care  is  taken  to maintain network
74              topology relationships between matched data items.
75
76              See  sos clean --help and man sos-clean for more information.
77
78              May be invoked via either sos clean, sos cleaner, sos  mask,  or
79              via  the  --clean,  --cleaner  or  --mask options for report and
80              collect.
81
82
83       help   This subcommand is used to retrieve more detailed information on
84              the  various SoS commands and components than is directly avail‐
85              able in either other manpages or --help output.
86
87              See  sos help --help and  man sos-help for more information.
88
89

GLOBAL OPTIONS

91       sos components provide their own set of options, however the  following
92       are available to be set across all components.
93
94       --batch  Do not prompt interactively, user will not be prompted for any
95       data
96
97       --encrypt
98              Encrypt the resulting archive, and determine the method by which
99              that  encryption  is done by either a user prompt or environment
100              variables.
101
102              When run with --batch, using this option will cause sos to  look
103              for either the SOSENCRYPTKEY or SOSENCRYPTPASS environment vari‐
104              ables. If set, this will implicitly enable the --encrypt-key  or
105              --encrypt-pass  options,  respectively, to the values set by the
106              environment variable. This enables  the  use  of  these  options
107              without  directly setting those options in a config file or com‐
108              mand line string. Note that use of an encryption key has  prece‐
109              dence over a passphrase.
110
111              Otherwise,  using  this option will cause sos to prompt the user
112              to choose the method of  encryption  to  use.  Choices  will  be
113              [P]assphrase,   [K]ey,  [E]nv  vars,  or  [N]o  encryption.   If
114              passphrase or key the user will then be prompted for the respec‐
115              tive value, env vars will cause sos to source the information in
116              the manner stated above, and choosing no encryption will disable
117              encryption.
118
119              See  the  sections on --encrypt-key and --encrypt-pass below for
120              more information.
121
122       --encrypt-key KEY
123              Encrypts the resulting archive  that  sosreport  produces  using
124              GPG.  KEY  must  be an existing key in the user's keyring as GPG
125              does not allow for keyfiles.  KEY can be any value  accepted  by
126              gpg's 'recipient' option.
127
128              Note  that the user running sosreport must match the user owning
129              the keyring from which keys will be obtained. In particular this
130              means  that  if  sudo is used to run sosreport, the keyring must
131              also be set up using sudo (or direct shell  access  to  the  ac‐
132              count).
133
134              Users should be aware that encrypting the final archive will re‐
135              sult in sos using double the amount of temporary  disk  space  -
136              the encrypted archive must be written as a separate, rather than
137              replacement, file within the temp directory that sos writes  the
138              archive  to.  However,  since  the encrypted archive will be the
139              same size as the original archive, there is no additional  space
140              consumption  once  the temporary directory is removed at the end
141              of execution.
142
143              This means that only the encrypted archive is  present  on  disk
144              after sos finishes running.
145
146              If encryption fails for any reason, the original unencrypted ar‐
147              chive is preserved instead.
148
149       --encrypt-pass PASS
150              The same as --encrypt-key, but use the provided PASS for symmet‐
151              ric encryption rather than key-pair encryption.
152
153       --config-file CONFIG
154              Specify alternate configuration file.
155
156       -s, --sysroot SYSROOT
157              Specify an alternate root file system path.
158
159       --tmp-dir DIRECTORY
160              Specify alternate temporary directory to copy data during execu‐
161              tion.
162
163       --threads THREADS
164              Specify the number of threads sosreport  will  use  for  concur‐
165              rency. Defaults to 4.
166
167       -v, --verbose
168              Increase  logging  verbosity. May be specified multiple times to
169              enable additional debugging messages.
170
171              The following table summarizes the  effects  of  different  ver‐
172              bosity levels:
173
174                  1 (-v)   :  Enable debug messages for sos.log. Show individ‐
175              ual plugins starting.
176                  2 (-vv)  :  Also print debug messages to console.
177                  3 (-vvv) :  Enable debug messages for  archive  file  opera‐
178              tions. Note this will dramatically
179                              increase the amount of logging.
180
181
182       -q, --quiet
183              Only log fatal errors to stderr.
184
185       -z, --compression-type {auto|xz|gzip}
186              Compression  type to use when compression the final archive out‐
187              put
188
189       --help Display usage message.
190

SEE ALSO

192       sos.conf(5)
193

MAINTAINER

195       Maintained on GitHub at https://github.com/sosreport/sos
196

AUTHORS & CONTRIBUTORS

198       See AUTHORS file in the package documentation.
199
200
201
202                                  April 2020                            sos(1)
Impressum