xsos -- a tool for sysadmins and support techs

Latest response

My public yum repo now includes an rpm for xsos.

For those unfamiliar with xsos, well... a picture is worth a hundred words in this case, so I'll give you 1000+ words covering some of what xsos can do. Note that some of these screenshots were generated by querying sosreports and some of them were generated by executing xsos live on running systems.

xsos (run with no options)

xsos --os --mem --scrub-ip

xsos --bios --ip --scrub-mac


xsos --cpu --lspci --netdev


xsos --ethtool


xsos --bonding


xsos --ps


xsos --kdump


xsos --sysctl


This next one illustrates something special ...


xsos --cpu --intrupt


xsos --softirq
(This one does some diagnosing based on the file /proc/net/softnet_stat. See RFE #108 for details.)


Finally, here's the verbose version of the xsos help page (there's a shorter -h as well)
xsos --help

Usage: xsos [DISPLAY OPTIONS] [-6abokcfmdtlerngisp] [SOSREPORT ROOT]
  or:  xsos [DISPLAY OPTIONS] {--B|--C|--F|--M|--D|--T|--L|--R|--N|--G|--I|--P FILE}...
  or:  xsos [-?|-h|--help]
  or:  xsos [-U|--update]

Display system info from localhost or extracted sosreport
Run with "-h" to see simplified help page

Content options:
 -a, --all      show everything
 -b, --bios     show info from dmidecode
 -o, --os       show hostname, distro, SELinux, kernel info, uptime, etc
 -k, --kdump    inspect kdump configuration
 -c, --cpu      show info from /proc/cpuinfo
 -f, --intrupt  show info from /proc/interrupts
 -m, --mem      show info from /proc/meminfo
 -d, --disks    show info from /proc/partitions + dm-multipath synopsis
 -t, --mpath    show info from dm-multipath
 -l, --lspci    show info from lspci
 -e, --ethtool  show info from ethtool
 -r, --softirq  show info from /proc/net/softnet_stat
 -n, --netdev   show info from /proc/net/dev
 -g, --bonding  show info from /proc/net/bonding
 -i, --ip       show info from ip addr (BASH v4+ required)
     --net      alias for: --lspci --ethtool --softirq --netdev --bonding --ip
 -s, --sysctl   show important kernel sysctls
 -p, --ps       inspect running processes via ps

Display options:
     --scrub-ip     remove IP addresses & hostnames from output
     --scrub-mac    remove HW MAC addresses from output
                    see XSOS_SCRUB_IP_HN & XSOS_SCRUB_MACADDR env vars
 -6, --ipv6         parse ip addr output for IPv6 addresses instead of IPv4
 -q, --wwid=ID      restrict dm-multipath output to a particular mpath device,
                    where ID is a wwid, friendly name, or LUN identifier
 -u, --unit=P       change byte display for /proc/meminfo & /proc/net/dev,
                    where P is "b" for byte, or else "k", "m", "g", or "t"
 -v, --verbose=NUM  specify ps verbosity level (0-4, default: 1)
 -w, --width=NUM    change fold-width, in columns (positive number, e.g., 80)
                    "0" disables wrapping, "w" autodetects width (default)
 -x, --nocolor      disable output colorization
 -y, --less         send output to `less -SR`
 -z, --more         send output to `more`

If no content options are specified, xsos parses the environment variable
XSOS_DEFAULT_VIEW to figure out what information to display. If this variable
is unset at runtime, it is initialized internally as follows:

   XSOS_DEFAULT_VIEW='os'

Tweak it to preference by adding additional space-separated MODULE statements,
where MODULE is the same as the long option (e.g. mem, ethtool, netdev). Note
that the --net alias option cannot be used for this purpose. Also note that the
-a / --all option has it's own environment variable: XSOS_ALL_VIEW

If SOSREPORT ROOT isn't provided, the data will be gathered from the localhost;
however, bios, multipath, and ethtool output will only be displayed if running
as root (UID 0). When executing in this manner as non-root, those modules will
be skipped, and a warning printed to stderr.

Sometimes a full sosreport isn't available; sometimes you simply have a
dmidecode-dump or the contents of /proc/meminfo and you'd like a summary...

Special options (BASH v4+ required):
 --B=FILE  read from FILE containing `dmidecode` dump
 --C=FILE  read from FILE containing /proc/cpuinfo dump
 --F=FILE  read from FILE containing /proc/interrupts dump
 --M=FILE  read from FILE containing /proc/meminfo dump
 --D=FILE  read from FILE containing /proc/partitions dump
 --T=FILE  read from FILE containing `multipath -v4 -ll` dump
 --L=FILE  read from FILE containing `lspci` dump
 --R=FILE  read from FILE containing /proc/net/softnet_stat dump
 --N=FILE  read from FILE containing /proc/net/dev dump
 --G=FILE  read from FILE containing /proc/net/bonding/xxx dump
 --I=FILE  read from FILE containing `ip addr` dump
 --P=FILE  read from FILE containing `ps aux` dump

As is hopefully clear, each of these options requires a filename as an
argument. These options can be used together, but cannot be used in concert
with regular "Content options" -- Content opts are ignored if Special options
are detected. Also note: the "=" can be replaced with a space if desired.

Re BASH v4+:
 BASH associative arrays are used for various things. In short, if running
 xsos on earlier BASH versions (e.g. RHEL5), you get ...
  * No output colorization
  * No -i/--ip
  * No parsing of "Special options"

Environment variables:
 For details of all configurable env variables, view first page of xsos
 source. There are vars to change default colors as well as other settings.
 Each variable name is prefixed with "XSOS_" and the important ones follow.
  COLORS  FOLD_WIDTH  ALL_VIEW  DEFAULT_VIEW  HEADING_SEPARATOR  IP_VERSION
  MEM_UNIT  NET_UNIT  PS_UNIT  PS_LEVEL  UPDATE_CONFIRM  OUTPUT_HANDLER
  SCRUB_IP_HN  SCRUB_MACADDR  ETHTOOL_ERR_REGEX

Version info: xsos v0.5.17 last mod 2015/04/12
See <github.com/ryran/xsos> to report bugs or suggestions

Necessary disclaimer: xsos is an open-source utility developed by me in my free time. I happen to be a Red Hat employee; that does not mean that xsos is shipped, supported, or officially condoned by Red Hat. If you can keep that in mind, you are free to post problems or questions here OR on the github issue tracker.

Ryan Sawhill's picture

Responses