= Redis KB server =

== Presentation ==
Redis (http://redis.io) is used to store and access the KB. Scans won't run if
they cannot access the server and might be significantly slowed down if redis is
not properly configured.

The feature has been developed with neither cluster mode nor replication
enabled. Redis 2.4 and 2.6 are supported. Versions 2.6 and higher are
recommended.


== Connection ==
OpenVAS can currently only access redis via a unix socket. This choice has been
made for the sake of speed and security. No authentication is supported yet, we
rely on filesystem permissions to protect the KBs.

The path to the unix socket is '/tmp/redis.sock' by default, and can be changed
using the 'kb_location' parameter.

On the redis side, use the following directives:

  port 0 # prevent redis from listening on a TCP socket
  unixsocket /tmp/redis.sock
  unixsocketperm 700
  timeout 0


== Database number ==
Multiple KBs can be served in parallel, for multiple hosts scanned by one or
several tasks. This is done using redis databases, which are independent
namepaces. The DB#0, which is where every new connected client starts, is
reserved and used to schedule concurrent accesses to the available namespaces.
It contains a single variable, called 'OpenVAS.__GlobalDBIndex'. This variable
is a bitmap of the different namespaces. When opening a new DB, the scanner will
look for the first bit that is not set, starting from 1 to the maximum number of
available DBs. If none is found, the scanner will enter a wait and retry loop.
Otherwise, it will (atomically, along with the check) set the bit to 1 and
switch to the selected namespace.

It is therefore important that redis exports enough databases. This number can
be calculated using the following formula:

  #DB = 1 + (#of parallel tasks) * (#of parallel hosts)

When using network scan, add one slot for the network DB.

The desired/needed value should be set to redis.conf, as a 'databases'
directive.

For instance:

  databases 128


== Clients numbers ==
Redis can limit the number of clients served concurrently. This can be safely
set to a pretty high number. You can estimate the number of clients that the
server will have to serve:

  #CLI = 1 + (#of parallel tasks) * (#of parallel hosts) * (#of concurrent NVTs)

For instance:

  maxclients    512


== Debugging and monitoring a scan via redis ==

Once redis-server is started, you can issue the following command to see
everything that happens during the execution.

$ redis-cli -s <path to the redis server socket> MONITOR

The default path is /tmp/redis.sock. Then start the scan or
openvas-nasl. You should be able to follow precisely the interactions
between the scanner and the KB server.

See also: http://redis.io/commands/MONITOR


To enter an interactive mode type

$ redis-cli -s <path to the redis server socket>

redis /tmp/redis.sock> keys *
1) "OpenVAS.__GlobalDBIndex"
redis /tmp/redis.sock> select 1
OK

Then you can search for keys with a pattern ("keys *" will dump all
keys present):

redis /tmp/redis.sock[1]> keys "*ALARM*"

Note that keys will disappear once a scan of a host finished.
When the scanner is not active, the store is empty.

The keys contain sets, not strings. So instead of the "get" command
you need to use "smembers" to view the content:

redis /tmp/redis.sock[1]> smembers Sun/VirtualBox/Lin/Ver
1) "4.3.12.93733"
