Skip to content

Installation & configuration guides#

Overview#

Application Stack TheHive can be deployed on a standalone server or as a cluster. The application relies on:

Apache Cassandra to store data (Supported version: 4.x).

Elasticsearch as indexing engine (Supported version: 7.x).

A file storage solution is also required ; the local filesystem of the server hosting the application is adequate in the standalone server scenario ; S3 MINIO otherwise.

Using Lucene

Since version 5.1, TheHive does NOT support Lucene backend as index engine any more.

Lucene was an option to handle the data index with TheHive 4.1.x ; to migrate your index to Elasticsearch, follow this guide.

Architecture#

Each layer, TheHive application, the Database & index engine, and file storage, is independant and can be set up as a standalone node or cluster. As a result, TheHive could be setup and work in a complex clustered archicteture, using virtual IP addresses and load balancers.

Standalone server

All applications are installed on the same server.

  • Cassandra
  • Elasticsearch
  • Files are store on the filesystem (or MinIO if desired)
  • TheHive
  • NGINX (optional): to manage HTTPS communications

Instructions included in the step-by-step installation guide ends up to install a standalone server.

TheHive and all applications of the stack are flexible enough to choose the right setup according with the needs.

Each layer and node can be installed:

  • on a dedicated operating system
  • with another application (for example: 1 node of Cassandra with 1 not of Elasticseach)

The installation guide for a 3 nodes cluster gives all details for a more complex setup.

Requirements#

Hardware requirements depends on the number of concurrent users (including integrations) and how they use the system. The following table diplays safe thresholds when hosting all services on the same machine:

Number of users TheHive Cassandra ElasticSearch
< 10 2 / 2 GB 2 / 2 GB 2 / 2 GB
< 20 2-4 / 4 GB 2-4 / 4 GB 2-4 / 4 GB
< 50 4-6 / 8 GB 4-6 / 8 GB 4-6 / 8 GB

Tip

If you are installing everything on the same server, we recommend at least 4 cores and 16 GB of RAM. And don't forget to set up jvm.options at least for Elasticsearch.

Operating systems#

TheHive has been tested and is supported on the following operating systems:

  • Ubuntu 20.04 LTS & 22.04 LTS
  • Debian 11
  • RHEL 8
  • Fedora 35 & 37

StrangeBee also provides an official Docker image.

Installation guides#

Too much in a hurry to read ?

If you are using one of the supported operating systems, use our all-in-one installation script: 

wget -q -O /tmp/install.sh https://archives.strangebee.com/scripts/install.sh ; sudo -v ; bash /tmp/install.sh

This script helps with the installation process on a fresh and supported OS ; the program also run successfully if the conditions in terms of hardware requirements are met.

Once executed, several options are available:

  1. Setup proxy settings ; will configure everything on the host to work with a HTTP proxy, and custom CA certificate.
  2. Install TheHive ; use this option to install TheHive 5 and its dependencies
  3. Install Cortex and all its dependencies to run Analyzers & Responders as Docker Iiages
  4. Install Cortex and all its dependencies to run Analyzers & Responders on the host (Debian and Ubuntu ONLY)

For each release, DEB, RPM and ZIP binary packages are built and provided. Discover how to install TheHive quickly by following our installation guides:

Use a dedicated server#

TheHive can be used on virtual or physical servers.

Our step-by-step guide let you prepare, install and configure TheHive and its prerequisites for Debian and RPM packages based Operating Systems, as well as for other systems and using our binary packages.

TheHive supports beeing installed in virtualized environments:

  • Using VMware
  • Using Proxmox virtual machines or containers (lxc)

Use Docker #

An Official Docker image publicly available. Follow our installation guide for Docker to use it in production.

Use Kubernetes #

TheHive is now compatible with Kubernetes - follow the related guide here.

Configuration Guides#

The configuration files are stored in the /etc/thehive folder:

  • application.conf contains all parameters and options
  • logback.xml is dedicated to log management
/etc/thehive
├── application.conf
├── logback.xml
└── secret.conf

A separate secret.conf file is automatically created by DEB or RPM packages. This file contains a secret that should be used by one instance.

The configuration should only contain the necessary information to start the application:

All other settings are available in the application WebUI.

Advanced uses cases#

Upgrade from TheHive 4.x (standalone server)#

F.A.Q

Can I upgrade from TheHive 4.0.x ?#

Yes, all TheHive 4.x can be updated to TheHive 5; Find how to update in this dedicated guide.

I use TheHive 3.x, can I upgrade my data to TheHive 5 ?#

TheHive 3 is out of support since 31 December 2021. Please contact StrangeBee for further assistance.

TheHive as a cluster#

Install a cluster with 3 nodes#

If you are looking to install a cluster (fault tolerant, H.A., ...), the following guide details all the installation and configuration steps to make a cluster with 3 nodes working. In this example, the cluster is composed of:

  • 3 TheHive nodes
  • 3 Cassandra nodes
  • 3 Elasticsearch nodes
  • 3 Min.IO nodes

Upgrade a cluster#

Upgrade a cluster

Update from TheHive 3.x#

TheHive 3.x is not supported any more since 31st of December, 2021.

Contact StrangeBee for further assistance at contact@strangebee.com.