How to install and configure ?

Please watch demo video<< coming soon>> (For Installation and Configuration) or follow below instructions

Main Server Installation and Configuration

This section describes how to install and configure the KloudDB Shield Main Server. The Main Server acts as the central management and monitoring node. Collector Agents installed on PostgreSQL servers will communicate with this server.

Architecture Overview

The deployment consists of:

Main Server – Centralized management server where the main package is installed. Collector Agents – Lightweight agents installed on each PostgreSQL server. PostgreSQL Servers – Database servers monitored and managed through the collector agents.

Main Server Installation and Configuration

Step 1: Install the Main Server Package

Install the appropriate package for your operating system.

Ubuntu 
sudo dpkg -i main-server_2.4_linux_amd64.deb

Verify that the installation completed successfully before proceeding to the configuration steps.

Step 2: Configure the Main Server

After installation, edit the configuration file:

sudo vi /etc/klouddbshield/server-node.yaml

Generate unique values for the following fields:

id - Unique identifier for the server node.
cluster_id - Unique identifier for the server node.
token - Unique token used for collector communication (has to match with the one present in collector config)
role - Server role. For the main server, use postgres.

These values should be random and sufficiently long to ensure uniqueness and security.

Sample config file :

id: 3337e121-1dc8-4b3b-a94f-843f426f5179
cluster_id: c7fb778c-d5a8-44af-9190-2a6ced9f727a
cluster_name: prod-cluster
url: http://103.xx.xx.xx:8081
token: f89909507d587b9e24ab4de2413686e417fb973bbea9e59a1f95428257bb5b19
hostname: bastion
ip: 103.xx.xx.xx
environment: dev
role: postgres

After updating the configuration file, start the service:

sudo systemctl start klouddbshield-server.service

Enable automatic startup during system boot:

sudo systemctl enable klouddbshield-server.service

Verify service status:

sudo systemctl status klouddbshield-server.service

Step 3: Validate Connectivity

Confirm that the Main Server is listening on the configured port:

ss -tulpn | grep 8081  or netstat -tulpn | grep 8081

Expected result:

LISTEN 0 128 0.0.0.0:8081

Collector Configuration ( On each Postgres Server repeat below steps )

1. Install the appropriate package for your operating system

ubuntu
 ciscollector_2.4_linux_amd64.deb

1. Configuration

You need to configure /etc/klouddbshield/kshieldconfig.toml as described below

# [postgres]
# host = "localhost"  -- > ip of server
# port = "5432"       -- > postgres port
# user = "postgres"    --> user credentials - give superuser or other required privs for this user (some of the modules like hbascanner etc.. need elevated access)
# password = "password123"
# dbname = "mydb"
# maxIdleConn = 10
# maxOpenConn = 100



# [collector]
# schedule = "0 12 * * *" --> this is the schedule for runs - Typically a weekend run is good enough for these scans - Some scans like logparser ,piiscanner can be slow and time taking 
depending on the amount of logs ,  database size etc.. 

   Example for weekly run is schedule = "0 2 * * 6" (Every Saturday at 2 AM)
   
# scan_commands = "all"  # CIS + HBA + SSL + password leak + log parser + PII (uses [piiscanner]) -->Use "all" to enable all features(recommended) .. You also need to enable collector.logparser and piiscanner blocks below 


# [collector.logparser] --> make sure you enable all of below parameters for log parser module 

# NOTE - Please ensure that  log_connections=on and prefix at a minimum includes %m [%p]: [%l-1] db=%d,user=%u,app=%a,client=%h

# prefix = "%m [%p]: [%l-1] db=%d,user=%u,app=%a,client=%h "
# logfile = "/var/log/postgresql/*.log"
# hbaconffile = "/etc/postgresql/pg_hba.conf"




# [piiscanner] --> enable for pii scans
# run_option = "datascan" --> The other option is MetaScan, but the recommendation is to enable DataScan. We also support Spacy Scan—please refer to the additional documentation for more details on Spacy Scan
# database = "mydb"
# schema = "public"
# exclude_tables = ""
# include_tables = ""


# [app]
# hostname = "postgreshost1"  --> Collector node name: This is the label assigned to the host and will be displayed on the main dashboard
# debug = true



# [mainserver]
# enabled = true
# url = "https://shield.example.com:8081"  --> This is the web server (dashboard server URL- same one you gave in main server config)
# token = "your-shared-secret"  --> NOTE - This has to match with the token you created on main server 
# push_interval = "30s"
# offline_threshold_sec = 90
# tls_ca_file = "/etc/klouddbshield/certs/ca.crt" --> Optional - Please see instructions in guide 

1. Start the collector service

sudo systemctl enable ciscollector.service
sudo systemctl start ciscollector.service
sudo systemctl status ciscollector.service

Your installation is now complete. You can access your dashboards using the central server URL, for example: http://xx.xx.xx.:8081. The steps below can be ignored, as they apply only to users following the older installation method who choose to continue with it . Please reach us at [e-mail] for any help

Below are steps if you want to use only ciscollector and not main server (Old method)

You can run iKloudDB Shield on your server by cloning repo or installing package (rpm , deb etc..) . Installing the package will automatically install all necessary dependencies

Method 1 - Cloning Repo

Clone the repo and build

git clone https://github.com/klouddb/klouddbshield

NOTE - You need to run below commands from the cloned repo location

$ go build -o ./ciscollector ./cmd/ciscollector
# Edit kshieldconfig.toml at path /etc/klouddbshield/kshieldconfig.toml 
$ ./ciscollector -r

Method 2 - Installing package

You can directly download the package from releases section of repo https://github.com/klouddb/klouddbshield/releases and install the package (for example – rpm for centos ; deb package for Ubuntu etc..) NOTE: Install the latest release only

E.g

For Ubuntu -

ciscollector_1.9_linux_amd64.deb

For Centos -

ciscollector_1.9_linux_amd64.rpm

NOTE - Scanning a large number of files may take a considerable amount of time. To expedite the process, please narrow your search to a specific time range or use wildcards to target a subset of log files

Configuration(Postgres) -

Once you install it , you need to populate the config file /etc/klouddbshield/kshieldconfig.toml in /etc/klouddbshield directory . Please fill username , dbname and password (sample entry below)

[postgres]
host="54.xxx.xxx.xx"
port="5432"
user="xxxxx"
dbname="postgres"
password="xxxxx"
maxIdleConn = 2
maxOpenConn = 2

How to execute after installing ?

Run the command "ciscollector -r " after cloning repo or installing package(Note - you need to populate /etc/klouddbshield/kshieldconfig.toml as described above)

Perform All Checks (Option 1) -

It is recommended to use Option 1 - All Postgres checks (as shown in the screenshot below). This option provides a comprehensive security report.

NOTE - Scanning a large number of files may take a considerable amount of time. To expedite the process, please narrow your search to a specific time range or use wildcards to target a subset of log files

Configuration(RDS) -

Make sure you have properly configured your AWS-CLI with a valid Access Key and Region or declare AWS variables properly. NOTE - You need to run this tool from bastion host or from some place where you have access to your RDS instances(It only needs basic aws rds describe priivs and sns read privs )

export AWS_ACCESS_KEY_ID="ASXXXXXXX"
export AWS_SECRET_ACCESS_KEY="XXXXXXXXX"
export AWS_SESSION_TOKEN="XXXXXXXXX"
export AWS_REGION="XXXXXXXXX"

Configuration(MySQL) -

Once you install it , you need to populate the config file /etc/klouddbshield/kshieldconfig.toml in /etc/klouddbshield directory . Please fill username , dbname and password (sample entry below)

[mysql]
host="xxxxxxx"
port="3306"
user="xxxxx"
password="xxxxx"
maxIdleConn = 2
maxOpenConn = 2

I am trying to use this tool but running into some issues , Can you help?

Please open an issue on repo or email us at [e-mail]