Introduction
------------
This is binstats 1.08 - an administration utility for tracking down the
various types of binary formats for Linux executables and their dynamic
library dependencies and also executable scripts and man pages.

Features include:
 1) tally of a.out (Linux/i386), ELF and ECOFF (new!) binaries, dynamically
    and statically linked, unstripped and setuid
 2) tally of Java bytecode binaries (if you run file-3.20+)
 3) tally of text files distinguishing between Bourne, bash and [T]C shells,
    awk, perl, python & tcl scripts, other interpreted scripts & unidentified
    texts
 4) tally of duplicated executable names
 5) tally of binaries with missing dynamic libraries
 6) tally of DLL and ELF dynamic libraries, used and unused
 7) tally of man pages and duplicated manual names (new!)
 8) a log of all the above tallies plus listing a.out binaries, statically
    linked binaries, unstripped binaries, setuid binaries, duplicated
    executables, missing library binaries, all unidentified text files,
    all used and unused dynamic libraries, duplicated manuals
 9) a C program that dereferences symbolic links
10) a command line interface

It was inspired by "execount" written by Murple (murple@clark.net)
<ftp://metalab.unc.edu/pub/Linux/utils/scripts/>. Originally, when binstats
was created in 1996 it was useful during the a.out to ELF transition for
pruning a system of a.out executables.

Now in 2001, times have changed with fancy package management systems being
common on Linux distributions. This makes binstats much less needed. But the
hurdle of creating binary packages suffices that people still compile stuff
from tar balls of source code - I know I do. Of course, with the ravages of
time, after many compilations and installations your system gets into a
rather untidy state: forgotten binaries that once used libc5 populated
/usr/local/bin; multiple versions of dynamically linked libraries lie
forlorn; various man pages are scattered across your file hierarchy. All
because you were enjoying the vicarious pleasure of trying the latest and
greatest version of rapidly changing open sources. Thus binstats is a last
resort to restore order to the chaos that this ad-hoc approach to software
installation brings.

Go on, try it. You know you want to: it's the latest version...


Technical details
-----------------
Binstats has been written as a bash script utilising the following common
unix tools: echo, tr, cat, xargs, cut, dirname, sed, find, sort, uniq, grep,
file, ldd, awk, col, diff, wc, uname, date. [As usual, a Linux distribution
is indebted to the GNU project for most of these tools.]

This latest version has been tested on Redhat 6.2 which contains GNU
bash 1.14.7, GNU sh-utils 2.0, GNU findutils 4.1, GNU textutils 2.0e, GNU
grep 2.4, file 3.28, ld.so 1.9.5, Gnu libc 2.1.3, Gnu Awk (gawk) 3.0.4,
util-linux 2.10f and GNU diffutils 2.7.

Also binstats (1.0.7) had been tested on Redhat 5.1 which contains GNU bash
1.14.7, GNU sh-utils 1.16, GNU findutils 4.1, GNU textutils 1.22, GNU grep
2.0, file 3.24, ld.so 1.9.5, Gnu libc 2.0.7, Gnu Awk (gawk) 3.0.3,
util-linux 2.7 and GNU diffutils 2.7.

Finally versions up to 1.05 have been tested on Redhat 4.2 which contains
GNU bash 1.14.7, GNU sh-utils 1.16, GNU findutils 4.1, GNU textutils 1.22,
GNU grep 2.0, file 3.22, ld.so 1.7.14, Gnu Awk (gawk) 3.0.2 and GNU
diffutils 2.7.


Historical bugs
---------------
Of the numerous commands used by binstats, some old versions of two
utilities have slight problems.

file: For ELF 'not stripped' support, pick up "file 3.15-grr1" plus the
patch from Mitch D'Souza <http://users.ox.ac.uk/~jo95004/patches/file.diff>.
Compile and install accordingly to instructions.

There is a bug in the magic of file-3.15: in Magdir/commands, the six lines
from 40-45 inclusive should be moved to the end.

file-3.20 has ELF 'not stripped' support and Java bytecode support.

ldd: ldd has at least one bug (in ld.so 1.7.14) and one inconsistency (or
feature) which binstats has to be cope with. The latter problem is still
present in the version that comes with Red Hat 5.1 - when only a single name
is passed to ldd, it does not print the name of the file. The solutions to
these problems are controlled by switches in the script.


Running
-------
Edit the Makefile to suit your setup. Compile derefsymlink, install the
executables and man pages. Read the notes in the script before using
binstats.

Now you have three options:
   1) leave binstats as is and it will use your PATH and ld.so.conf
   2) edit the variables to fit your system
or 3) use the command line interface

      ./binstats [-b[inaries]="list of executable directories"] [-d[ebug]]
              [-f[ile]=bstats.log] [-h[elp]]
              [-l[ibraries]="list of library directories"]
              [-m[anuals]="list of manual directories"]
	      [-p[ath]="usual path for binstats"]
	      [-t[emp]=/tmp] [-v[ersion]]

      For example, if you have a minimal system then try
        ./binstats -b="/bin /sbin /usr/bin /usr/sbin"
      if you only have the four specified directories.

If you don't run it as root then any executable without world readable
status (especially setuid binaries) will register in the tallies or log as
"can't read setuid".


Acknowledgements
----------------
Thanks goes to the people who have provided feedback. Special thanks goes to
Matej Vela <vela@debian.org> who contributed the man pages.


Bugs, etc
---------
Please send any bug reports, patches, etc to me. The latest version can be
found at <http://www.nottingham.ac.uk/~etzpc/binstats.html>. The
distribution is also archived at
<ftp://metalab.unc.edu/pub/Linux/utils/scripts/>.


To do
-----
Maybe it's better use Perl or Python [when I read up on it] for all this.

Peter Chang <Peter.Chang@nottingham.ac.uk>

18th January 2001

PS binstats is released under the GPL and as such the usual licence
conditions and lack of warranty apply.

