INSTALLATION INSTRUCTIONS FOR OPENVAS-MANAGER
=============================================

Please note: The reference system used by most of the developers is Debian
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-manager
---------------------------------

Prerequisites:
* cmake
* glib-2.0 >= 2.16
* gnutls >= 2.8
* openvas-libraries >= 8.0.5
* sqlite3
* pkg-config

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

Please see the section "Prerequisites for Optional Features" below additional
optional prerequisites.


Compiling openvas-manager
-------------------------

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.  Note: It is assumed that the other
OpenVAS components are installed to the same path.  If not, you need to set
some paths separately, see below for details.

Thereafter, the following commands are useful.

    $ make                # build the manager
    $ 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

In case you want to install openvas-manager to a different path from the
other OpenVAS modules, you might need to set some paths explicitly
before running cmake:

Adjust any values in the Variables section of CMakeLists.txt:
The certificate and key locations in OPENVAS_SERVER_CERTIFICATE,
OPENVAS_SERVER_KEY, OPENVAS_CLIENT_CERTIFICATE, OPENVAS_CLIENT_KEY and
OPENVAS_CA_CERTIFICATE may need modifying.


Certificate Generation
----------------------

Note that the manager always connects to the scanner via client certificate
using certificate based authentication exclusively.  This means that you
have to generate the certificate and key for this and provide them to the
manager.
The easiest way to do this is to use the "openvas-mkcert-client" script
provided by the openvas-scanner module.  You can generate the certificates,
register them with the OpenVAS scanner and install the client certificates
into the proper location for use with openvas-manager with a single command:

    $ openvas-mkcert-client -n -i

Or you can call the script without parameters if you want to have finer
control over the process:

    $ openvas-mkcert-client

If you did not use the "-i" option described above, the script will
create the client certificate and key in a temporary directory.  In order
to have the manager use the certificate and key, you have to copy the
files into a specific location.  Change into the temporary directory
created by openvas-mkcert-client and execute the following commands:

    $ cp key_om.pem /var/lib/openvas/private/CA/clientkey.pem
    $ cp cert_om.pem /var/lib/openvas/CA/clientcert.pem

Please note that the target directory in the commands above might have
to be prefixed with the prefix you have set earlier.


Initializing the Database
-------------------------

Now you can initialize the OpenVAS Manager database.
You need a running OpenVAS Scanner (openvassd) for this
as the Manager will retrieve all NVT details from the Scanner.
Run this command if you are using the default ports:

$ openvasmd --rebuild

This command can be repeated anytime to update the database
with updated NVT data, regardless of whether openvasmd already
runs as a service in the background or not.


Migrating the Database
----------------------

If you have used Manager before, you might need to migrate
the database to the current data model. Use this command
to run the migration:

$ openvasmd --migrate


Creating an administrator user for OpenVAS
------------------------------------------

You can create an administrator user with the --create-user option of
"openvasmd":

$ openvasmd --create-user=myuser

The new user's password is printed on success.

An administrator user can later create further users or
administrators via clients like the Greenbone Security Assistant (GSA).

Also, the new user can change her password via GSA.


Optimizing the database
-----------------------
OpenVAS Manager offers the command line option --optimize=<name> to run various
 optimization of the database. The currently supported values for <name> are:

vacuum
  This option can reduce the file size by freeing some unused storage
  space in the database.
  For more information see the documentation for the VACUUM command of the
  database back-end you are using.

analyze
  This option updates various internal statistics of the database used to
  optimize queries.
  For more information see the documentation for the ANALYZE command of the
  database back-end you are using.

cleanup-config-prefs
  This option removes duplicate preferences from Scan Configs.

remove-open-port-results
  This option removes results which were used in older versions of OpenVAS to
  indicate an open port. Since open ports are now part of the host details
  these results are now obsolete in most cases.

cleanup-port-names
  This cleans up the ports of results as stored in the database by removing
  parts that do not conform to the format <port>/<protocol>.
  For example the application name will be removed from a port using the old
  format "telnet (23/tcp)", reducing it to the new format "23/tcp".
  This makes filtering results and delta reports more consistent.

cleanup-result-severities
  This cleans up results with no severity by assigning the default
  severity set by the user owning the result.
  All new results should have a severity assigned but this was not ensured in
  older versions, so this function can be used to correct missing severity
  scores in older reports.

rebuild-report-cache
  This clears the cache containing the unfiltered result counts of all reports
  and fully rebuilds it.

update-report-cache
  This creates the cache containing the unfiltered result counts of all reports
  that are not cached yet.


Import/Update IANA Services Names
---------------------------------

If you want the Manager to resolve port names when outputing reports for
instance, you need to import the information from a Services Names list.

In order to update the database, download the port names list:

$ wget http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml

Then provide it as an argument to openvas-portnames-update script:

$ openvas-portnames-update service-names-port-numbers.xml

You can safely delete the list after that as it is not needed and all relevant
information has been imported into the database.

$ rm service-names-port-numbers.xml

Note that IANA updates this list frequently. The same steps could be followed to
update the information in the database from a newer list.

Currently, the helper tool supports only the official IANA Services Names list.


Migrating Credentials
---------------------

While OpenVAS Manager 4.0 initially place the credential encryption key in
<install-prefix>/etc/openvas/gnupg, OpenVAS Manager 5.0 has switched to using
<install-prefix>/var/lib/openvas/gnupg for better FHS compliance and to set the
key apart from the one used for signature verification.

In order to continue using your encrypted credentials, please copy the contents
of <install-prefix>/etc/openvas/gnupg to
<install-prefix>/var/lib/openvas/gnupg.

Make sure the permissions on <install-prefix>/var/lib/openvas/gnupg are
suitable for the user OpenVAS Manager is running as.

Once your encrypted credentials are working again, feel free to remove the
credential encryptions key from the keyring in
<install-prefix>/etc/openvas/gnupg and the signature verification key from the
one in <install-prefix>/var/lib/openvas/gnupg.


Encrypted Credentials
---------------------

By default the Manager stores private key and password parts of target
credentials encrypted in the database.  This voids leaking such keys
via backups.  To be able to do a proper restore of the data, it is
important to also backup the encryption key.  The easiest way to do
this is to create backup of the entire directory tree

   <install-prefix>/var/lib/openvas/gnupg

and store it at a safe place independent from the database backups.
This needs to be done only once after the key has been created or
changed.  The Manager creates the key on the fly if it does not
exists.  If needed the key can also be created in advance using:

$ openvasmd --create-credentials-encryption-key

To check whether the key has been generated you may use the command

$ gpg --homedir <install-prefix>/var/lib/openvas/gnupg --list-secret-keys

An example output would be

  sec   2048R/1B55390F 2013-01-18
  uid                  OpenVAS Credential Encryption

Your key will have the same user ID ("OpenVAS Credential Encryption")
but another keyid (1B55390F) and another creation date (2013-01-18).

Older versions of the Manager didn't used encrypted credentials.  Thus
for old installations the database may hold a mix of cleartext and
encrypted credentials.  Note, that after changing a cleartext
credentials it will be saved encrypted.

To encrypt all existing credentials you may use

$ openvasmd --encrypt-all-credentials

Key change: If you disable the current key (see also the gpg manual) and
create a new key, this command will decrypt using the old but disabled key
and then re-encrypt using the new key.  The command --decrypt-all-credentials
may be used to revert to plaintext credentials:

$ gpg --homedir /var/lib/openvas/gnupg -K

Look for the current key and remember its keyid. Then:

$ gpg --homedir /var/lib/openvas/gnupg --edit-key KEYID

At the prompt enter "disable" followed by "save" and "quit".
Then create a new key and re-encrypt all passwords:

$ openvasmd --create-credentials-encryption-key
$ openvasmd --encrypt-all-credentials

No encryption: If for backward compatibility reasons encrypted credentials
are not desired, the manager must _always_ be started with the option
--disable-encrypted-credentials.


Prerequisites for Optional Features
-----------------------------------

Certain features of the Manager also require some programs at run time:

Prerequisites for generating PDF reports:
* pdflatex

Prerequisites for generating HTML reports:
* xsltproc

Prerequisites for generating verinice reports:
* xsltproc, xmlstarlet, zip

Prerequisites for generating credentials RPM / DEB packages:
* rpm
* fakeroot
* alien

Prerequisites for generating credentials .exe packages:
* makensis (usually distributed as part of nsis)

Prerequisites for generating system reports:
* A program in the PATH, with usage "openvasmr seconds type", where
  seconds is the number of seconds before now that the report covers,
  and type is the type of report.  When called with type "titles" the
  script must print a list of possible types, where the name of the
  type is everything up to the first space and everything else is a
  title for the report.  When called with one of these types openvasmr
  must print a PNG in base64 encoding.  When called with the special
  type "blank", openvasmr must print a PNG in base64 for the Manager to
  use when a request for one of the titled types fails.  openvasmr may
  indicate failure by simply refraining from printing.

Prerequisites for signature verification:
* gnupg

Prerequisites for HTTP alerts:
* wget

Prerequisites for Sourcefire Connector alert:
* A program in the PATH called greenbone_sourcefire_connector that takes args
  IP, port, PKCS12 file and report file in Sourcefire format.

Prerequisites for verinice .PRO Connector alert:
* A program in the PATH called greenbone_verinice_connector that takes args
  IP, port, username, password and report file in verinice .PRO format.

Prerequisites for SCP alert:
* sshpass
* scp

Prerequisites for Send alert:
* socat

Prerequisites for splitting large XML files (see tools/extra/README):
* python


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.
