Skip to main content

Kiuwan On-Premises Distributed Installation Guide

The Kiuwan On-Premises installer is a powerful tool that suits multiple environment scenarios:

  • Single-host, fully contained installation.
  • Multi-host installation where infrastructure services are externalized.
  • Multi-host installation where Kiuwan services are distributed.
  • Any combination of the two previous scenarios.

Depending on your needs, a different installation approach will be needed. Check this installation guide for details on how to proceed and to find the solution that best fits your requirements.
 

System requirements

Installation requirements

It is mandatory for any host where Kiuwan On-Premises is installed to meet these requirements:

  • Linux distribution
  • Linux kernel version 3.10 or higher
  • Connectivity to SMTP Mail Server.
  • Internet connectivity during the installation process (see Needed internet connections).
  • The installing user can be a root user (or with sudo privileges) or a non-root user. If you choose to install as a non-root user, some sections below need sudo privileges to create users, add namespace mapping, and make Docker daemon changes.
  • When running the provided Redis Cluster containers (that is, if you are not externalizing the Redis service, see Externalizing Redis), it is recommended for the host machine to keep the same local IP address. If this is not acceptable for you, be aware that all containers should be restarted after an IP change (see My Kiuwan On-Premises local IP address has changed and Redis is not responding anymore).

Please follow Docker official recommendations when installing Docker. These URLs describe the installation process for different Linux distributions:

These software programs are also needed:

  • Docker CE >= 19.03.2
  • Docker-compose >= 1.24.1
  • Unzip
  • GNU tar
  • Wget
  • BC
  • Tee
  • Ip
  • netstat
  • Java Runtime Environment >= 8 (needed to generate keystores for custom hosts).
  • OpenSSL >= 1.1.1 (needed to generate certificates for custom hosts). Other supported versions of OpenSSL are 1.0.2g and 1.0.2k-fips.

Important: Kiuwan On-Premise does not install on Ubuntu 24.04. Work is underway to support this Ubuntu version.

Important recommendations to consider:

  • Make sure that the docker-compose command can be executed with sudo. This means that the docker-compose binary file must be included in the sudoers path. The binary is usually installed under the /usr/local/bin directory. Depending on your OS, this information may be set in the secure_path variable in the sudoers file (/etc/sudoers).
  • To download and install Docker Compose:
curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname  -s)-$(uname -m)" -o /usr/local/bin/docker-compose

chmod +x /usr/local/bin/docker-compose

Please check the official Docker-compose documentation for more information: https://docs.docker.com/compose/install.

It is also recommended to use the target installation hosts exclusively for Kiuwan services. If you plan on running other containers than Kiuwan's in a single-host installation, please make sure that:

  • None of them is using the following network: 172.172.0.0/16
  • There are no containers that may block any of these ports:
    • 443: standard HTTPS port (or the one you will configure to access your Kiuwan On-Premises installation).
    • 8143, 8243, 8343, 8443, 8543, 8643, 8743, 8843: ports that Kiuwan front instances listen to (or those you may configure for Kiuwan front instances).
    • 6379: port that Redis instances listen to.
    • 3306: port that MySQL instance listens to (or the port you configure for MySQL).
The Kiuwan On-Premises installation tool will check most of these requisites before installing. If any of them is not met, the installation will be canceled.
 

Special requirements for RedHat, CentOS, and Fedora

If your Docker server is running on RedHat, CentOS, or Fedora, be sure the filesystem where Docker is installed supports d_type (the directory entry data structure that describes the information of a directory on the filesystem).

Some of the above operating systems are not configured with d_type support (see http://www.pimwiddershoven.nl/entry/docker-on-centos-7-machine-with-xfs-filesystem-can-cause-trouble-when-d-type-is-not-supported.

Running on XFS without d_type support causes Docker to skip the attempt to use the overlay or overlay2 driver. See https://docs.docker.com/storage/storagedriver/overlayfs-driver/#prerequisites.

You can check if your existing XFS filesystem has d_type enabled by running the following commands:

$ docker info | grep "Supports d_type:"
Supports d_type: true


$ xfs_info /docker-mount-point | grep ftype
naming =version 2         bsize=4096      ascii-ci=0     ftype=

In case you get d_type: false or ftype=0, you will need to create a new XFS filesystem with d_type support enabled. Unfortunately, it isn't possible to enable d_type support on an existing filesystem.

The Kiuwan On-Premises installation tool will check if d_type is enabled on XFS filesystems and stop the installation if it is not.

There are two options:

  • Add a new disk and create a new XFS partition on it.
  • Backup your existing data and recreate the XFS filesystem with d_type support enabled.

You can create a new XFS filesystem with d_type enabled by running the following command:

$ mkfs.xfs -n ftype=1 /mount-point

Needed internet connections

Please make sure your host machines have a connection to these servers when installing Kiuwan On-Premises:

Host Needed when Purpose

*.docker.com (all subdomains of docker.com, including nested subdomains)

*.docker.io (all subdomains of docker.io)

 Installing These are the Docker servers where the needed images will be pulled from.
cdn.mysql.com Installing Download the mysql driver file needed during the installation process.
static.kiuwan.com Installing This is Kiuwan's static content server, needed by the installer to download needed resources.
api.kiuwan.com You own a Kiuwan On-Premises Insights license, both for installing and running This is Kiuwan's central API endpoint, which needed to update the Insights vulnerabilities database.

Proxy configuration

If the host on which you are installing Kiuwan On-Premises needs to access the internet through a proxy server, note that:

  • Your OS should know about your proxy settings to be able to download the Kiuwan On-Premises installer distribution.
  • Docker daemon must know about your proxy settings to download images from https://*.docker.com or https://*.docker.io
  • Docker must know about your proxy settings to propagate them to the created containers.
  • Direct access to your SMPT mail server is needed (it is MANDATORY that the host machine can access your mail server, regardless of the proxy server).

To instruct your OS to use your proxy settings, please refer to the official documentation for your Linux distribution.

To make Docker daemon use your proxy server, please follow the official Docker documentation on how to set a proxy:

https://docs.docker.com/config/daemon/systemd/#httphttps-proxy

To make Docker use your proxy when creating containers, please follow the official Docker documentation on how to set a proxy to be used by the containers:

https://docs.docker.com/network/proxy/#configure-the-docker-client

Remember to restart both Docker daemon and Docker to apply proxy configuration changes:

sudo systemctl daemon-reload
sudo systemctl restart docker

You can check if Docker has successfully read your configuration by executing:

docker system info

Check if your proxy configuration is shown in the console:

[...]
HTTP Proxy: http://proxy.domain.com:3456

HTTPS Proxy: http://proxy.domain.com:3456

No Proxy: localhost,127.0.0.1,172.172.0.0/16
[...]

Examples

This is an example of a /etc/systemd/system/docker.service.d/http-proxy.conf file that makes the Docker daemon use a proxy:

[Service]
Environment="HTTP_PROXY=http://user:password@proxy.domain.com:3456"
Environment="HTTPS_PROXY=http://user:password@proxy.domain.com:3456"
Environment="NO_PROXY=localhost,127.0.0.1,172.172.0.0/16"

This is an example of a ~/.docker/config.json that makes Docker propagate proxy configuration to the created containers:

{
"proxies": {
"default": {
"httpProxy": "http://user:password@proxy.domain.com:3456",
"httpsProxy": "http://user:password@proxy.domain.com:3456",
"noProxy": "localhost,127.0.0.1,172.172.0.0/16"
}
}
}

CPU and memory minimum requirements

The following table shows the minimum requirements for each service. Note that these are only minimum requirements. You should make sure to give each service enough resources, depending on your system demands.

Service Memory CPU cores
wildflykiuwan-f[n] 2.5GB 2 cores
wildflykiuwan-a[n] 2.5GB per analysis slot 2 cores per analysis slot
wildflykiuwan-s[n] 2.5GB 2 cores
mysql 5GB 4 cores
loadbalancer 1GB 1 core
redis_0000[n] 2GB 2 cores

CPU clock speed and disk speed will affect the overall response time. 

With the above configuration, a system with the following load should give continuous service without problems:

  • Parallel processing of 2 analyses (any additional parallel analysis request will be enqueued, and it will be executed as soon as any of the running analyses finish)
  • 50 concurrent web users or REST API calls.

Given the table above, for a single-host installation where no service is externalized, the minimum system requirements are:

  • 18GB of RAM and a processor with 8 cores for Kiuwan On-Premises.

It is recommended that you overscale these characteristics for the OS to have resources available for itself.
 

The Kiuwan On-Premises installation tool (kiuwan-cluster)

The Kiuwan On-Premises installation process is carried out by our "kiuwan-cluster" tool.

The tool is provided as a tar.gz file. The following table summarizes the resources you will find once the tool distribution is extracted:

Resource Purpose
/config/volumes.properties Configuration file to set where your persistent volumes will reside.
/docker/compose Docker compose files used to manage Kiuwan On-Premises' docker services.
/docker/*.sh Advanced shell scripts to interact with your Kiuwan On-Premises installation.
/logs The folder where the tool will write installation logs.
/ssl Tools that ease the certificate creation to keep Kiuwan On-Premises under a secure environment.
/support Tools to ease collecting support data.
/tools Internal tools used when installing.
/user-content The folder where you will have to put some resources the installation process will need.
/volumes The base persistent volumes (that may be copied to different locations depending on your installation needs).
*.sh Main shell scripts to interact with your Kiuwan On-Premise installation.
/config/volumes.properties Configuration file to set where your persistent volumes will reside.
/docker/compose Docker compose files used to manage Kiuwan On-Premises' docker services.
/docker/*.sh Advanced shell scripts to interact with your Kiuwan On-Premises installation.
/logs The folder where the tool will write installation logs.
/ssl Tools that ease the certificate creation to keep Kiuwan On-Premises under a secure environment.
/support Tools to ease collecting support data.
/tools Internal tools used when installing.
/user-content The folder where you will have to put some resources the installation process will need.
/volumes The base persistent volumes (that may be copied to different locations depending on your installation needs).
*.sh Main shell scripts to interact with your Kiuwan On-Premise installation.

The following sections will guide you through the installation process.

 

Related to

Was this article helpful?
Powered by Zendesk