
THE ROOTKIT HUNTER PROJECT
==========================

Copyright (c) 2003-2007, Michael Boelen
See the LICENSE file for conditions of use and distribution.

It is recommended that all users of RootKit Hunter (RKH) join the
rkhunter-users mailing list. Subscribing to the list can be done via
the RKH website at http://rkhunter.sourceforge.net

A copy of the RKH FAQ is also available from the web site.


ROOTKIT HUNTER REQUIREMENTS
===========================

Please note RKH has some requirements:

1) Before RKH starts it will check that certain required commands
   are present on the system. These are typical commands such as
   'cat', 'sed', 'head', 'tail', etc. If a command is missing then
   RKH will not run.

2) Some tests require commands such as stat, readlink, md5/md5sum or
   sha1/sha1sum. If these are not present, then RKH has perl
   scripts which will automatically be used instead. However, this
   requires perl being present. If it is not, then the tests will
   be skipped. Readlink is provided as a script itself, and does
   not use perl. Other tests will use other commands. If the relevant
   command is not found on the system, then the test will be skipped.

3) A tool should be present with which to download file updates. 
   Currently wget, curl, (e)links, lynx and GET are supported. If your
   system does not allow the possibility to install one of these 
   applications, but does run perl, you can use 'bget' available from 
   http://www.cpan.org/authors/id/E/EL/ELIJAH/. If you use another 
   generic method of updating RKH then please let us know.

4) Some tests require single-purpose tools. RKH does not depend on
   these, but it will use them if it finds them - they can enhance
   RKH's detection capabilities. The tools are:
   - Skdet
       Tests for SucKIT, Adore, Adore-NG, UNFshit, UNFkmem and
       frontkey.
   - Unhide
       Finds hidden processes.
       http://www.security-projects.com/?Unhide
   If the relevant tool is not found, then the test is skipped.


ROOTKIT HUNTER INSTALLATION
===========================

Unpacking the tar file should produce a single directory called
'rkhunter-<version>'. Where '<version>' is the version number of rkhunter
being installed. For example, the rkhunter-1.3.0.tar.gz tar file will produce
the 'rkhunter-1.3.0' directory when unpacked. Within this directory is the
installation script called 'installer.sh'.

To perform a default installation of RKH simply unpack the tarball and,
as root, run the installation script:

    tar zxf rkhunter-<version>.tar.gz
    cd rkhunter-<version>
    ./installer.sh --layout default --install

RKH installation supports custom layouts. To show some examples
run:

    ./installer.sh --examples

As an another example, to install all files beneath /opt, run:

    ./installer.sh --layout custom /opt --install

To show where files are installed using the 'oldschool' layout
run:

    ./installer.sh --layout oldschool --show

The layout named 'RPM' may not be chosen since it is used solely
for installing RKH using RPM.


The default installation process will install a configuration file,
called 'rkhunter.conf', into the '/etc' directory or where
you chose using the --layout switch. Please edit the configuration 
file according to your own system requirements. If the installer 
encounters an existing rkhunter.conf, it will not be overwritten.
Instead the installer creates a new configuration file, but with
a unique number as its suffix. Please inspect the new configuration
file and copy over any changes to the existing configuration file.

The main RKH script will be installed into the '/usr/local/bin'
directory or where you chose using the --layout switch. Man pages will 
be installed into '/usr/local/share/man', and other documentation will 
be installed into the '/usr/local/share/doc' directory. RKH data files,
language support, and a directory for temporary files will be
installed into '/var/lib/rkhunter'. Finally, RKH support scripts will
be installed into '/usr/local/lib/rkhunter/scripts', or, if using an
x86_64 system, into '/usr/local/lib64/rkhunter/scripts'. All directories,
except 'lib64', will be created where necessary.

Before running RKH you will need to fill the file properties database by
running the following command:

    rkhunter --propupd

Note that if you want to use the package management tools provided by 
your distribution you will need to select a package manager. In the case
of using RPM your command would be:

    rkhunter --propupd --pkgmgr RPM


To run RKH, as root, simply enter the following command:

    rkhunter --check


By default, the log file '/var/log/rkhunter.log' will be created. It
will contain the results of the checks made by RKH.

To see what other options can be used with rkhunter, enter:

    rkhunter --help


NOTE: The first run of 'rkhunter' after installation may give some
      warning messages. Please see the FAQ file for more details
      about this.


STANDALONE INSTALLATION
=======================

It is possible to run RKH standalone, that is, with it all being
installed into one directory.

To do this unpack RKH as described above, and then install it using
the following command:

    ./installer.sh --layout custom . --install

It is then necessary to change to the 'files' directory:

    cd files

Within the directory will be a copy of the 'rkhunter.conf' configuration
file. You can modify this file according to your requirements if you
wish, but note the installer has already set the necessary variables.

To run RKH, as root simply enter the following command:

    ./rkhunter --check


INSTALLATION INFORMATION FOR x86_64 SYSTEMS
===========================================

The installation of RKH is largely independent of the system architecture.
However, RKH does have some support scripts and these need to be installed
into the appropriate library directory. When using the 'default' layout
option, or one of the known layout options (for example, '/usr' or
'/usr/local'), then the relevant 'lib64' directory will be used only if it
already exists. For a 'custom' layout, the 'lib64' directory will be used
and created if necessary. Standalone installations do not use any special
library directory at all. RPM installations will use the relevant 'lib64'
directory only if the system architecture is detected as being 'x86_64'.


REMOVING AN INSTALLATION
========================

RKH supports uninstallation. To do this unpack the installation
tarball, and then run the installer with the --remove option. If RKH
was installed using a default installation, then run:

    tar zxf rkhunter-<version>.tar.gz
    cd rkhunter-<version>
    ./installer.sh --layout default --remove

If you chose a different layout, for example '/usr', then run the
installer using:

    ./installer.sh --layout /usr --remove

Note: the installer will not remove files that were installed using RPM
(use the 'rpm' command to remove the package).

For a standalone uninstallation, specified by using '--layout custom .',
the installer will remove the whole installation directory (the 'files'
sub-directory).

During uninstallation, the installer will remove the initial configuration
file. However, if RKH was installed more than once, then any additional
configuration files are not removed. These may be removed manually.

When installing RKH, some directories may have been created. However,
RKH is unaware of this when being uninstalled. As such, and especially
when having used a custom installation, some directories may be
emptied of files, but the directories themselves may remain. Again,
these can be removed manually if wished.

In order to see where RKH installed its files during installation, the
'--show' option can be used. For example:

    ./installer.sh --layout custom /opt --show


USING TEST NAMES
================

Within RKH some of the tests have been given names. There are two types of
test names - specific test names and grouped test names. A specific test name
generally refers to one specific test within RKH. A grouped test name refers
to a set, or group, of related tests. Within a group name there are usually
one or more specific test names.

To see the current list of test names use the 'rkhunter --list tests' command.
The grouped names list will show the specific names that are within the group.

So, for example, the file properties check has the grouped name of 'properties'.
However, within that test the file hash value test is known as 'hashes'.
Similarly, the file attributes check, which checks the file permissions, uid
and gid values, and so on, is known as the 'attributes' test. Note that while
it is possible to tell RKH to run the file properties check, but ignore the
file hash value test, it is not possible to tell RKH to run the file attributes
but to ignore the file permissions checks. RKH has no specific name for the
file permissions test, and so it cannot be specifically enabled or disabled.

RKH can be told to enable or disable one or more of the tests by using the
'--enable' and '--disable' command-line options. Alternatively, the RKH
configuration file options 'ENABLE_TESTS' and 'DISABLE_TESTS' can be used.
Note, however, that if either command-line option is used then the
configuration file options, for both enabled and disabled tests, are ignored.
The program defaults if no options are used at all are to enable all tests and
to disable no tests. For this purpose the enable options can use the special
test name 'all', and the disable options can use the name 'none'. To specify
more than one test name, specify them as a comma-separated list. For example:

    rkhunter --enable 'rootkits,hashes'

Note that in the above example no disabled test list was specified. As such, it
will default to the program default value - '--disable none'. If multiple use
of the options are given on the command-line, then the last values seen will
be used.

The supplied RKH configuration file will have some tests already disabled.
These are generally CPU and/or I/O intensive tests, or ones which may be prone
to giving false-positive results. They can, of course, be enabled by editing
the DISABLE_TESTS list. To run the tests from the command line, either user
the '--enable' command-line option with the specified test name, or use
either '--enable all' or '--disable none'.

If either of the '--enable' or '--disable' command-line options is used, and
the '--propupd' option is not given, then '--check' is assumed.

If the '--enable' option is used and only one test name, other than 'all',
is given, then the '--skip-keypress' option is assumed as well. So, for
example, to run all the rootkit tests just use:

    rkhunter --enable rootkits

Similarly, to run all the tests except the rootkit tests, then use:

    rkhunter --disable rootkits

In this example RKH will assume the enabled test list of '--enable all'. In the
previous example, '--disable none' will have been assumed.

If a combination of enabled and disabled tests are specified, then RKH will
disable a test if it is specified in the enable list. So, for example:

    rkhunter --enable 'rootkits,deleted_files' --disable malware

In this example the 'malware' test is disabled because it is part of the
'rootkits' test. The fact that the 'deleted_files' test is specified to be
run is ignored, because that is part of the 'malware' test. RKH will always
look to see what tests to disable first. It will then run any enabled tests
that are left.

By default RKH will log what tests names have been enabled and disabled.
Additionally it will log each test name that it is about to execute. When
initially run RKH may skip some tests due to missing commands or files. It is
usually possible to omit these tests by including them in the DISABLE_TESTS
list in the configuration file. The test name associated with these tests can
be found by looking in the log file.

It should be noted that not all the tests have been given names. As such some
test names may execute more tests than expected. For example:

    rkhunter --enable group_changes

The 'group_changes' test name refers to the check to see if the /etc/group file
has been modified. However, running the above command will also cause several
tests on the /etc/passwd file to be executed. This is because those tests are
part of the 'local_host' grouped test name, as is the 'group_changes' test,
but those other tests have no specific names. As such, RKH will start the
'local_host' tests, executing some of the /etc/passwd file tests and then the
'group_changes' test, but ignoring any other tests within 'local_host' which
do have specific names (for example, 'filesystem' and 'passwd_changes').


USING PACKAGE MANAGERS
======================

The RKH file properties check, by default, performs a check of various current
file properties against those that it has previously stored in the
'rkhunter.dat' file. This way RKH can warn the user if a file has changed. The
file properties include items such as the files hash value, file permissions,
uid, gid, inode number and so on. The properties are obtained and stored in the
rkhunter.dat file when RKH is run with the '--propupd' option.

Typically the file properties are obtained using commands such as 'stat',
'file', 'md5sum' and 'prelink'. However, it is also possible to specify that
RKH should get whatever values it can by using a package manager. This can be
done by using the '--pkgmgr' command-line option, or the 'PKGMGR' configuration
file option. When the RPM package manager is specified, during the file
properties check the results from the RPM verification command are used as the
test results. For the other package managers, the values from the package
manager database are compared against the current values for the files. By
using a package manager, it is possible to avoid some false-positive reports
that a file has changed when in fact it has been automatically updated by the
system.

The currently available package managers are 'RPM' for RedHat/RPM-based
systems, 'DPKG' for Debian-based systems, and 'BSD' for *BSD systems. It is
also possible to specify 'NONE' to indicate not to use a package manager.
The program default is 'NONE'.

Any file which is not part of a package is treated as before, that is, the
HASH_FUNC configuration file option, or the '--hash' command-line option, will
be used.

It should be noted that all the package managers provide an MD5 hash value for
a file. However, the 'RPM' package manager can provide other file property
values as well, such as the file permissions, uid, gid, modification time and
so on. During the file properties check all of these values will be used,
rather than the ones stored in the rkhunter.dat file.

It should also be noted that the 'DPKG' and 'BSD' package manager options
only provide the files MD5 hash value. As such, during the file properties
check, all the other current file properties will be re-calculated as before,
and compared against the values in the rkhunter.dat file. Hence, only the 'RPM'
package manager offers any real benefit in using a package manager.

NOTE: It is possible for a package manager database to become maliciously
corrupted. To that extent the use of the package manager options with RKH
does not provide any increase in security. However, it may result in less
false-positive warnings of files which have changed. As always RKH can only
report on changes, but not on what has caused the change.


USING LOCAL MIRRORS
===================

When the '--update' or '--versioncheck' options are used, rkhunter uses
a mirror site from the mirrors.dat file to obtain the required information.
By default rkhunter will use any mirror listed in the file, and it will
then rotate the list of mirrors. At the time of writing the supplied
mirrors.dat file lists the Rootkit Hunter SourceForge site as a mirror.

However, it is possible for users to define a local mirror if they wish to.
This is done by simply editing the mirrors.dat file and inserting the
mirror URL. The line should begin with the text 'local='. For example:

    local=http://www.example.com/rkhunter_data

The required rkhunter files must be placed in a location, of the users choice,
which is accessible by the clients. So in the above example, the rkhunter
data files would have been placed in the 'rkhunter_data' directory. The
required files consist of the '.dat' files supplied with rkhunter, and which
will have been installed in the database directory. For a default
installation this would have been in '/var/lib/rkhunter/db'.

Additionally, the mirror directory must have an 'i18n' sub-directory which
contains all the current language translation files for the various versions
of rkhunter. Each version is put into its own sub-directory. So, for example,
there would be a '1.3.1' sub-directory, a '1.3.2' sub-directory and so on,
all within the 'i18n' directory. Again, the database directory will already
have had the 'i18n' sub-directory installed in to it, but it will only
contain the language files for the current version of rkhunter. There are
no version sub-directories installed by default. As such, the mirror will
need to have the various version sub-directories created, and the relevant
language files put in to them, for the versions of rkhunter that the mirror
is required to support. If a client tries to access the language files for a
version of rkhunter that is not supported by the mirror, then the download
will fail. Depending on how the client is configured, another, possibly
remote, mirror may be tried, or rkhunter will give a warning.

Within each rkhunter version sub-directory of the 'i18n' directory, it is
necessary to have a file called 'i18n.ver'. This file simply contains a list
of the available language files, and their version numbers. For example:

      cn:2007061401
      en:2007102501

So, as an example, the mirror file structure will need to look similar
to this:

                      rkhunter_data
                            ||
                            ||
     ===============================================
     ||               ||              ||          ||
 mirrors.dat  rkhunter_latest.dat    i18n    suspscan.dat
                                      ||
                                      ||
                  1.3.1 ============ 1.3.2 ============ 1.3.3
                  / | \              / | \              / | \
                 /  |  \            /  |  \            /  |  \
               cn  en  i18n.ver   cn  en  i18n.ver   cn  en  i18n.ver


Finally, if the '--versioncheck' option is to be supported with the local
mirror, then the directory, 'rkhunter_data' in the above example, must
contain a file called 'rkhunter_latest.dat'. This file must contain the
current rkhunter version number (for example, '1.3.0') and no other text.

It is possible to similarly define 'remote' mirrors, which begin with the
text 'remote='. At present though there is no real difference between a
local or remote mirror.

The supplied mirror site(s) in the mirrors.dat file begin with the text
'mirror=', and this should not be changed.

In order to select whether all the mirrors or only the local or remote
mirrors should be used, the rkhunter configuration file has an option in
it called 'MIRRORS_MODE'. This option takes a numeric value, which by default
is zero. The current values and meanings are:

    0 - use any mirror (the default)
    1 - use only local mirrors
    2 - use only remote mirrors

To further support local and remote mirrors there are two other configuration
options available:

The first is 'UPDATE_MIRRORS', which simply tells rkhunter whether the
mirrors.dat file itself should be updated (i.e. overwritten) when the
'--update' option is used. If local mirrors are listed in the file then you
probably do not want the file automatically updated. The 'UPDATE_MIRRORS'
option has a default value of one, indicating that the mirrors.dat file should
be updated. Set this option to zero to disable this feature.

The second option is 'ROTATE_MIRRORS'. This tells rkhunter whether it should
rotate the list of mirrors whenever the '--update' or '--versioncheck' options
are used. Again, with local mirrors you may want these accessed in a specific
order, rather than rotated each time. The option has a default value of one
indicating that the mirrors should be rotated. Set this option to zero to
disable this feature.

By default if a mirror fails for some reason, then rkhunter will use the next
mirror, of the configured type, listed in the file. If there are no more
mirrors left, then rkhunter will give a warning message.


ROOTKIT HUNTER SUPPORT
======================

If a problem is found with RKH, it is recommended that users initially
try and resolve the problem themselves. This can be done by first
checking the FAQ file, which is present in your installation if the
distributed tarball is used as source. The FAQ will contain answers 
to many common problems. The latest version of the FAQ can always be 
found at RKH's project pages on SourceForge, in the 'Documentation' 
section.

If the problem has occurred directly after upgrading RKH, then please
check the CHANGELOG file. It will contain information about changes
made since the previous version of RKH, and may indicate why you are
now experiencing a problem.

Users should also check the rkhunter-users mailing list archives
(available on the web site). The problem will be investigated by the
RKH development team, and, where appropriate, a solution posted on the
mailing list. Hence the mailing list archives may well contain a
solution to the problem.

Additionally, users should check the RKH tracker system (available at
http://sourceforge.net/tracker/?group_id=155034). It is quite
possible that the problem has already been reported to us as a bug or
support request. It is also possible that a fix for the problem has
been provided in the tracker log.

Depending upon the nature of the problem it may be worthwhile trying
an Internet search (for example using google), to see if anyone else
has experienced a similar problem.

Finally, if you have still not found an answer to the problem, then
mail it to the rkhunter-users mailing list. Please provide as much
information as possible about the problem, but do not make the
message excessively long! Information such as your operating system
and version of RKH should always be included.

If you are sure the problem is a bug, or want it considered as a
support request, then please submit it directly into the tracker
system.

