• NAME
• SYNOPSIS
• DESCRIPTION
• QUICKSTART
• OPTIONS
• PREREQUISITES
• INSTALLATION
• AUTHORS
• LAST MODIFIED

NAME

SYNOPSIS

        sowhat {command} {options}
          commands:  
          --init            clear data for this host from database. 
          --scan            scan database; options: 
            --path              scan current execution path. 
            --path={paths}      scan a list of directories as an execution path
            --node={paths}      scan individual filesystem nodes. 
            --tree={paths}      recursively scan directory for binaries
            --env={scripts}     invoke package and scan resulting bins.
            --envAll            study all packages in /local/env. 
            --inetd             study contents of inetd.conf. 
          --diff            scan for differences from recorded data; options: 
            --path              scan current execution path. 
            --path={paths}      scan a list of directories as an execution path
            --node={paths}      scan individual filesystem nodes. 
            --tree={paths}      recursively scan directory for binaries.
            --env={scripts}     invoke package and scan resulting bins.
            --envAll            study all packages in /local/env.
            --inetd             study contents of inetd.conf. 
          --report          generate a summary report of recorded data.
            --from={paths}      include only referencing files in path list. 
            --to={paths}        include only referenced files in path list. 
            --not-from={paths}  exclude referencing files in path list. 
            --not-to={paths}    exclude referenced files to path list. 
          --aliases={paths} report all aliases for paths, symbolic or hard. 
          --ls              list names of all available tables. 
          --initAll         clear all data from tables, for all hosts.
          --version         report version
          Options for all commands: 
            --debug             turn on debugging messages. 
            --quiet             turn off informative messages. 
            --verbose           add informative status messages. 
            --ldd={path}        specify a different path for 'ldd' command.
            --file={path}       specify a different path for 'file' command.
            --host={hostname}   change hostname from the default. 
            --table={tablename} specify a different database table.

DESCRIPTION

Sowhat currently scans for and stores data on the following kinds of embedded dependencies:

dynamic libraries

Sowhat runs ldd on all dynamically linked programs and dynamic libraries, and records library bindings.

symbolic and hard links

Hard links are disambiguated by querying the results of scanning whole filesystems. The accuracy of the bindings depends upon the completeness of sowhat's scans.

scripts

Executable files beginning with '#!' are recorded as referencing the script name that follows.

inetd.conf

Sowhat scans the inetd configuration file and records both bindings to specific programs and the data for those programs.

QUICKSTART

        sowhat --initAll

To clear the database of all data for the host on which you're running sowhat,

        sowhat --init

To scan a database and record data for your current user path,

        sowhat --scan --path

To report changes since the last scan,

        sowhat --diff --path

To determine which programs use a library or library path, e.g., /usr/lib/libc.so.1,

        sowhat --report --to=/usr/lib/libc.so.1

where /usr/lib/libc.so.1 is the path of the library to be studied.

To see all information gathered by sowhat,

        sowhat --report | less 

where less is the name of your pagination program.

OPTIONS

--init

Re-initialize database for this host by deleting all stored information.

--initAll

Delete everything and start over.

--scan

Scan parts of the system for dynamic library dependencies and recording each one. There are several optional arguments to --scan, including:

--scan --path

Scan the current user's current path for all executable binary programs, and record the dependencies between each and its dynamic libraries.

--scan --path={paths}

Scan each directory given, one by one, checking every file in the directory but not recursing into subdirectories.

--scan --node={paths}

Scan the given filesystem nodes, one by one. Separate full pathnames with ':'s.

--scan --tree={paths}

Recursively scan the directories {paths} for files that reference others and record each one's dependencies on the others. Separate paths with ':'. Example:

        --scan --tree=/usr/local:/var/local

will recursively scan both /usr/local and /var/local for referring files and record all information found.

--scan --env={scripts}

Source the scripts listed in {scripts} (separated by ':'s) in a subshell and scan their paths. {script} is presumed to be a csh or tcsh script. Sowhat scans new path components added to the current path by the script for file dependencies and records the results.

--scan --envAll

(Tufts EECS option) Do --scan --env={script} for every script with a name matching $main::ENVPATH/*.cshrc and record all results. ($main::ENVPATH is a configuration option).

One may specify any combination of the above to perform more than one kind of scan.

--diff

Report differences between a scan (as in --scan) and the current state of a system. Arguments to this command are the same as for --scan and report on differences within different aspects of the system:

--diff --path

Report differences in library binding in the current user's execution path.

--scan --path={paths}

Report differences in files in the directories given, not recursing into subdirectories.

--diff --tree={dname}

Report differences in library binding for programs and libraries in a particular directory or its subdirectories.

--diff --env={script}

Report differences in library bindings for programs in path components added to the current path by a specific csh script.

--diff --envAll

Report differences in library bindings for path components added to the current path when executing scripts in /local/env/*.cshrc

--diff --inetd

Report differences between references in the current version of inetd.conf and the one in effect during the last scan.

Any mix of the above directives may appear after --diff, though only the last one of each kind will be obeyed.

--report

Report all discovered bindings for the current host. This does not report any bindings recorded for other hosts. One can limit the scope of reports with several options:

--to={paths}

Limit the report to listing files that reference the given paths, separated by ':'s. For example --to=/var/local:/usr

would report only on references to files contained in /var/local and /usr.

--from={paths}

Limit the report to referring files in the given list of directories, separated by ':'s. For example,

        --from=/usr/local/bin:/usr/hosts

would only report references implied by files contained in these two directories.

--not-to={paths}

Do not list references to things in the given set of paths, separated by ':'s.

--not-from={paths}

Do not list referring files in the given set of paths, separated by ':'s.

Useful combinations:

1. To check on all files that use a given file, e.g., /usr/lib/libc.so.1, one could type

           sowhat --report --to=/usr/lib/libc.so.1
   

   To check whether anything in a directory /foo is referred to by any sowhat service,

           sowhat --report --to=/foo
   

2. To see if files in a given directory refer outside it, one could type something like:

           sowhat --report --from=/var --not-to=/var:/usr:/lib
   

   This reports the references in /var that don't refer to /var, /usr, or /lib.

--aliases={paths}

Report all aliases for each given path, either symbolic or hard. Example:

        sowhat --aliases=/etc/motd:/var/mail

would report on whether it knows of any links that point either to or from the two files.

--ls

List all tables in the current database that have the form of reference tables. One can use one of these instead of the default by specifying

        --table=newtable

Several options apply to all commands:

--debug

Print debugging information on STDERR, including scan progress.

--quiet

Supress normal informative printing to STDERR. This is suitable when sowhat is to be executed under control of cron.

--verbose

Print informative messages showing status of scans.

--table={tname}

Use database table {tname} rather than the default of libs.

--ldd={path}

Specify a new path for ldd.

--file={path}

Specify a new path for the file (file type) command.

--version

Report the version of sowhat.

PREREQUISITES

Perl 5

Tested on revision 5.004_04 and higher.

Perl modules:

DBI, DBD::Mysql, Getopt::Long, Data:::Dumper.

MySql

Revision 3.22.27 or higher, from http://www.mysql.org. Other databases may work, as the code is rather portable. To port, modify the Perl module Sowhat::DBRef.

ldd and file commands.

Currently, only Solaris ldd is supported.

INSTALLATION

1. Install MySql from www.mysql.org, following instructions contained with the distribution.

2. Create a database for use with sowhat, which can have any name; we suggest the name ``sowhat'':

           mysql> create database sowhatdb; 
   

3. Grant all privileges to the database on each host on which you wish to run sowhat.

           mysql> grant all privileges on sowhatdb to someuser identified by "somepass"; 
   

   where "someuser" is a user name and "somepass" is some password you create.

   It is important that sowhat have the ability to create tables, as it will then create the tables that it needs without your help.

   It is important to execute mysql in ``internet mode'' (-i option) if you wish to record data from non-local hosts. If you only wish to analyze one host you may run mysql without the -i option.

   As running mysql in internet mode has some unpleasant security ramifications, we suggest dedicating a copy of mysql to sowhat in this case, so that other more important data need not be compromised.

4. Install Perl-5, including the modules DBI, DBD::Mysql, Getopt::Long, and Data::Dumper.

5. Edit the first 9 lines of line of sowhat to point to appropriate commands and select appropriate options. These options include the user (``someuser'') and password (``somepass'') to use when connecting to the database. Parameters include:

   $SOWHATDATA

   This is a distinguished name for the database sowhat will use:

           my $SOWHATDATA = "DBI:mysql:sowhatdb:myhost.mydomain.org"; 
   

   DBI

   The interface to use.

   mysql

   The database management system to use.

   sowhatdb

   The database to use to store sowhat data.

   myhost.mydomain.org

   The name of the database server. Can be localhost.

   $SOWHATUSER

   The name of a valid user with access to the database you listed above.

           my $SOWHATUSER = "sowhatuser";
   

   $SOWHATPASS

   The password for that user for the database you listed above.

           my $SOWHATPASS = "sowhatpass"; 
   

   Please change this to your own secret password, unless you want to entertain hackers on your site...

   $main::LDD

   Where to find the Solaris ldd command.

           $main::LDD  = "ldd";
   

   $main::FILE

   Where to find the Solaris file command.

           $main::FILE = "file";
   

   $main::GETHOST

   Algorithm for determining the name of the host upon which you're executing sowhat.

           $main::GETHOST = "uname -n";
   

   $main::TCSH

   Where to find tcsh.

           $main::TCSH = "/usr/bin/tcsh"; 
   

   $main::TMP

   Algorithm for creating temporary files. $$ is the current process ID.

           $main::TMP = "/tmp/sowhat$$"; 
   

   $main::REFTABLE

   Database table to use for sowhat references, by default.

           $main::REFTABLE = "refs"; 
   

   Once you set this, running sowhat will create the appropriate table libs in the database you specified, if it does not exist already.

AUTHORS

        Yizhan Sun, mailto:ysun@eecs.tufts.edu, 
        Alva L. Couch, mailto:couch@eecs.tufts.edu, 
        Electrical Engineering and Computer Science
        Tufts University
        161 College Avenue
        Medford, MA 02155
        http://www.eecs.tufts.edu/~couch
        Copyright 2001 by Yizhan Sun and Alva L. Couch.

LAST MODIFIED