...

These softwares are also needed:

...

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).

Info

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

...

These software are also needed:

Docker CE >= 19.03.2
Docker-compose >= 1.24.1
Unzip
GNU tar
Wget
BC
Tee
Ip
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.

Warning

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). 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

...

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 listen to (or the port you configure for MySQL).

Info
The Kiuwan On-Premises installation tool will check most of these requisites before installing. If any of them is not met, 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:

Code Block

language	bash

$ 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=1

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.

Info
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:

Code Block

language	bash

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

Needed internet connections

Please make sure your host machines have connection to these servers when installing Kiuwan

...

On-Premises Insights license, both for installing and running

This is Kiuwan's central API endpoint, needed to update 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 in order to be able to download the Kiuwan On-Premises installer distribution.
Docker daemon must know about your proxy settings in order to download images from https://*.docker.com or https://*.docker.io
Docker must know about your proxy settings in order 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:

Code Block

language	bash

sudo systemctl daemon-reload
sudo systemctl restart docker

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

Code Block

language	bash

docker system info

Check if your proxy configuration is shown in the console:

Code Block

language	text

[...]
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:

Code Block

[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:

Code Block

language	js

{
	"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

...

2.5GB	2 cores
mysql	5GB	4 cores
loadbalancer	1GB	1 core
redis_0000[n]	2GB	2 cores

Note: 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 finishes)
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:

...

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 tool). It can be downloaded directly from a terminal like this:

Code Block

language	bash

wget https://static.kiuwan.com/download/onpremise/kiuwan-cluster.tar.gz

This will download the latest available installation tool to the current directory.

Note that, as stated in System requirements, you will need access to static.kiuwan.com in order to download this file. You should also check your proxy configuration if you access the internet over a proxy server.

Step 2: untar kiuwan-cluster

Once downloaded, you should untar the provided gz file:

Code Block

language	bash

tar xvzpf kiuwan-cluster

...

On-Premises needs this exact MySQL driver:

mysql-connector-java-5.1.39-bin.jar

You can download it by executing this command and extracting the jar file included inside the tar:

Code Block

language	bash

wget

...

Untar the downloaded file:

Code Block

language	bash

tar xvzpf mysql-connector-java-5.1.39.tar.gz

Copy the connector jar file to the user content folder:

Code Block

language	bash

cp mysql-connector-java-5.1.39

...

Copy the provided volumes to your desired location:

Code Block

language	bash

sudo cp -rp [INSTALL_DIR]/volumes/config-shared [VOLUMES_DIR]/config-shared
sudo cp -rp [INSTALL_DIR]/volumes/data-shared [VOLUMES_DIR]/data-shared
sudo cp -rp [INSTALL_DIR]/volumes/data-local [VOLUMES_DIR]/data-local

Info
Take note of the locations you choose for each volume. You will need these paths for the next installation step.

Step 6: configure the created volume paths

...

is just a placeholder for the real path you chose.

Note that you will need to create the configured folders by running:

Code Block

language	bash

sudo mkdir [VOLUMES_DIR]

In case you are using different base directories for each volume, you must create all the needed base directories.

Warning
Do NOT use the same folder for different volumes. It is MANDATORY that each volume resides on a separated folder.

Step 6: initialize your volumes

Copy the provided volumes to the configured location by running this script:

Code Block

language	bash

cd [INSTALLER_DIR]
sudo ./deploy-volumes.sh

Step 7: configure your email server

Kiuwan On-Premises needs

...

a working and accessible e-mail server to send notifications.

Edit with your preferred editor the main configuration file, found in your [VOLUMES_DIR]:

Code Block

language	bash

sudo vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

Info
Please note that this is the file located in your [VOLUMES_DIR], not in the [INSTALLER_DIR], which only contains the base volumes.

Edit the following properties under the section named "Kiuwan instances shared configuration":

kiuwan.mail.host: the host of your email server.
kiuwan.mail.port: the port of your email server.
kiuwan.mail.authentication: a flag to indicate if your mail server needs authentication or not.
kiuwan.mail.username: the username to use when authenticating with your email server (only applies if kiuwan.mail.authentication is true).
kiuwan.mail.password: the password to use when authenticating with your email server (only applies if kiuwan.mail.authentication is true).
kiuwan.mail.from: the email account to use as the sender.
kiuwan.mail.secure.layer: the security layer that your mail server uses (ssl, tls or none). Set to none if your mail server uses a plaintext connection.
kiuwan.mail.secure.layer.value: the value to set to the ssl or tls (true or false). Only applies if kiuwan.mail.secure.layer is not none.
kiuwan.default.mail.account: the email account to set to

...

the default Kiuwan user (kiuwanadmin).

Mail server configuration examples

If your mail server uses a plaintext connection without authentication, set these properties values (other mail server properties values will be ignored):

kiuwan.mail.authentication=false
kiuwan.mail.secure.layer=none

If your mail server uses a TLS secure connection but does not need authentication:

kiuwan.mail.authentication=false
kiuwan.mail.secure.layer=tls
kiuwan.mail.secure.layer.value=true

If your mail server uses a SSL secure connection and needs authentication:

kiuwan.mail.authentication=true
kiuwan.mail.username=myuser
kiuwan.mail.password=mypassword
kiuwan.mail.secure.layer=ssl
kiuwan.mail.secure.layer.value=true

If your mail server uses a plaintext connection and needs authentication:

kiuwan.mail.authentication=true
kiuwan.mail.username=myuser
kiuwan.mail.password=mypassword
kiuwan.mail.secure.layer=none

Installation: single-host and minimum configuration

Follow this section if you want to proceed and install Kiuwan

...

INSTALLER_DIR] folder and execute this command:

Code Block

language	bash

sudo ./deploy-user-content.sh

This will copy the user-content files to the configured volumes and set the needed permissions.

Step 2: install Kiuwan

...

INSTALLER_DIR] folder and execute this command:

Code Block

language	bash

sudo ./install.sh

This will:

Check if your host meets the minumum installation requirements.
Download and run the needed Docker images.
Install the database resources for Kiuwan

...

Installation: advanced configuration

All configuration properties you can edit are located in this file located inside your data-shared volume:

[VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

Here is a complete list of the properties you can configure and their meaning (default passwords are omitted):

Property	Default value	Meaning
Access configuration
kiuwan.protocol	https	Kiuwan default access protocol
kiuwan.domain	kiuwan.onpremise.local	Kiuwan default domain
kiuwan.port	443	Kiuwan default access port
Mailing configuration
kiuwan.mail.host		Email server host
kiuwan.mail.port		Email server port
kiuwan.mail.username		Email server username
kiuwan.mail.password		Email server password
kiuwan.mail.from		Email account you want Kiuwan to use when sending emails
kiuwan.default.mail.account		Email account to set to the built-in Kiuwan users
Kiuwan instances shared configuration
timezone	Europe/Madrid	Kiuwan servers timezone
Kiuwan front instances configuration
kiuwan.nodes.front.max.memory	1024m	Max memory to set to front instances
session.timeout	3600	Time a session can be inactive before close it (in seconds)
session.secure	false	Use the secure attribute of the session cookie
session.httponly	false	Use the httponly attribute of the session cookie
Kiuwan analyzer instances configuration
kiuwan.nodes.analyzers.max.memory	1024m	Max memory to set to analyzer instances
queues.reportsGeneratedQueueSize	2	Number of slots enabled for analysis processing
Kiuwan scheduler instances configuration
kiuwan.nodes.schedulers.max.memory	1024m	Max memory to set to front instances
Kiuwan file repositories configuration
centralFileRepository.type	filesystem	Central file repository storage type [filesystem\|s3]
sourceCodeFileRepository.type	filesystem	Source code repository storage type [filesystem\|s3]
Amazon S3 bucket configuration (only applies when using AWS S3 type repositories)
s3.privateBucket.bucketName		S3 bucket name
s3.privateBucket.subDirectoryName		S3 subdirectory name
s3.privateBucket.accessKeyId		Access key id
s3.privateBucket.secretKeyId		Secret key id
s3.dir.centralFileRepository		Central file repository directory
s3.dir.sourceCodeFileRepository		Source code file repository directory
MySQL configuration
mysql.host	mysqlkiuwan	MySQL server host
mysql.port	3306	MySQL server port
mysql.username	csaas	MySQL server username
mysql.password		MySQL server password
mysql.config.useSSL	false	Enable or disable the use of encryption when connecting to MySQL
mysql.config.requireSSL	false	Force the use of encryption when connecting to MySQL
mysql.config.verifyServerCertificate	false	Force the validation of the certificate served MySQL
Redis Cluster cache and store configuration
redis.[cache\|store].nodes	redis_0000[1-6]:6379	Redis nodes hosts (use the provided single host name when using elasticache)
redis.[cache\|store].timeout	2000	Redis connection timeout
redis.[cache\|store].password		Redis password
redis.[cache\|store].clientName		Redis client name
SSL configuration
java.keystore.password		Java keystore password. This must be aligned with the generated keystore password (in case you change the default Kiuwan host name)
java.truststore.password		Java truststore password. This must be aligned with the generated truststore password (in case you change the default Kiuwan host name)

Accessing your Kiuwan on Premises installation

...

Accessing your Kiuwan On-Premises installation

In order to access your Kiuwan On-Premises installation you should follow a few more steps.

Step 1: add your domain to your local network DNS

To access your Kiuwan On-Premises installation you should take into account whether the selected domain is available in the DNSs your local network may use.

In order to access Kiuwan you will need to do one of the following options:

Add kiuwan.onpremise.local to your DNS (recommended option).
Add kiuwan.onpremise.local to your hosts file.

For testing purposes or if you choose the second option, edit this file in the host where you plan to access Kiuwan from:

Windows OS: C:\Windows\System32\drivers\etc\hosts
Linux OS: /etc/hosts

Add the following entry to the previous file:

Code Block
[kiuwan_on_premise_host_ip] [kiuwan_on_premise_host]

For example, the previous entry may look like this for an installation pointing to the default host (note that the IP of the example may change in your local network):

Code Block
192.168.0.56 kiuwan.onpremise.local

Note that although the installation process may have finished, the Kiuwan servers may need some minutes to start up. Please wait if you receive a "404 - Not Found" error message when accessing Kiuwan on Premises.

Step 2: add your certificates' CA to your clients

Depending on whether you are using a trusted CA or not to sign your certificates, you may need to add the CA to your client's certificate store to avoid warning messages.

Please refer to the Adding the provided or a custom CA to Kiuwan On-Premises' clients section for a complete explanation on how to handle this depending on your installation configuration.

Step 3: access Kiuwan On-Premises

Accessing the web application

Once the previous steps have been done, you should be able to access Kiuwan

...

Image Removed

Handling trusted certificates warning messages in your browser and clients

Kiuwan on Premises installer tool provides default certificates for the default host name, signed by a supplied CA (Certificate Authority).

The CA public certificate is provided in this file:

[INSTALL_DIR]/ssl/ca/cacert.pem

In order to make your browser trust the supplied certificates, you will need to add this CA to your browser, and Java clients that access your Kiuwan on premises installation:

Fixefox, Chrome, Edge: import cacert.pem by using the tools provided by the browsers.
Java clients (Kiuwan for developers Eclipse, Kiuwan for developers JetBrains, Jenkins, KLA, etc): add the provided cacert.pem to the JRE keystore used by the client. Please refer to the official documentation of your JRE distribution about the Java keytool program.
Windows clients (Kiuwan for developers VisualStudio): import cacert.pem by using the tools provided by Windows (certmgr.msc).
Multiplatform clients (Kiuwan for developers VisualStudioCode): import cacert.pem by using the tools provided by your OS.

Default users

Code Block

language	text

https://kiuwan.onpremise.local

Note that although the installation process may have finished, the Kiuwan servers may need some minutes to start up. If this is the case, a loading page will be shown (as long as you are using the provided Apache load balancer service):

Image Added

Once Kiuwan On-Premises services are started, you will be redirected to your Kiuwan On-Premises installation's main login page:

Image Added

Downloading Kiuwan Local Analyzer

Once logged into the web application, you can download Kiuwan Local Analyzer by clicking on the "Download Kiuwan Local Analyzer" option in the top right drop-down menu.

Image Added

Consuming Kiuwan REST API

To access your Kiuwan On-Premises installation via its REST API, you should point to this URL:

Code Block

language	text

http(s)://[KIUWAN_DOMAIN]/saas/rest/v1

Please refere to the Kiuwan REST API documentation deployed in your Kiuwan On-Premises server for more details:

Code Block

language	text

http(s)://[KIUWAN_DOMAIN]/pub/doc/rest-api/kiuwan-rest-api.html

You can also access the REST API documentation through the link shown in your Kiuwan On-Premises login page.

Info
There are no quota limits to Kiuwan REST API invocations anymore since Kiuwan On-Premises 2.8.1910.7.

Configuring Kiuwan for Developers

To install the Kiuwan for Developers plugin you should point to the corresponding download endpoint for each Kiuwan for Developers distribution:

IDE distribution	How to install	URL
Eclipse	Add a new updatesite	https://[KIUWAN_DOMAIN]/pub/updatesite
JetBrains	Add a new custom plugin repository	https://[KIUWAN_DOMAIN]/pub/jetbrains/plugins.xml
Visual Studio	Add an extension gallery	https://[KIUWAN_DOMAIN]/pub/vsgallery/atom.xml
Visual Studio Code	Download the extension package file and use the "Install from VSIX" option	https://[KIUWAN_DOMAIN]/pub/vscode/k4d-vscode.vsix

Please refer to the Kiuwan for Developers page for more information.

Default users

Kiuwan On-Premises is provided with two user accounts:

Username	Default password
sysadmin	sysadmin
kiuwanadmin	kiuwanadmin

Please make sure you change these passwords as soon as possible

...

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.

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

Page tree

Page History

Versions Compared

Old Version 34

New Version Current

Key

Introduction

System requirements

Installation requirements

Special requirements for RedHat, CentOS, and Fedora

Needed internet connections

Proxy configuration

Examples

CPU and memory minimum requirements

The Kiuwan

On-Premises installation tool (kiuwan-cluster)

Installation: common steps

Step 1: download kiuwan-cluster

Step 2: untar kiuwan-cluster

Step 3: copy license files

Step 4: download and copy the needed driver version for MySQL

Step 5:

configure the volumes paths

Step 6: configure the created volume paths

Step 6: initialize your volumes

Step 7: configure your email server

Mail server configuration examples

Installation: single-host and minimum configuration

Step 1: deploy user content

Step 2: install Kiuwan

On-Premises

Installation: advanced configuration

Accessing your Kiuwan on Premises installation

Accessing your Kiuwan On-Premises installation

Step 1: add your domain to your local network DNS

Step 2: add your certificates' CA to your clients

Step 3: access Kiuwan On-Premises

Accessing the web application

Handling trusted certificates warning messages in your browser and clients

Default users

Downloading Kiuwan Local Analyzer

Consuming Kiuwan REST API

Configuring Kiuwan for Developers

Default users