snap Command

Purpose

Gathers system configuration information.

Syntax

snap [-@] [ -a ] [-z "product_name=prd_name,..." | "class=myclass,.." | ALL] [-M Timeout][ -A ] [ -b ] [ -B ] [ -c ] [ -C ] [-D ] [ -f ] [ -F] [ -g ] [ -G ] [ -i ] [ -k ] [ -l ] [ -L ][ -n ] [ -N ] [ -p ] [ -r ] [ -R ] [ -s ] [ -S ] [ -t ] [ -T Filename ] [-u user1,...][ -w ] [ -X ] [ -Y ][ -o OutputDevice ] [ -d Dir ] [ -v Component ] [ -O FileSplitSize ] [ -P Files ] [ script1 script2 ... | All | file:filepath ]

snap -e [ -m Nodelist ] [ -d Dir ]

snap -z ADD ["product_name=prod_name" "class=myclass" "command_path=/tmp/myprod_myscript -a"]

snap -z DELETE ["product_name=prod_name" ]

Description

The snap command gathers system configuration information and compresses the information into a pax file. The file may then be written to a device such as tape or DVD, or transmitted to a remote system. The information gathered with the snap command might be required to identify and resolve system problems.
Note: Root user authority is required to execute the snap command. Use the snap -o /dev/cd0 command to copy the compressed image to DVD. Use the snap -o /dev/rmt0 command to copy the image to tape.

Use the snap -o /dev/rfd0 command to copy the compressed image to diskette. Use the snap -o /dev/rmt0 command to copy the image to tape.

At least 8 MB of temporary disk space is required to collect all system information, including contents of the error log. If you do not gather all system information with the snap -a command, less disk space may be required (depending on the options selected).
Note: If you intend to use a tape to send a snap image to IBM® for software support, the tape must be one of the following formats:
  • 8 mm, 2.3 GB capacity
  • 8 mm, 5.0 GB capacity
  • 4 mm, 4.0 GB capacity

Using other formats prevents or delays IBM software support from being able to examine the contents.

The snap -g command gathers general system information, including the following:

  • Error report
  • Copy of the customized Object Data Manager (ODM) database
  • Trace file
  • User environment
  • Amount of physical memory and paging space
  • Device and attribute information
  • Security user information
  • Configuration and tuning parameter information of the system

The output of the snap -g command is written to the /tmp/ibmsupt/general/general.snap file.

The snap command checks for available space in the /tmp/ibmsupt directory, the default directory for snap command output. You can write the output to another directory by using the -d flag. If there is not enough space to hold the snap command output, you must expand the file system.

Each execution of the snap command appends information to previously created files. Use the -r flag to remove previously gathered and saved information.

Flags

Item Description
-@ Gathers the workload partition information.
-a Gathers all system configuration information except HACMP specific data. To gather HACMP specific data, run the snap -e option.

Collection of registered debug data scripts for external products gets executed and their data is also included as part of system configuration and it can be limited for selected products by specifying their names with the –z flag.

The -a option requires at least 8 MB of temporary disk space.

-A Gathers asynchronous (TTY) information.
-b Gathers SSA information.
-B Bypasses collection of SSA adapter dumps. The -B flag only works when the -b flag is also specified; otherwise, the -B flag is ignored.
-c Creates a compressed pax image (snap.pax.Z file) of snap known component subdirectories in the /tmp/ibmsupt directory tree or any other user-defined directory that is specified with the -d flag.
Note: Information that is not gathered with this option must be copied to the snap directory tree before using the -c flag. If a test case is needed to demonstrate the system problem, copy the test case to the /tmp/ibmsupt/testcase directory before compressing the pax file. Any directories that are defined by the user must be saved in the /tmp/ibmsupt/other directory for the snap command to compress them.
-C Retrieves all the files in the fwdump_dir directory. The files are placed in the "general" subdirectory. The -C snap option behaves the same as -P*.
-D Gathers dump and /unix information. The primary dump device is used.
Note:
  1. If bosboot -k was used to specify the running kernel to be other than /unix, the incorrect kernel is gathered. Make sure that /unix is, or is linked to, the kernel in use when the dump was taken.
  2. If the dump file is copied to the host machine, the snap command does not collect the dump image in the /tmp/ibmsupt/dump directory. Instead, it creates a link in the dump directory to the actual dump image.
-d AbsolutePath Identifies the optional snap command output directory (/tmp/ibmsupt is the default). You must specify the absolute path.
-e Gathers HACMP specific information.
Note: HACMP specific data is collected from all nodes belonging to the cluster. This flag cannot be used with any other flags except -m and -d.
-f Gathers file system information.
-F Gathers flash adapter information.
-g Gathers the output of the lslpp -hac command, which is required to recreate exact operating system environments. Writes output to the /tmp/ibmsupt/general/lslpp.hac file. Also collects general system information and writes the output to the /tmp/ibmsupt/general/general.snap file.
-G Includes predefined Object Data Manager (ODM) files in general information collected with the -g flag.
-i Gathers installation debug vital product data (VPD) information.
-k Gathers kernel information
-l Gathers programming language information.
-L Gathers LVM information.
-m Nodelist Node name list (separated by commas) to gather HACMP information.
Note: Currently this flag is only valid with the -e flag.
-M Timeout Specifies the maximum time out value in seconds, that the snap frame work waits before it kills one registered external product debug data command. Default time out value is 300 seconds.
-n Gathers Network File System (NFS) information.
-N Suppresses the check for free space required.
-o OutputDevice Copies the compressed image onto the specified device.
-O FileSplitSize Used to enable splitting of the snap output files into smaller files. The size of these files is specified as a parameter to the -O option and must be specified in megabytes. This flag can only be used when the -c flag is specified.
-p Gathers printer information.
-P Files Retrieves the named Files from the fwdump_dir directory. If -P * is specified, all the files in the directory are gathered. The files are placed in the general subdirectory. The -C snap option behaves the same as -P*.
-r Removes snap command output from the /tmp/ibmsupt directory.
-R Gathers SCSI RAID information.
-s Gathers Systems Network Architecture (SNA) information.
-S Includes security files in general information collected with the -g flag.
-t Gathers Transmission control protocol information.
-T Filename Gathers all the log files for a multi-CPU trace. Only the base file, trcfile, is captured with the -g flag.
-u user1,user2... Specifies comma separated user names whose shell and System Management Interface Tool (SMIT) history is to be collected.
-v Component Displays the output of the commands executed by the snap command. Use this flag to view the specified name or group of files.
Note: Press the Ctrl-C key sequence to interrupt the snap command. A prompt will return with the following options: press the Enter key to return to current operation; press the S key to stop the current operation; press the Q key to quit the snap command completely.
-w Gathers WLM information.
-X Gathers X.25 (Packet-based Communication Protocol) information.
-Y Gathers InfiniBand information and saves it in the /tmp/ibmsupt/IB directory.
-z Facilitates debug data collection for external products.
  • The ADD keyword allows external products to register their debug data collection script with the snap framework.
  • The DELETE keyword allows external products to deregister their debug data collection script with the snap framework.

When a product name is specified as parameter to the product_name attribute, a registered debug data collection command is executed. To collect data for more than one product specify the required product names in the product_name attribute.

When a class name is specified as parameter to the class attribute, registered debug command of all the products in that class are executed. To collect data for more than one class specify the required class names in the class attribute.

When ALL is specified as parameter, registered debug data collection command of all the products in all classes is executed.

When any script gets executed, system appends the product name to the list pointed by SNAPDEBUGDATA environment variable.

Parameters

Arguments

Names of third-party scripts to be executed are specified as parameters to snap. A parameter can be a single word or a list of words enclosed in quotes. When parameters are enclosed in quotes, the first parameter in the list represents the name of the script and the subsequent words represent the arguments to pass to the script.

When All is specified as a parameter, all the scripts in the script repository are executed. No script parameters may be passed in this case.

If the file: keyword is used and is immediately followed by a path to a file, that file is read to get the scripts to execute. Each line in the file represents a script and optional parameters to the script .

snap Scripts

A third-party script must be executable in /usr/lib/ras/snapscripts, and must follow the guidelines described below. When called during pass 1, a script must return its size estimation to snap. In pass 2, it collects the data and saves it as specified by snap.

The script must read and utilize the following environment variables, SNAPDIR, PASSNO, SCRIPTSIZE and SCRIPTLOG.

The scripts or commands can also use SNAPDEBUGDATA variable to learn about the debug data collected by snap script. This variable has comma separated name of the products for which the snap command collects the data during execution.

All output files must be written to $SNAPDIR. This is the directory where the script should be saving its output. The PASSNO variable contains the snap phase during which the script is called. During the first pass, the script should calculate a size estimation for the data it will write during the second pass. It will then write that numeric estimation to the file pointed to by $SCRIPTSIZE. The value saved to the file should be in decimal. snap passes the path to a log file where all debug data for the script should be saved. Standard out and standard error should not be redirected by the script, because snap will save standard out and standard error to $SNAPDIR/ScriptName.out and $SNAPDIR/ScriptName.err, respectively.

The following example shows a snap script:
#!/usr/bin/ksh


if [ "$PASSNO" = 1 ]
then
         (( size=99999 ))
        .... 
        # this is where code to do the size estimation should go.
        ....
        echo $size > $SCRIPTSIZE

else if [ "$PASSNO" = 2 ]
then
        # debug information should go to $SCRIPTLOG
        echo "Debug Data" >> $SCRIPTLOG

        # .....where the work to collect the data takes place
        # ...

        # The data collected should be written to $SNAPDIR        .
        touch $SNAPDIR/foo_output1
        touch $SNAPDIR/foo_output2
fi
fi
Note: To collect information about virtual SCSI devices, run the snap client_collect,all command. If you need to collect data from the Virtual I/O server, see the snap command page on the Virtual I/O server, which uses different syntax from the snap command on AIX®.
The following scripts can be run when you run the snap command with the -a or -g flags:
  • To run with the -a flag: svCollect, client_collect, lsvirt
  • To run with the -g flag: svCollect, client_collect

Splitting of snap Output

If it is split, snap output might look like the following:

% ls -l
total 112048
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xaa
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xab
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xac
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xad
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xae
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xaf
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xag
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xah
-rw-r--r--   1 lmic     adm         6291456 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xai
-rw-r--r--   1 lmic     adm          744518 Nov 26 09:56 snap.hastings.112603095649.pax.Z.xaj

Executing Third Party Scripts

An external product debug data collection command or script is a standalone executable. The script is registered with the snap framework before it can be used to collect user defined debug data. These scripts can be de-registered as per user discretion.

Following is the ODM class defined in the system.

#define DEFAULTSIZE 256
#define DATA_VALUESIZE 1024

class snap_config {
        char product_name[DEFAULTSIZE]; key
        char class[DEFAULTSIZE];key
        char command_path[DATA_VALUESIZE];
        vchar sc_reserved1[DATA_VALUESIZE];
        vchar sc_reserved2[DATA_VALUESIZE];
}
product_name
Specify the name of the product. The same name is used for deregistration of the product debug data collection script.
class
Class can be a storage, a network or a database. You can choose appropriate class based on the product or define your own class. Class helps in the classification of the products. Users can contact IBM service personnel to add any other class in the snap documentation.
command_path
Path of the command or executable along with its options. sc_reserved1 and sc_reserved2 are reserved.

Registration of Third Party Debug Script with Snap framework

Registration can be done in two ways:
  1. You can explicitly run odmadd command to add the entry. In such case:
    • You must copy the script or executable to /usr/lib/ras/snapscript/bin/<productname> directory.
    Points to remember:
    1. You need to enter the command before executing the odmadd:
      export ODMDIR=/usr/lib/objrepos
    2. After the odmadd command completes, you can restore the old value of the ODMDIR command.
    3. You can continue running the snap command. For example, the content of myfile is given below:
      product_name=myprod
      class=myclass
      command_path=/usr/lib/ras/snapscripts/bin/prod_name/myscript1.sh -t 10
      export ODMDIR=/usr/lib/objrepos
      odmadd myfile
    Note: Users making direct entry to ODM must take care of duplicate entries as the snap command processes only one entry for a particular product name. So, the odmdelete command must be executed before the odmadd command is invoked.
  2. Use the ADD keyword with the –z flag.
Note:
  • 1. If the debug binary is changed or updated, the user must re-register the component to update the snap repository with the latest binary.
  • 2. Combination of multiple commands as a part of command_path variable is not supported. For example, the following format is not supported:
    command_path=<path>/ls|<path>/grep myfile 
  • 3. Special characters like, ', <, | are not supported as values to the command_path variable.

Deregistration of Third party debug scripts from Snap framework

Deregistration can be done in two ways:
  1. Use the odmdelete command to deregister the product. For example,
    export ODMDIR=/usr/lib/objrepos
    odmdelete -o snap_config -q product_name=productname
  2. Use the DELETE keyword with the –z flag. For example,
    Snap –z DELETE product_name=productname

Examples

  1. Enter the following command to gather all system configuration information:
    snap -a
    The output of this command is written to the /tmp/ibmsupt directory.
  2. Enter the following command to create a pax image of all files contained in the /tmp/ibmsupt directory:
    snap -c
  3. Enter the following command to gather general system configuration information, including the output of the lslpp -hac command:
    snap -g -o /dev/rfd0
    Output is written to the /tmp/ibmsupt/general/lslpp.hac and /tmp/ibmsupt/general/general.snap files. This command also writes the system information to a removable diskette.
  4. Enter the following command to gather HACMP specific information from nodes node1 and node2 belonging to a single cluster:
    snap -e -m node1,node2
    Output is written to the /tmp/ibmsupt/hacmp directory.
  5. To run the scripts foo1, foo2 and foo3. where foo1 takes no argument, foo2 takes three arguments and foo3 takes one argument, type the following:
    snap  foo1 "foo2 -x -y 3" "foo3 6"
    Output is written to /tmp/ibmsupt/snapscripts/foo1, /tmp/ibmsupt/snapscripts/foo2 and /tmp/ibmsupt/snapscripts/foo3 assuming the destination directory is the default, /tmp/ibmsupt.
  6. To specify the All parameter to run all the scripts, type:
    snap All
    Note: No parameters are passed in this case.
  7. To specify the path to a file containing the name and optional parameter list of scripts to execute, type:
    snap file:/tmp/scriptnames
    A sample input file to execute the scripts from example 5:
    foo1 
    foo2 -x -y 3
    foo6
  8. If splitting of the snap output into 4MB files is desired, type:
    snap -a -c -O 4
  9. To submit only the HACMP snap -e data from nodes node1 and node2, enter the following command:
    snap -e -m node1,node2
    snap -c

    Submit the <pax.z> file to IBM according to the instructions of the service representative.

  10. To submit all of the snap data from nodes node1 and node2, enter the following commands:
    snap -e -m node1,node2
    snap -a
    snap -c 

    Submit the <pax.z> file to IBM according to the instructions of the service representative.

  11. To register a debug script present in the /usr/lpp/abc/debug_abc directory of product abc, in class storage enter the following command:
    snap –z ADD "product_name=abc" "class=storage" "command_path=/usr/lpp/abc/debug_abc –a"
  12. To deregister a debug script of product abc, enter the following command:
    snap –z DELETE "product_name=abc"
  13. To gather debug data of multiple products, enter the following command:
    snap –z "product_name=abc, product_name=def"

Files

Item Description
/usr/sbin/snap Contains the snap command.
/tmp/ibmsupt Contains snap command output.
/tmp/ibmsupt/general/lslpp.hac Contains the output of the lslpp -hac command, which is required to recreate exact operating system environments.
/tmp/ibmsupt/general/general.snap Contains general system information that is collected with the snap -g command.
/tmp/ibmsupt/testcase Contains the test case that demonstrates your system problem.
/tmp/ibmsupt/other Contains user-defined directory.