INSTALLATION INSTRUCTIONS FOR OPENVAS-SCANNER
=============================================

Please note: The reference system used by most of the developers is Debian
GNU/Linux 'Wheezy' 7.  The build might fail on any other systems.
Also it is necessary to install dependent development packages.


Prerequisites for openvas-scanner
---------------------------------

Prerequisites:
* cmake
* glib-2.0 >= 2.16
* libgcrypt
* openvas-libraries >= 8.0.2
* pkg-config
* redis >= 2.4.0

Prerequisites for building documentation:
* Doxygen
* xmltoman (optional, for building man page)
* sqlfairy (optional, for producing database diagram)


Compiling openvas-scanner
-------------------------

If you have installed required libraries to a non-standard location, remember to
set the PKG_CONFIG_PATH environment variable to the location of you pkg-config
files before configuring:

    $ export PKG_CONFIG_PATH=/your/location/lib/pkgconfig:$PKG_CONFIG_PATH

Create a build directory and change into it with

    $ mkdir build
    $ cd build

Then configure the build with

    $ cmake -DCMAKE_INSTALL_PREFIX=/path/to/your/installation ..

or (if you want to use the default installation path /usr/local)

    $ cmake ..

This only needs to be done once.

Thereafter, the following commands are useful.

    $ make                # build the scanner
    $ make doc            # build the documentation
    $ make doc-full       # build more developer-oriented documentation
    $ make install        # install the build
    $ make rebuild_cache  # rebuild the cmake cache

Please note that you may have to execute "make install" as root, especially if
you have specified a prefix for which your user does not have full permissions.

To clean up the build environment, simply remove the contents of the "build"
directory you created above.


Setting up openvas-scanner
--------------------------

Setting up an openvas-scanner requires the following steps:

1) The scanner service communicate through an SSL connection.
   In order to establish this connection, the scanner needs to have
   an SSL certificate it can present to the client to prove its identity. You
   can interactively create this certificate by using the following command:

   $ openvas-mkcert

   This command will guide you through the certificate creation and place the
   certificates in the correct locations on your system.

2) (optional) You may decide to change the default scanner preferences
   by setting them in the file $prefix/etc/openvassd.conf. If that file does
   not exist (default), then the default settings are used. You can view
   them with "openvassd -s". The output of that command is a valid configuration
   file. The man page ("man openvassd") provides details about the available
   settings, among these opportunities to restrict access of scanner regarding
   scan targets and interfaces.

3) In order to run vulnerability scans, you will need a collection of Network
   Vulnerability Tests (NVTs) that can be run by openvas-scanner. Initially,
   your NVT collection will be empty. It is recommended that you synchronize
   with an NVT feed service before starting openvas-scanner for the first time.

   Your installation is preconfigured to synchronize with the OpenVAS NVT Feed.
   Simply execute the following command to receive thousands of NVTs from this
   feed service:

   $ openvas-nvt-sync

   Please note that you will need at least one of the following tools for a
   successful synchronization:
   * rsync
   * wget
   * curl

   NVT feeds are usually updated a few times per week. Be sure to update your
   NVT collection regularly to detect the latest threats.
   Please visit the OpenVAS website for more information on available NVT feeds
   and instructions for integrating feeds into your scanner installation.

4) You can launch openvas-scanner using the following command:

   $ openvassd

   Be aware that the first launch of openvas-scanner after the initial feed
   synchronization or after large feed updates will take longer than usual since
   the internal scanner cache has to be updated. Subsequent launches will be
   much quicker.

   Sending SIGHUP to the scanner main process will initiate a reload of the
   feed content and of the scanner preferences. This will not affect running
   scans. The NVT synchronisation routine will try to send the SIGHUP to the
   scanner on its own. This works only if the pid-file of scanner is found
   which is expected to be /var/run/openvas/openvassd.pid.

   Please note that although you can start openvassd as a user without elevated
   privileges, it is recommended that you start openvassd as root since a number
   of Network Vulnerability Tests (NVTs) require root privileges to perform
   certain operations like packet forgery. If you run openvassd as a user
   without permission to perform these operations, your scan results are very
   likely to be incomplete.

5) The scanner needs a running redis server to temporarily store information
   gathered on the scanned hosts. Redis 2.4 and newer is supported but 2.6
   is recommended. See doc/redis_config.txt to see how to setup and run a redis
   server.

   Two examples are installed which you may use directly for a quick start:

   $ redis-server /share/doc/openvas-scanner/example_redis_2_4.conf

   or

   $ redis-server /share/doc/openvas-scanner/example_redis_2_6.conf

   or copy the example to another location, edit and use the copy instead.

6) Once the scanner has started, openvas-manager can act as a client and control
   the scanner. The actual user interfaces (for example GSA or CLI-OMP)
   will only interact with the manager, not the scanner.


You will be guided through creation of user accounts by the INSTALL file
of OpenVAS Manager.


If you encounter problems, the files /var/log/openvas/openvassd.messages and
/var/log/openvas/openvassd.dump may contain useful information. (The exact
location of these files may differ depending on your distribution and
installation method.) Please have these files ready when contacting the OpenVAS
developers through the OpenVAS mailing list or the online chat or submitting bug
reports at http://bugs.openvas.org/ as they may help to pinpoint the source of
your issue.


Static code analysis with the Clang Static Analyzer
---------------------------------------------------

If you want to use the Clang Static Analyzer (http://clang-analyzer.llvm.org/)
to do a static code analysis, you can do so by adding the following parameter
when configuring the build:

  -DCMAKE_C_COMPILER=/usr/share/clang/scan-build/ccc-analyzer

Note that the example above uses the default location of ccc-analyzer in Debian
GNU/Linux and may be different in other environments.

To have the analysis results aggregated into a set of HTML files, use the
following command:

    $ scan-build make

The tool will provide a hint on how to launch a web browser with the results.

It is recommended to do this analysis in a separate, empty build directory and
to empty the build directory before "scan-build" call.
