1sos(1) General Commands Manual sos(1)
2
6 sos - A unified tool for collecting system logs and other debug infor‐
7 mation
8
10 sos component [options]
11
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 The most well known function is sos report or sosreport as it was pre‐
19 viously known.
20 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
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 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 See sos report --help and man sos-report for more information.
40 May also be invoked via the alias rep or the deprecated command
42 sosreport.
43 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 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 See sos collect --help and man sos-collect for more information.
58 May also be invoked via the alias sos collector or the depre‐
60 cated command sos-collector.
61 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 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 See sos clean --help and man sos-clean for more information.
77 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 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 See sos help --help and man sos-help for more information.
88
91 sos components provide their own set of options, however the following
92 are available to be set across all components.
93 --batch Do not prompt interactively, user will not be prompted for any
95 data
96 --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 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 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 See the sections on --encrypt-key and --encrypt-pass below for
120 more information.
121 --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 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 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 This means that only the encrypted archive is present on disk
144 after sos finishes running.
145 If encryption fails for any reason, the original unencrypted ar‐
147 chive is preserved instead.
148 --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 --config-file CONFIG
154 Specify alternate configuration file.
155 -s, --sysroot SYSROOT
157 Specify an alternate root file system path.
158 --tmp-dir DIRECTORY
160 Specify alternate temporary directory to copy data during execu‐
161 tion.
162 --threads THREADS
164 Specify the number of threads sosreport will use for concur‐
165 rency. Defaults to 4.
166 -v, --verbose
168 Increase logging verbosity. May be specified multiple times to
169 enable additional debugging messages.
170 The following table summarizes the effects of different ver‐
172 bosity levels:
173 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 -q, --quiet
183 Only log fatal errors to stderr.
184 -z, --compression-type {auto|xz|gzip}
186 Compression type to use when compression the final archive out‐
187 put
188 --help Display usage message.
190
192 sos.conf(5)
193
195 Maintained on GitHub at https://github.com/sosreport/sos
196
198 See AUTHORS file in the package documentation.
199 April 2020 sos(1)