INSTALL 6.93 KB
Newer Older
Lock Lin's avatar
Lock Lin committed
1 2 3 4
INSTALLATION INSTRUCTIONS FOR OPENVAS-SCANNER
=============================================

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

8 9 10

Prerequisites for openvas-scanner
---------------------------------
Lock Lin's avatar
Lock Lin committed
11 12 13

Prerequisites:
* cmake
14 15 16
* glib-2.0 >= 2.16
* libgcrypt
* openvas-libraries >= 8.0.2
Lock Lin's avatar
Lock Lin committed
17
* pkg-config
18
* redis >= 2.4.0
Lock Lin's avatar
Lock Lin committed
19 20 21 22 23 24

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

25 26 27 28

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

Lock Lin's avatar
Lock Lin committed
29 30 31 32
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:

33 34 35 36 37 38
    $ export PKG_CONFIG_PATH=/your/location/lib/pkgconfig:$PKG_CONFIG_PATH

Create a build directory and change into it with

    $ mkdir build
    $ cd build
Lock Lin's avatar
Lock Lin committed
39 40 41

Then configure the build with

42
    $ cmake -DCMAKE_INSTALL_PREFIX=/path/to/your/installation ..
Lock Lin's avatar
Lock Lin committed
43 44 45

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

46
    $ cmake ..
Lock Lin's avatar
Lock Lin committed
47

48
This only needs to be done once.
Lock Lin's avatar
Lock Lin committed
49 50 51 52 53 54 55

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
56
    $ make rebuild_cache  # rebuild the cmake cache
Lock Lin's avatar
Lock Lin committed
57

58 59
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.
Lock Lin's avatar
Lock Lin committed
60

61 62
To clean up the build environment, simply remove the contents of the "build"
directory you created above.
Lock Lin's avatar
Lock Lin committed
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79


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.

80 81 82 83 84 85 86 87 88
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
Lock Lin's avatar
Lock Lin committed
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
   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.

110
4) You can launch openvas-scanner using the following command:
Lock Lin's avatar
Lock Lin committed
111 112 113 114 115 116 117 118

   $ 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.

119 120 121 122 123 124
   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.

Lock Lin's avatar
Lock Lin committed
125 126 127 128 129 130 131
   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.

132 133 134 135
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.
Lock Lin's avatar
Lock Lin committed
136

137
   Two examples are installed which you may use directly for a quick start:
Lock Lin's avatar
Lock Lin committed
138

139
   $ redis-server /share/doc/openvas-scanner/example_redis_2_4.conf
Lock Lin's avatar
Lock Lin committed
140

141
   or
Lock Lin's avatar
Lock Lin committed
142

143
   $ redis-server /share/doc/openvas-scanner/example_redis_2_6.conf
Lock Lin's avatar
Lock Lin committed
144

145 146 147 148 149 150 151 152 153
   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.
Lock Lin's avatar
Lock Lin committed
154 155 156 157 158 159 160 161 162


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.
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185


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.