This file is part of IVRE.

Copyright 2011 - 2014 [[mailto:pierre.lalet@cea.fr|Pierre LALET]]

====== DB Server ======

Follow the [[http://docs.mongodb.org/manual/installation/|documentation from MongoDB project]], depending on your distribution. It is recommended to install packages from the MongoDB project rather than the (possibly old) packages from your distribution.

====== IVRE ======

===== Installation =====

The installation of [[doc:README|IVRE]] itself can be done by:

  * using the ''%%setup.py%%'' (classical ''%%./setup.py build; sudo ./setup.py install%%'') script.
  * building an RPM package (you can use the provided ''%%buildrpm%%'' script, or use the ''%%setup.py%%'' script with your own options) and then installing it.
  * using [[doc:DOCKER|Docker]] (in this case you do not need to follow the following instructions, as the Docker containers are already configured).

===== Configuration =====

Default configuration values are hard-coded in ''%%ivre/config.py%%''. You should not change this file, unless you are modifying IVRE and you want to change the default configuration. You do not need to do this if you want to install IVRE with a non-default configuration, you just need to distribute a proper configuration file.

You can override default values in three files:

  * two system-wide:
    * ''%%/etc/ivre.conf%%''
    * ''%%/usr/local/etc/ivre.conf%%'' (read after, so higher priority)
  * one user-specific:
    * ''%%~/.ivre.conf%%'' (the last to be read, so highest priority)

The file should contain lines of type ''%%key = value%%''. Empty lines and comments (starting with the ''%%#%%'' character) are ignored. The following values can be changed:

  * ''%%DB%%'': the URL to use; default is ''%%mongodb:///%%'', meaning use default database (''%%ivre%%'') on the default host (''%%localhost%%''). Here is a more complete example: ''%%mongodb://user:password@host/db?colname_aaa=bbb&colname_ccc=ddd%%''
  * ''%%DB_NMAP%%'', ''%%DB_PASSIVE%%'' and ''%%DB_DATA%%'': specific URLs to use; default is to use the URL from ''%%DB%%'' setting.
  * ''%%GEOIP_PATH%%'': default is ''%%/usr/local/share/ivre/geoip/%%''.

It might be a good idea to have a read-only account everywhere except for some specific users or hosts that need write access to the database (the users that insert scan results with ''%%nmap2db%%'', the users or the hosts that run ''%%p0f2db%%'' and/or ''%%passiverecon2db%%''). It is best to avoid using a configuration with write access to the database when you only need a read access. This can be achieved with users or hosts dedicated to insertion tasks.

===== DB creation =====

Once IVRE has been properly configured, it's time to initialize its databases.

For that, the command-line tools (namely ''%%ipdata%%'', ''%%ipinfo%%'', ''%%scancli%%'' and ''%%runscans-agentdb%%'', respectively for information about IP addresses, passive information, active information and running scans through agents) have a ''%%--init%%'' option.

So you can run, with a user or from a host where the configuration has a write access to the database (add ''%%< /dev/null%%'' to skip the confirmation):

<code>$ scancli --init
This will remove any scan result in your database. Process ? [y/N] y
$ ipinfo --init
This will remove any passive information in your database. Process ? [y/N] y
$ ipdata --init
This will remove any country/AS information in your database. Process ? [y/N] y
# runscans-agentdb --init
This will remove any agent and/or scan in your database and files. Process ? [y/N] y</code>
==== Getting IP data ====

<code># ipdata --download
$ ipdata --import-all --dont-feed-ipdata-cols</code>
==== Web Server ====

Once IVRE has been installed, to also install the web interface, you have to copy or symlink IVRE files to your web server directories, or configure your web server to use IVRE files directly.

The files the web server should serve statically are located in ''%%[PREFIX]/share/ivre/web/static%%'', the folder the web server should serve as CGI is located in ''%%[PREFIX]/share/ivre/web/cgi-bin%%'', and the (optional) folders to use as Dokuwiki content are located in ''%%[PREFIX]/share/ivre/dokuwiki/doc%%'' and ''%%[PREFIX]/share/ivre/dokuwiki/media%%'' (make sure your dokuwiki has been configured with proper server-side URL rewriting).

You may want to change some values, by creating the files ''%%[PREFIX]/share/ivre/web/cgi-bin/scanjsonconfig.py%%'' and ''%%[PREFIX]/share/ivre/web/static/config.js%%'' based on the ''%%-sample%%'' files you'll find in the same directories.

On a typical Debian/Ubuntu installation, these files should be copied or (sym)linked at these locations:

  * ''%%[PREFIX]/share/ivre/web/static/*%%'' -> ''%%/var/www%%''
  * ''%%[PREFIX]/share/ivre/web/cgi-bin/scanjson.py%%'' -> ''%%/usr/lib/cgi-bin/%%''
  * ''%%[PREFIX]/share/ivre/dokuwiki/doc%%''  -> ''%%/var/lib/dokuwiki/data/pages/%%''
  * ''%%[PREFIX]/share/ivre/dokuwiki/media/logo.png%%''  -> ''%%/var/lib/dokuwiki/data/media/wiki/%%''

The values ''%%skip%%'' and ''%%limit%%'' from ''%%scanjsonconfig.py%%'' must match those in the ''%%dflt%%'' object in ''%%config.js%%''.

If you access the web interface by another URL than the "standard" http://localhost/, then you have to set ''%%ALLOWED_REFERERS%%'' in ''%%scanjsonconfig.py%%''

====== Agent ======

If you do not plan to run active scans with remote agents (where IVRE will not be installed), you can skip this section.

The agent does not require IVRE to be installed. It is a script that needs to be adapted to each situation.

The agent is only needed when you cannot install IVRE on the machine used to scan or when you want to use many machines to run one scan.

It requires a POSIX environment, and the commands ''%%screen%%'', ''%%rsync%%'' and ''%%nmap%%'' (of course). See the [[doc:AGENT|AGENT]] file for more information about that.

