The Kiuwan On-Premises installer is a powerful tool that suits multiple environment 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.
It is mandatory for any host where Kiuwan On-Premises is installed to meet these requirements:
These softwares are also needed:
Please follow Docker official recommendations when installing Docker. These URLs describe the installation process for different Linux distributions:
We also recommend using 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 are using the following network: 172.172.0.0/16 |
Please make sure your host machines have connection to these servers when installing Kiuwan On-Premises:
Host | Needed when | Purpose |
---|---|---|
https://hub.docker.com | Installing | This is the main Docker server where the needed images will be pulled from. |
https://static.kiuwan.com | Installing | This is Kiuwan's static content server, needed by the installer to download needed resources. |
https://api.kiuwan.com | You own a Kiuwan On-Premises Insights license, both for installing and running | This is Kiuwan's central API endpoint, needed to update Insights vulnerabilities database. |
If the host on which you are installing Kiuwan On-Premises needs to access the internet through a proxy server, note that:
To instruct your OS to use your proxy settings, please refer to the official documentation of 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 [...] |
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://proxy.domain.com:3456" Environment="HTTPS_PROXY=http://proxy.domain.com:3456" Environment="NO_PROXY=localhost,127.0.0.1" |
This is an example of a ~/.docker/config.json that makes Docker propagate proxy configuration to the created containers:
{ "proxies": { "default": { "httpProxy": "http://proxy.domain.com:3456", "httpsProxy": "http://proxy.domain.com:3456", "noProxy": "localhost,127.0.0.1" } } } |
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 |
---|---|---|
wildfly-f[n] | 3GB | 2 cores |
wildfly-a[n] | 3GB per analysis slot | 2 cores per analysis slot |
wildfly-s[n] | 3GB | 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:
Given the table above, for a single-host installation where no service is externalized the minimum system requirements are:
It is recommended that you overscale these characteristics for the OS to have resources available for itself.
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/*.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. |
/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.
This guide will reference two important folders:
Sometimes these folders will be referenced inside command line examples. Please make sure you replace any of them with the needed real path.
Note that it is up to you where these folders will be located.
The first step is to download kiuwan-cluster (the Kiuwan On-Premises installation tool). It can be downloaded directly from a terminal like this:
wget https://static.kiuwan.com/download/onpremise/kiuwan-cluster.tar.gz |
This will download the latest available installation tool to the current directory.
Once downloaded, you should untar the provided gz file:
tar xvzpf kiuwan-cluster.tar.gz |
This will untar the installation tool to a folder with extended version information of the tool. For example:
/home/user/kiuwan-cluster_master.XXXX-2.8.YYMM.V
This folder will be referred to as [INSTALL_DIR] throughout this guide.
In order to be able to start a Kiuwan On-Premises installation, you will need two license files:
Copy these files to the user-content folder of your installation tool directory (please replace [INSTALL_DIR] with the real location of your installation directory):
cp configq1.zip [INSTALL_DIR]/user-content cp license.zip [INSTALL_DIR]/user-content |
Kiuwan 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:
wget http://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.39.tar.gz |
Untar the downloaded file:
tar xvzpf mysql-connector-java-5.1.39.tar.gz |
Copy the connector jar file to the user content folder:
cp mysql-connector-java-5.1.39/mysql-connector-java-5.1.39-bin.jar [INSTALL_DIR]/user-content |
The installation tool comes with the base volumes to boot a first installation of Kiuwan On-Premises. We provide three volumes:
Copy the provided volumes to your desired location:
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 |
Take note of the locations you choose for each volume. You will need these paths for the next installation step. |
Edit the file located in [INSTALL_DIR]/config/volumes.properties and set the previous paths to each property:
config.shared=[VOLUMES_DIR]/config-shared data.shared=[VOLUMES_DIR]/data-shared data.local=[VOLUMES_DIR]/data-local |
Please remember that [VOLUMES_DIR] is just a placeholder for the real path you chose.
KoP 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]:
sudo vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties |
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.username: the username to use when authenticating with your email server.
kiuwan.mail.password: the password to use when authenticating with your email server.
kiuwan.mail.from: the email account to use as the sender.
Follow this section if you want to proceed and install Kiuwan On-Premises with no further customization.
The defaults will install Kiuwan On-Premises with these characteristics:
If this is enough for you, just continue with the following steps.
If you plan to change the default domain, please refer to the Modifying the default domain section before continuing and come back here after you have made the needed changes.
On a terminal, navigate to the [INSTALL_DIR] folder and execute this command:
sudo ./deploy-user-content.sh |
This will copy the user-content files to the configured volumes and set the needed permissions.
On a terminal, navigate to the [INSTALL_DIR] folder and execute this command:
sudo ./install.sh |
This will:
Once the installation is finisished please refer to the Accessing your Kiuwan On-Premises installation section.
The default configuration sets "kiuwan.onpremise.local" as the default domain to access Kiuwan On-Premises.
We encourage to change the default domain, but take into account that this means updating the provided certificates to keep your installation connections secure.
Using your preferred editor, edit the default configuration file located in your config-shared volume:
sudo vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties |
Edit these properties (kiuwan.port is only needed if you want to use https under a different port than the default 443):
Once you have selected your new domain and if you are using the provided Apache load balancer, you should edit the main Apache configuration file:
sudo vim [VOLUMES_DIR]/config-shared/ApacheLoadBalancer/conf/httpd.conf |
Edit this line and change the default domain (kiuwan.onpremise.local) to your new domain:
Define kiuwanDomain kiuwan.onpremise.local |
If you have externalized the provided Apache load balancer, you should edit the equivalent configuration file to set the new domain.
Please refer to the Managing certificates guide and follow the needed steps depending on your needs.
Once this is done, you should have these files under the [INSTALL_DIR]/user-content/certs folder:
If you are performing a new Kiuwan On-Premises installation, please refer to the steps indicated in the following sections, depending on your installation needs:
If you have already installed Kiuwan On-Premises, you will need to stop your containers, update the deployed configuration and restart them. To do so, execute these commands:
cd [INSTALL_DIR]/docker sudo ./stop-kiuwan.sh sudo ./stop-infrastructure.sh sudo ./update.sh sudo ./start-infrastructure.sh sudo ./start-kiuwan.sh |
If you are modifying an existing Kiuwan On-Premises installation, you will need to update your DNS or hosts files.
Note that if you have generated new certificates signed by a different CA than the one that signed the previous ones, you should update your Kiuwan On-Premises clients certificates or truststores.
Please refer to Accessing your Kiuwan On-Premises installation for details on these topics.
Kiuwan On-Premises uses three main services under its infrastructure's hood:
If you want to use your own services for any of the previous ones, Kiuwan On-Premises can connect to them by bypassing their creation at installation time.
First of all, you will need to edit the main configuration file and mark which services you want to externalize:
This table shows the properties you should modify when externalizing each service:
Service | Property | Default value |
---|---|---|
Apache | kiuwan.externalize.apacheloadbalancer | false |
Redis | kiuwan.externalize.redis.[cache|storage] | false |
MySQL | kiuwan.externalize.mysql | false |
When setting to "true" any of the previous properties, the corresponding service will be externalized and the installation tool will not manage any related instance. Note that all the configuration will be up to you, as the Kiuwan On-Premise installer will only be able to configure how Kiuwan On-Premise will connect to your own services.
When externalizing this service you should take into account that:
In case you set Redis as an external service, Kiuwan On-Premises needs to know where the Redis nodes are deployed and which ports to use when connecting to them.
In case you use a special DNS that can resolve the same host to different hosts and ports (DNS Round-Robin or equivalent), you should configure just an single host.
All the needed configuration is located in the main configuration file:
The following table shows the properties to configure (note that you should set exactly the same configuration for both "cache" and "store" Redis configurations):
Property | Meaning | Example |
---|---|---|
redis.[cache|store].nodes | Comma separated list of host and port for each Redis node | rn1.mydomain.com:6379,rn2.mydomain.com:6379,rn3.mydomain.com:6379,rn4.mydomain.com:6379,rn5.mydomain.com:6379,rn6.mydomain.com:6379 |
redis.[cache|store].timeout | Connection timeout in milliseconds | 2000 |
redis.[cache|store].password | Password to use when connecting to a node (leave empty if you have set no password access) | |
redis.[cache|store].clientName | Name of the client connection (defaults to empty) |
It is mandatory for Kiuwan On-Premises to work with your Redis installation that it complies with these characteristics:
When externalizing MySQL note that your MySQL installation should comply with these characteristics:
You should create the needed schemas in your MySQL installation. To do so, please execute this script with a user that has schema creation privileges:
create database opt_activity CHARACTER SET utf8 COLLATE utf8_unicode_ci; create database opt_cinc CHARACTER SET utf8 COLLATE utf8_unicode_ci; create database opt_metamodel CHARACTER SET utf8 COLLATE utf8_unicode_ci; create database opt_qmm CHARACTER SET utf8 COLLATE utf8_unicode_ci; create database opt_transaction CHARACTER SET utf8 COLLATE utf8_unicode_ci; create database opt_insight CHARACTER SET utf8 COLLATE utf8_unicode_ci; |
You should create the user that will be connecting to Kiuwan On-Premises schemas. Please run this script as an admin user to do so:
create user '[USER]'@'%' identified by '[PASSWORD]'; grant all privileges on `opt_%`.* to '[USER]'@'%' identified by '[PASSWORD]'; flush privileges; |
Note that you should replace [USER] with the desired user name and [PASSWORD] with the desired password.
The following table shows the properties to configure for Kiuwan On-Premises to connect to your own MySQL instance:
Property | Meaning | Example |
---|---|---|
mysql.host | Your MySQL installation host | mysqlkiuwan |
mysql.port | The connection port to access your MySQL installation | 3306 |
mysql.username | The user that will be connecting to Kiuwan On-Premises schemas (should match the one provided in the previous step) | csaas |
mysql.password | The user's password (should match the one provided in the previous step) |
Kiuwan On-Premises uses these shared file repositories to store analysis related data:
These two Kiuwan On-Premises internal file repositories can be replaced with Amazon S3 buckets.
To do so, you should first configure these properties in the main configuration file ([VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties):
The following table shows the properties you should modify when making Kiuwan On-Premises connect to AWS S3 buckets:
Property | Meaning | Example |
---|---|---|
s3.privateBucket.bucketName | Your AWS S3 bucket name | s3mycompany-us |
s3.privateBucket.subDirectoryName | Your AWS S3 subdirectory name under the configured bucket | mydirectory |
s3.privateBucket.accessKeyId | AWS access key for your bucket | BS3BX35Z27UAQCEACTPQ |
s3.privateBucket.secretKeyId | AWS secret key for your bucket | Aasdfjklwe1234123lkjfasc21ssACasfEq124Da |
s3.dir.centralFileRepository | The main key prefix that will be used to keep the central file repository entries | kiuwanCentralWorkingDirectory/analysisData |
s3.dir.sourceCodeFileRepository | The main key prefix that will be used to keep the source code file repository entries | kiuwanCentralWorkingDirectory/analyzedSourceCode |
All configuration properties you can edit are located in this file located inside your data-shared volume:
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. Please refer to Supported timezones page for a complete list of supported time zones. |
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) |
In order to access your Kiuwan On-Premises installation you should follow a few more steps.
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:
For testing purposes or if you choose the second option, edit this file in the host where you plan to access Kiuwan from:
Add the following entry to the previous file:
[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):
192.168.0.56 kiuwan.onpremise.local |
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.
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.
Once the previous steps have been done, you should be able to access Kiuwan On-Premises entering your Kiuwan host in your browser which by default is:
https://kiuwan.onpremise.local |
You will access you Kiuwan On-Premises installation's main login page:
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.
To access your Kiuwan On-Premises installation via its REST API, you should point to this URL:
https://[KIUWAN_DOMAIN]/saas/rest/v1 |
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.
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, by selecting the option "Account management" from the menu in the upper right corner and selecting "Change Password".