INSTALLATION INSTRUCTIONS FOR OSPD
==================================

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


Prerequisites for OSPD
----------------------

Prerequisites:
* python 2.7, python 3.3 or python 3.4
* python-setuptools

For using ospd_ssh:
* python-paramiko

On Debian 8 this should work to install dependencies:
# apt-get install python-setuptools python-paramiko


Building OSPD
-------------

To install OSPD into directory <prefix> run this command:

python setup.py install --prefix=<prefix>

The default for <prefix> is /usr/local

Be aware that this might automatically download and install missing
Python packages. To prevent this, you should install the prerequisites
first with the mechanism of your system (for example via apt or rpm).

You may need to set the PYTHONPATH like this before running
the install command (perhaps with another python version):

export PYTHONPATH=<prefix>/lib/python2.7/site-packages/

You also may need to create directories prior to the install:

mkdir -p <prefix>/lib/python2.7/site-packages


Creating certificates
---------------------

You need TLS certificates for each of your OSPD service. You may use
the same certificates for all services if you like.

By default those certificates are used which are also used by OpenVAS
(see paths with "ospd-NAME --help"). Of course this works only
if installed in the same environment.
 
In case you do not have already a certificate to use, you may quickly
create your own one (can be used for multiple ospd daemons):

$ openvas-manage-certs.sh -s

And sign it with the CA checked for by the client.


Registering a OSP daemon at OpenVAS Manager
-------------------------------------------

The file README explains how to control a OSP daemon via command line.

It is also possible to register a OSP daemon at the OpenVAS Manager
and then use OMP clients to control the OSP daemon, for example the
web interface GSA.

You can register either via the GUI (Configuration->Scanners) and create
a new Scanner there.

Or you can create a scanner via openvasmd command line (adjust host,
port, paths etc. for your daemon):

$ openvasmd --create-scanner="OSP Scanner-Name" --scanner-host=127.0.0.1 --scanner-port=1234 \
           --scanner-type="OSP" --scanner-ca-pub=/usr/var/lib/openvas/CA/cacert.pem \
           --scanner-key-pub=/usr/var/lib/openvas/CA/clientcert.pem \
           --scanner-key-priv=/usr/var/lib/openvas/private/CA/clientkey.pem 

Check whether OpenVAS Manager can connect to the OSP daemon (needs to run of course):

$ openvasmd --get-scanners
08b69003-5fc2-4037-a479-93b440211c73  OpenVAS Default
3566ddf1-cecf-4491-8bcc-5d62a87404c3  OSP Scanner-Name

$ openvasmd --verify-scanner=3566ddf1-cecf-4491-8bcc-5d62a87404c3
Scanner version: 1.0.

Of course, using OMP via command line tool "omp" to register a
OSP Scanner is also possible as a third option.


Creating a source archive
-------------------------

To create a .tar.gz file for the ospd module run this command:

python setup.py sdist

This will create the archive file in the subdirectory "dist".


Documentation
-------------

To generate the protocol documentation for OSP in HTML format, run the script:

./doc/generate

This will create the osp.html file in the subdirectory "doc".

Source code documentation can be accessed over the usual methods,
for example:

$ python
>>> import ospd.ospd
>>> help (ospd.ospd)

An equivalent to this is:

$ pydoc ospd.ospd

To explore the code documentation in a web browser:

$ pydoc -p 12345
pydoc server ready at http://localhost:12345/
 
For further options see the man page of pydoc.


Tests
-----

To run the tests, execute the command:

python setup.py test

If successful, something like the text below will be outputted:
...
Ran 14 tests in 0.025s

OK

Don't get confused by the various error message you will see. Those
are part of the tests. The "OK" at the end is what counts.
