INSTALLATION INSTRUCTIONS FOR OSPD-NMAP
=======================================

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

Prerequisites:
* python 2.7 or python 3
* ospd: Base class for OSP servers.
* Subprocess: Native Python library to run processes.


Installing OSPD-NMAP
--------------------

For executing nmap a low privileged user account is sufficient for
some basic operations. However, some details are only available with
a high privileged user account.


Via virtualenv
..............

The preferred way to install ospd-nmap is to do so inside a virtualenv,
this way, the server and its dependency are well isolated from system-wide
updates, making it easier to upgrade it, delete it, or install dependencies
only for it. Refer to the virtualenv documentation for further information.

First you need to create a virtualenv somewhere on your system::

    virtualenv ospd-nmap

Finally install OSPD-NMAP inside your newly created virtualenv::

    ospd-nmap/bin/pip install ospd_nmap-x.y.z.tar.gz

Note: As ospd is not (yet) available through PyPI, you probably want to
install it manually first inside your virtualenv prior installing OSPD-NMAP.

To run OSPD-NMAP, just start the binary placed inside the virtualenv::

    ospd-nmap/bin/ospd-nmap


(Sub-)System-wide
.................

To install OSPD-NMAP 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/


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

You need TLS certificates for each of your OSP daemons. You may use
the same certificates for all servers if you like.

By default those certificates are used which are also used by OpenVAS
(see paths with "ospd-nmap --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 servers):

$ 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 the 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 Nmap" --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 Nmap

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


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

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

$ python
>>> import ospd_nmap.wrapper
>>> help (ospd_nmap.wrapper)

An equivalent to this is:

$ pydoc ospd_nmap.wrapper

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.


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