sowhat -- report every file that references a given library.
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.
Sowhat is a tool that scans an entire system or network for dependencies between
files and other things they reference, including dynamic libraries, script
interpreters, etc. It can then respond to queries about which file
references which which other files. Sowhat can be used to analyze the impact of a system change prior to making it, or
to report the possible impact of a change already made. E.g., after a
system change that breaks some crucial software, one can ask sowhat to list the changes that could have possibly brought about the breakage.
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.
All of these but the last are performed on all files. The last refers only to the inetd configuration file, normally
/etc/inetd.conf
or /etc/inet/inetd.conf
.
To clear all stored data,
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.
Sowhat operates in several modes based upon the options one gives it on the
command line. Sowhat performs several major actions, including --init
, --diff
, --report
, and --aliases
. Actions include:
- --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:
-
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
-
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.
Sowhat requires the following prerequisites for operation:
- 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.
sowhat is a self-contained Perl-5 script. Installing it is mainly a matter of
satisfying its prerequisites.
-
Install MySql from www.mysql.org, following instructions contained with the
distribution.
-
Create a database for use with sowhat, which can have any name; we suggest the name ``sowhat'':
mysql> create database sowhatdb;
-
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.
-
Install Perl-5, including the modules DBI, DBD::Mysql, Getopt::Long, and Data::Dumper.
-
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.
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.
Nov 10, 2001