> For the complete documentation index, see [llms.txt](https://klouddb.gitbook.io/klouddb_shield/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://klouddb.gitbook.io/klouddb_shield/how-to-install-and-configure.md). # 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 ``` 2. 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 ``` 3. 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: . 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 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 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