This file is part of IVRE.

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

====== What is Docker? ======

Docker is an open-source platform that automates the deployment of applications inside containers. See the [[http://www.docker.com/|official website]].

This document describes the (easy) installation of [[doc:README|IVRE]] using Docker containers, including the database and web servers.

====== Using Vagrant ======

If you already manage your Docker containers using [[https://www.vagrantup.com/|Vagrant]], or if you want to give it a try (or if you are not running a Linux system and want to use Docker anyway), you can use it to get the images, prepare and run the containers.

You'll need a recent version of Vagrant (at least 1.6), since Docker providers do not exist in prior versions.

With the ''%%Vagrantfile%%'' as it is provided, the TCP port 80 of your host will be used, so you need either to make sure it is not already in use, or to modify the ''%%Vagrantfile%%'' after the ''%%cp%%'' step in the instructions below to use another port.

To use the ''%%Vagrantfile%%'' located in the ''%%docker/%%'' directory of the source tree (or the ''%%[PREFIX]/share/ivre/docker/%%'' directory when IVRE has been installed), run (from the folder where you want to store your data):

<code>$ mkdir -m 1777 var_lib_mongodb var_log_mongodb ivre-share
$ cp [path to ivre source]/docker/Vagrantfile .
$ vagrant up --no-parallel</code>
The ''%%--no-parallel%%'' option prevents Vagrant from starting the ''%%ivreweb%%'' container before the ''%%ivredb%%'' is ready.

The DB and Web servers should now be running, with the TCP port 80 of your host redirected to the ''%%ivreweb%%'' container.

To get a shell with the CLI tools and Python API, attach to the ''%%ivreclient%%'' container:

<code>$ docker attach ivreclient
ivre@fd983ba5e6fd:~$</code>
You can detach from the container (without stopping it) by using ''%%C-p C-q%%'' and attach to it again later with the same ''%%docker attach ivreclient%%'' command.

To initialize the database and start playing with IVRE, you need to enter some commands described in the [[#a_command_line_client|related section below]].

====== Without Vagrant ======

===== Getting the images =====

You can either get the images from a repository on the Internet or build them. I'll consider you are on a computer with Docker installed and an access to the Internet.

==== From the Internet ====

<code>$ for img in agent base client db web ; do
> docker pull "ivre/$img"
> done</code>
==== Build the images ====

You can also build the images from the provided ''%%Dockerfile%%''s. For that, from the ''%%docker/%%'' directory, run:

<code>$ docker pull debian:testing
$ for img in agent base client db web ; do
> docker build -t "ivre/$img" "$img"
> done</code>
This might take a long time.

It is also possible to build the ''%%ivre/base%%'' image without fetching the //tarball// from GitHub, by creating it locally and using the ''%%base-local%%'' directory instead of ''%%base%%''. From the repository root, run:

<code>$ git archive --format=tar --prefix=ivre/ HEAD -o docker/base-local/ivre.tar
$ cd docker
$ docker build -t ivre/base base-local</code>
===== Running =====

==== The database server ====

To create the volume to store MongoDB data, run (''%%chmod%%''-ing to ''%%1777%%'' is a bit overkill, ''%%chown%%''-ing it to the UID of the MongoDB user in the container would do):

<code>$ mkdir -m 1777 var_lib_mongodb var_log_mongodb</code>
To run an instance of the MongoDB server ready for IVRE, issue (this will run the instance and give it the name ''%%ivredb%%''; we will use this name later):

<code>$ docker run -d --name ivredb --hostname ivredb \
>        --volume "`pwd`/var_lib_mongodb":/var/lib/mongodb \
>        --volume "`pwd`/var_log_mongodb":/var/log/mongodb \
>        ivre/db</code>
You can add the option ''%%-p 27017:27017%%'' to have the MongoDB service accessible through the host's TCP port 27017.

==== The web server ====

<code>$ docker run -d --name ivreweb --hostname ivreweb \
>        --link ivredb:ivredb --publish 80:80 ivre/web</code>
The ''%%--publish 80:80%%'' option creates a redirection and makes the web server accessible through the host's TCP port 80.

If you want to use modified configuration files, you can use ''%%--volume%%''. For example:

<code>$ docker run -d --name ivreweb --hostname ivreweb \
>        --volume "`pwd`/scanjsonconfig.py:/usr/local/share/ivre/web/cgi-bin/scanjsonconfig.py"
>        --volume "`pwd`/nginx-default-site:/etc/nginx/sites-available/default"
>        --link ivredb:ivredb --publish 80:80 ivre/web</code>
==== A command line client ====

First, place Nmap result files (XML format) in a specific directory:

<code>$ mkdir -m 1777 ivre-share
$ cp -r /path/to/my/nmap/results.xml ivre-share</code>
Now to get a shell in an IVRE client instance (for command line actions), issue:

<code>$ docker run -i -t --name ivreclient --hostname ivreclient \
>        --link ivredb:ivredb --volume "`pwd`/ivre-share":/ivre-share \
>        ivre/client</code>
This gives a shell in the ''%%ivreclient%%'' container, and from there we can use IVRE's command line tools and Python API. For example, to initialize the database:

<code>ivre@ivreclient:~$ ipinfo --init
This will remove any passive information in your database. Process ? [y/N] y
ivre@ivreclient:~$ ipdata --init
This will remove any country/AS information in your database. Process ? [y/N] y
ivre@ivreclient:~$ scancli --init
This will remove any scan result in your database. Process ? [y/N] y
ivre@ivreclient:~$ runscans-agentdb --init
This will remove any agent and/or scan in your database and files. Process ? [y/N] y
ivre@ivreclient:~$ ipdata --download --import-all --dont-feed-ipdata-cols
[...]</code>
The latest command will take a long time. Then we can integrate the Nmap results to the database:

<code>ivre@ivreclient:~$ nmap2db -r -s MySource -c MyCategory /ivre-share</code>
You can then exit the shell (''%%C-d%%''), this will stop the container.

<code>ivre@ivreclient:~$ exit</code>
You can start the container again later by issuing:

<code>$ docker start -i ivreclient
ivre@ivreclient:~$</code>
If you do not want to exit the shell but only detach from it, use ''%%C-p C-q%%''. You can attach to it again later by issuing ''%%docker attach ivreclient%%''.

