On-Prem Single-Node Installation Guide

This guide describes how to deploy a complete single-node on-premises instance with all platform services on one machine. Single-node installations are suitable for testing, proof-of-concept, and small-scale environments.

The single-node installation steps for v3.5.1 are identical to v3.5.0. If you have previously installed v3.5.0 using this guide, the same steps apply for v3.5.1 with the v3.5.1 installer package.

Overview

The single-node installation sets up all components on a single machine. This is recommended for:

• Small deployments with limited data volume

• Testing environments

• Proof-of-concept

The following services are installed and run on single node:

Prerequisites

Operating System Requirements

The following Linux operating systems are supported:

• Officially supported: Red Hat Enterprise Linux 9+

• Compatible (expected to work): CentOS 9+, Alma Linux 9+

System requirements:

Ports:

The following defaults ports are used internally by various components. All ports are configurable.

Note: Firewall rules must allow ingress traffic.

Certificate Requirements

The platform uses mutual TLS (mTLS) for secure authenticated communication between all services and server components.

All required certificates can be generated and self-signed or you can provide your own certificates. See Certificates Management Guide for detailed information and instructions on various options for certificates.

generate_cert.sh generates the following certificates:

Recommendation: run generate_cert.sh to see list of files and locations.

Domain Name Requirements

A single external FQDN for the platform is required. The following format is recommended:

agilesec.<external domain>

For example: agilesec.dilithiumbank.com

Installation Steps

The installation can be performed in two modes: Interactive (default) or Non-Interactive (for automated/CI-CD deployments).

In this version, install_analytics.sh introduces the install sub-command for performing fresh installations:

./install_analytics.sh install [OPTIONS]

For backward compatibility, running ./install_analytics.sh [OPTIONS] without the install sub-command continues to work as in previous versions. To see all available install options, run ./install_analytics.sh install --help.

Non-Interactive Mode

All key installation scripts support an optional --non-interactive (or -n) flag to skip confirmation prompts, enabling fully automated deployments.

Pre-requisites for Non-Interactive Install

The install_analytics.sh script reads the admin password from a .pass file when running in non-interactive mode. To set this up:

1. Copy the example file: cp .pass.example .pass

2. Edit .pass and set admin_password

3. Set secure permissions: chmod 600 .pass

Step 1: Prepare the Environment

Ensure you have the installer package and your node meet the minimum memory and CPU requirements.

1. Download the installation zip archive from the Keyfactor download portal.

2. Extract the zip archive to your preferred install location, i.e. a agilesec-analytics folder.

unzip -d <installer_directory> <installer_package>.zip
cd <installer_directory>

3. Ensure the installation script is executable:

cd <installer_directory>
chmod +x install_analytics.sh

4. Environment configuration is required before starting the installation. A sample configuration file for a single-node installation is available at generate_envs/single_node_config.conf. You can use the default values for all settings. However, it is recommended to review and update the following settings for single-node installations:

[Optional] Using Port 443 (HTTPS Standard Port)

To run the platform on the standard HTTPS port (443) instead of the default 8443, set analytics_port=443 in generate_envs/single_node_config.conf before running generate_envs.sh. Then proceed with the normal installation steps.

When using port 443, be aware of the following post-install behavior:

• Since port 443 is a privileged port (< 1024), HAProxy requires root privileges to bind to it.

• ./manage.sh start as a regular user will start all services except HAProxy.

• HAProxy must be started or restarted with sudo:

BASH

sudo ./manage.sh start haproxy

• However, stopping HAProxy does not require sudo:

BASH

./manage.sh stop haproxy

• The platform URL simplifies to https://<analytics_hostname>.<analytics_domain> (no port number needed, since 443 is the default HTTPS port).

5. Generate config file for single-node installation.

./generate_envs/generate_envs.sh -t single-node

Tip: Add --non-interactive to skip overwrite prompts.

generate_envs.sh will copy env.single_node file to <installation_directory>/.env

6. Generate certificates

You can generate and self-sign all required certificates using <installer_directory>/certificates/generate_certs.sh. Alternately, you can use certificates issued by your own CA. For POCs and first-time installations, it is recommended you generate all certificates using generate_certs.sh.

Run the following command to generate and self-sign all required certificates. The .env file is required to generate certificates. By default, the script looks for the .env file under <installation directory>.

This command will populate the required certificate files under the certificates directory:

cd certificates/
./generate_certs.sh

Tip: Add --non-interactive (or -n) to skip overwrite prompts. See On-Prem Single-Node Installation Guide.

[Optional] Using your own certificates

If you are using your own certificates, perform following steps:

• Copy your CA cert chain to <installation_directory>/certificates/ca

• Copy server and client certificates to <installation_directory>/certificates/<analytics_internal_domain> .

• Certificate filenames must match those listed under On-Prem Single-Node Installation Guide.

Step 2: Install the Platform

1. Ensure you have either a DNS entry for <analytics_hostname>.<external domain> (recommended) pointing to your node's IP address or an entry in your /etc/hosts for <analytics_hostname>.<external domain> pointing to your node's IP address.

2. Make sure settings file <installer_directory>/.env is present.

3. Run sudo ./scripts/tune.sh -u <username> to update the following:

   1. System settings for Sysctl settings. Recommended values are:

      1. vm.max_map_count = 262144

      2. fs.file-max = 65536

   2. Security settings in /etc/security/limits.conf for file descriptors and number of threads. These settings are needed by OpenSearch:

      1. <non-root-user> - nofile 65536

      2. <non-root-user> - nproc 65536

      3. <non-root-user> soft memlock unlimited

      4. <non-root-user> hard memlock unlimited

   3. /etc/hosts entries:

      1. <private ip> <node 1 hostname>.<analytics_internal_domain>

      2. Note: Only entries for internal nodes are added to /etc/hosts.

   4. Install git binary

Alternately, you can perform the above steps manually

4. (Recommended) Prepare the .pass file to avoid typing the admin password on the console:

cp .pass.example .pass
# Edit .pass and set admin_password
chmod 600 .pass

Using the .pass file prevents typos that can occur when entering the password interactively (the password is not echoed back on the console).

5. Run the installation:

cd <installer_directory>
./install_analytics.sh install -u <user> -p <installation-dir> --non-interactive

Or to run interactively (will prompt for admin password on console):

./install_analytics.sh install -u <user> -p <installation-dir>

Note 1: The previous functionality of using ./install_analytics.sh -u <user> -p <installation-dir> without the install sub-command is still supported.

Note 2: <installation-dir> is a new, separate directory where the installed files will reside.

To see additional install options, run ./install_analytics.sh install --help.

Example: End-to-End Non-Interactive Single-Node Install

cd <installer_directory>

# Generate env config
./generate_envs/generate_envs.sh -t single-node --non-interactive

# Generate certificates
cd certificates/
./generate_certs.sh --non-interactive
cd ..

# Prepare .pass file
cp .pass.example .pass
# Edit .pass and set admin_password
chmod 600 .pass

# Run system tuning
sudo ./scripts/tune.sh -u <user>

# Install
./install_analytics.sh install -u <user> -p <installation-dir> --non-interactive -v

Post-Installation Verification

Verify Service Health

Run ./scripts/manage.sh status to check the status of all services. If any service shows Not running, try restarting it. See Managing Services for instructions on starting and restarting services.

You should see following services in Running status:

$ ./scripts/manage.sh status
SERVICE                   DESCRIPTION                              STATUS              
------------------------  ---------------------------------------- --------------------
opensearch                OpenSearch Search Engine                 Running (PID: 1450891)
opensearch-dashboards     OpenSearch Dashboards                    Running (PID: 1452817)
indexing                  Indexing Microservice                    Running (PID: 1451400)
haproxy                   HAProxy Load Balancer                    Running (PID: 1451285)
mongodb                   MongoDB Server                           Running (PID: 1451281)
kafka                     Kafka Server                             Running (PID: 1451295)
webui                     Web UI Microservice                      Running (PID: 1451316)
api                       Web API Microservice                     Running (PID: 1452924)
cbom                      CBOM Exporter Microservice               Running (PID: 1453074)
sm                        Security Manager Microservice            Running (PID: 1453083)
analytics-manager         Analytics Manager Microservice           Running (PID: 1451408)
ingestion                 Ingestion Microservice                   Running (PID: 1451419)
scheduler                 Scheduler Microservice                   Running (PID: 1451450)

After installation completes, allow approximately 30 seconds for all services to fully initialize before accessing the UI. Attempting to log in immediately may result in a 503 Service Unavailable error. If this occurs, wait 30 seconds and refresh the page.

Access the Platform UI

To log into the new Web UI, use the URL displayed at the end of the install.

• Login URL: https://<analytics_hostname>.<analytics_domain>:<analytics_port>

• Username: admin@<analytics_domain>

• Password:

For example, using the default settings:

• Login URL: https://analytics.kf-agilesec.com:8443

• Username: admin@kf-agilesec.com

• Password: HelloWorld123456!

You will see a login screen like this:

After logging in, the Overview Dashboard should show 0 across all charts, as shown in the screenshot below:

Run a Smoke Test

Follow these steps to run a quick smoke test and confirm the platform is working:

Step 1: In the Web UI, go to Sensors -> Network Scan.

Step 2: On the network scan page, enter an HTTPS URL to scan (for example: https://www.google.com), then click Scan to start the scan.

Step 3: While the scan is running, you will see a progress screen similar to the following:

Step 4: Once the scan successfully completes, you will see a Network scanned successfully message and the Scan Information tab will contain information about the scan:

Step 5: At this point, the scan has completed and the pipeline is waiting for the policy execution to finish. Policy execution can take up to 45 seconds. Until policies run, all findings will show a Pending status under the Findings tab:

Step 6: Once policies have run, the Score column show a risk score instead of Pending, as shown in the screenshot below:

Step 7: Shortly after policies run successfully, a backend process performs additional analysis on the findings. Once this process completes, you will see Successful statuses as shown in the screenshot below. This confirms the platform is working as expected.

Managing Services

After installation, you can manage services using the unified service manager script at ./scripts/manage.sh.

The manage.sh script provides a centralized way to manage all platform services:

cd /scripts ./manage.sh [action] [options] [services...]

Actions

Options

Available Services

If no specific services are specified, the action will be applied to all installed services.

Usage Examples

• To start all services:

./manage.sh start

• To start only OpenSearch with debug output:

./manage.sh start -d opensearch

• To start multiple specific services:

./manage.sh start opensearch opensearch-dashboards

The script automatically resolves dependencies, starting OpenSearch first (as it's a dependency for other services) before starting any dependent services.

• To stop all services:

# Stop all installed services
./manage.sh stop

• To stop only specific services:

./manage.sh stop haproxy indexing

The script stops services in reverse dependency order to ensure a clean shutdown.

• To Restart all installed services:

# Restart all installed services
./manage.sh restart

• To restart only OpenSearch:

./manage.sh restart opensearch

• To reload configuration:

./manage.sh reload haproxy

• To list status of all services:

./manage.sh status

• To check status of specific services:

./manage.sh status opensearch indexing

• To list all available services:

./manage.sh list

Note: If HAProxy is configured to use a privileged port (< 1000), you will need root privileges to start or stop it. The script will display the appropriate command to run with sudo.

Post Installation Configuration

SAML Setup

For detailed instructions on various SSO integration options see Authentication and Access Control documentation.

Only users with the Platform Admin privilege role for the organization can edit the SAML 2.0 configuration. To access the SAML setup page, do the following:

Step 1: Go to Settings -> Authentication Options.

Step 2: Turn on SAML 2.0 Single Sign-On

Step 3: Open Settings for SAML 2.0 Configuration, then configure the SAML settings for your environment. Details for each configurable option are provided in the Configuration Options table below.

Configuration Options

Service Provider Information

Authorization Settings

Note: Only SHA256 signing algorithm is supported for now.

Identity Provider Configuration

Note: It is Required to select one of the Identity Provider Configuration options.

Custom Attribute Configuration

Role Mapping Configuration

Troubleshooting

If you encounter issues during installation or operation:

Installation Issues

• Check the console output for specific error messages.

• Verify all prerequisites are met.

• Ensure all certificate files are correctly placed and have proper permissions and filename.

• Check the .env file to make sure following are correct:

  • private_ip

  • analytics_hostname

  • analytics_domain

  • analytics_port

  • cluster_frontend_node_ips

  • cluster_backend_node_ips

• Make sure the analytics FQDN <analytics_hostname>.<analytics_domain> is reachable on <analytics_port>.

Service Issues

• Check service logs in the <installation_path>/logs directory.

• Verify port availability using netstat or ss commands.

• Ensure proper certificate permissions and ownership.

• Check disk space with df -h.

• Verify memory availability with free -h.

Common Errors

• Certificate Issues: Ensure all certificate DNs and CNs match specs from certificates requirements section.

• Port Conflicts: Verify no other services are using the required ports.

• Permission Denied: Check file and directory permissions.

• Memory Errors: Verify you have sufficient memory available (minimum 8GB recommended).