TL;DR

# yum install op5-support-release
# yum install ist
# ist collect -t <YOUR-TICKET-NUMBER> [optional module(s)]

Introduction

To facilitate easy collection of files and system information for troubleshooting, and analysis by our Client Services Analysts, we provide a tool named ist-collect. The name stands for "ITRS Support Tool - Collector".

ist-collect is part of a collection of tools run through the wrapper ist.

ist-collect will automate the collection of many files. It will also run a series of commands and collect the output from these. It then adds these to a tar.xz archive suitable for submission to an existing ticket.

For more information on how to inspect the data being collected by ist-collect, see this article.

Usage

Preface

The ist packages are located in the op5-support-updates repository, which you must first activate if you want to install them. The reason for this division is that ist is developed and maintained by Client Services rather than OP5 Engineering. However, rest assured that it's only developed in-house.

Client Services will handle any bugs rather than OP5 Engineering.

Installation

Enable the op5-support-updates repository:

# yum install op5-support-release

Install the wrapper package:

# yum install ist

Example usage

The typical usage would be:

# ist collect -t 123456

This would collect most of the interesting files from the current machine, as well as a collection of command outputs to display system information. ist would create an archive in the /tmp folder and the name would include the ticket number "123456" for easy reference.

Help text

The help text contains much useful information that you can view with the option -h or --help.

ITRS Support Tool - Collect is a tool for collecting data relevant to product support.

Usage: ist collect [-adsSu] [-n|-y] [-t NUM] [-T PATH]
ist collect [-adSu] [-n|-y] [-t NUM] [-T PATH] [module...]
ist collect [-dsSu] [-n|-y] [-N NAME]... [-t NUM] [-T PATH]
ist collect [-dSu] [-n|-y] [-N NAME]... [-t NUM] [-T PATH] [module...]
ist collect [-cd] [-n|-y] [-T PATH]
ist collect [-h]
ist collect [-l] [module...]
ist collect [-L]
ist collect [-v]

Options:
-a, --all-nodes Extend the collection to all nodes in the cluster.
-c, --cleanup Delete old files from previous runs of ist-collect.
-d, --debug Set log level to debug.
-h, --help Print this help message.
-l, --list-files List files that would be collected.
-L, --list-nodes List all nodes in the cluster available to ist-collect.
-n, --assume-no Assume 'no' at any prompt to delete old files.
-N, --node NAME Remote nodes to collect from, except for the local node.
-s, --skip-files Skip file collection, only produce information files.
-S, --single-thread Use only a single thread for data collection.
-t, --ticket-id ID no-id Specify the ticket ID.
-T, --tmp-path PATH false Specify a custom path for work and archive delivery.
-u, --keep-unix-timestamps Keep Unix timestamps in logfiles.
-v, --version Print the current version number of ist-collect.
-y, --assume-yes Assume 'yes' at any prompt to delete old files.

Notes:
* ist-collect MUST be run as root.

* Without any modules specified, all modules will be collected by default.

* The collection is done in parallel when there are more than one node
from which data is to be collected. This can be disabled using the
--single-thread option. Using this option is advised if system load is a
concern.

* Without the options '-a' or '-N' ist-collect will only collect files
from the local node.

* The option '-a' simply extends the collection to all (reachable) nodes
in the cluster. It's agnostic to all other options. See the examples for
more details on this.

* The option '-N' works in the same way as option '-a', but only to the
nodes specified. This option can be repeated to select multiple nodes.
The local node will always be included.

* The collection is essentially (see next note) non-destructive and will
only write to the designated tmp-path (default '/tmp').

* Apart from temporary files that were created during the collection, the
only files that will be deleted are old ist-collect files. These may be
located in the tmp-path, in '/tmp' or in '/var/www/html'. The deletion
of these files are optional and ist-collect will prompt before deleting
them unless one of the flags '--assume-no' or '--assume-yes' have been
used.

* The archive being produced by ist-collect can easily be read by the user
before sending it to ITRS. Nothing is automatically sent to ITRS.

* The option '-l' will only show what files would be collected from the
local node. It's not currently possible to calculate this for remote
nodes using this flag.

* The option '-l' can be used together with one or more modules to get a
list of files that would be collected using said module(s).

Modules:
The following modules are available in this version of ist-collect:

autodiscovery
backup
cron
httpd
ldap*
livestatus
lmd
logging
mayi*
merlin
mysql
nachos
nacoma
naemon*
nagvis
network
ninja
notify
php
pnp
postfix*
queryhandler
secure*
smsd*
snmpscan
ssh*
synergy
syslog*
trapper
vmware
yum

All of the modules above can include other sensitive data from your
environment, such as IP-addresses usernames and passwords. You may want
to submit the collected data to ITRS over a secure channel.

The modules marked with an asterisk (*) may contain particularly
sensitive information, such as phone numbers, email addresses, names,
and similar.

Examples:
# ist collect -a
Collect files (and information) from ALL nodes in the cluster.

# ist collect -c
Clean up old files.

# ist collect nachos ninja nacoma
Collect files ONLY related to the modules nachos, ninja, and nacoma from
the local node. Also collect the general system and cluster information
from the local node.

# ist collect -a nachos ninja nacoma
Collect files ONLY related to the modules nachos, ninja, and nacoma from
ALL nodes in the cluster. Also collect the general system and cluster
information from ALL nodes in the cluster.

# ist collect -a -s -t 123456
Do NOT collect any logfiles or configs, but generate information files for
ALL nodes in the cluster and name the archive with the ticket number
'123456'.

# ist collect -a -s -t 123456 -T /mnt/data
Do NOT collect any logfiles or configs, but generate information files for
ALL nodes in the cluster and name the archive with the ticket number
'123456'. Save the resulting archive at '/mnt/data' and use that same
directory for temporary files during collection.

# ist collect -t 123456
Collect files (and information) from the local node and name the archive
with the ticket number '123456'. This is a very typical use case.

# ist collect -t 123456 -N foo -N bar
Collect files (and information) from the local node, as well as the remote
nodes 'foo' and 'bar', and name the archive with the ticket number
'123456'.

# ist collect -t 123456 -N foo -N bar naemon
Collect files ONLY related to the module naemon (as well as system
information) from the local node, as well as the remote nodes 'foo' and
'bar', and name the archive with the ticket number '123456'.

Collecting files and data from the whole cluster

If you are using an OP5 environment with multiple nodes, you should run ist-collect on the primary master unless instructed otherwise by Client Services. To collect information from all nodes in the cluster (except where "connect = no" is defined in merlin.conf), run ist-collect with the option -a.

# ist collect -a -t 123456

Collecting files related to specific modules

Most times, it's already known what part of the product is causing a problem. In such cases, it would usually be beneficial to only collect related files. To do this, simply list the wanted modules as arguments to ist-collect.

Example, collecting files related to merlin, nachos and nacoma:

# ist collect -t 123456 merlin nachos nacoma

The above command would only collect files related to merlin, nachos, and nacoma. A current list of available modules can be printed with the option -m.

Downloading the archive

By default, ist will place the archive in the /tmp folder. You can change this behavior by using the option -T.

Windows

For Windows users, we recommend the excellent tool WinSCP that can you can download here. When installed, connect to your server using the credentials provided by the server administrator and download the file from the /tmp folder.

Linux and MacOS

Use the common Unix tool scp to download the file. Assuming that the file is in /tmp something similar would do the job:

$ scp HOSTNAME:/tmp/FILENAME.tar.xz ~/Downloads/

Edit HOSTNAME and FILENAME and change the location to something other than ~/Downloads/ where applicable.

Uninstallation

Should you no longer wish to have ist on your system, you may remove it using yum:

# yum remove ist

To disable the op5-support-updates repository, do:

# yum remove op5-support-release