Variables Reference — Configuring all.yml

The variables file is the second of two files you need to edit before running the Diskover Ansible playbook. It controls what version of Diskover to install, your package repository credentials, and how every component is configured.

All variables are defined in a single file:

diskover-ansible/inventory/group_vars/all.yml

These variables are global — they apply to all host groups (web, worker, rabbitmq, elasticsearch). This guide explains every variable in detail: what it does, its default value, when you should change it, and what happens if you don't.

Quick Reference

Here's every variable at a glance. Detailed explanations follow in the sections below.

Installation Mode

These variables control whether packages are downloaded from the internet (online) or installed from pre-staged tarballs (offline/air-gapped). The offline tarballs are provided by the Diskover Data team.

offline_install

When false (the default), the playbook downloads Diskover packages from JFrog Artifactory over the internet. When true, the playbook installs from pre-built RPM tarballs that you've staged on the target hosts.

If you set this to true, you must also set offline_rpms_location. For the complete step-by-step process — including how to obtain the tarballs, stage them, and run the playbook — see the Offline / Air-Gapped Installation guide.

# Online installation (default)
offline_install: false

# Air-gapped / offline installation
offline_install: true

offline_rpms_location

This is the path on the Ansible control machine where you've placed the offline RPM tarballs provided by Diskover Data. During the playbook run, Ansible copies the relevant tarballs from this location to each target host.

offline_rpms_location: /home/admin/diskover-offline/

Important: This path must exist on the control machine (the machine running Ansible), not on the target hosts. See the Offline / Air-Gapped Installation guide for details on obtaining and staging these tarballs.

Diskover Application

These variables control which version of Diskover to install and how to access the package repository.

diskover_version

The Diskover release version to install. This must match a version available in JFrog Artifactory (for online installs) or in your offline package directory. Please reach out to the Diskover Data team if you're unsure which version to use.

diskover_version: 2.5.0

This variable is required for both online and offline installations. The playbook uses it to select the correct packages.

For upgrades: Update this value to the new version number and re-run the playbook. See the Running Playbooks guide for the full upgrade procedure.

jfrog_user

Your JFrog Artifactory username for downloading Diskover packages. This credential is provided by Diskover Data — contact Diskover Support if you don't have it.

jfrog_user: your-jfrog-username

jfrog_pass

Your JFrog Artifactory password or API key for downloading Diskover packages. This credential is provided by Diskover Data.

jfrog_pass: your-jfrog-api-key

Diskover Admin

config_diskover_admin_api

This controls whether the playbook runs the Diskover Admin API configuration play. On a first-time installation, this play writes directly to the Diskover Admin SQLite database, configuring the following settings so you don't have to do it manually through the Admin Wizard:

• Web.Elasticsearch — Elasticsearch host IP(s), port, HTTPS toggle, username, password, certificate verification, and CA certificate path

• Diskover.Elasticsearch — The same Elasticsearch connection settings used by the scanner/ingest layer

• System.Message Queue — RabbitMQ host IP, username, and password

• System.API — The Diskover Admin API host, port, and HTTPS toggle

When to set true:

• First-time installations (fresh deploy)

• When you want to reset the Admin configuration to match the current Ansible variables

When to set false:

• Upgrades — you don't want the playbook to overwrite your existing Admin configuration

• Re-runs where Admin is already configured

# First install
config_diskover_admin_api: true

# Upgrade or re-run
config_diskover_admin_api: false

This is the single most important variable to change between a fresh install and an upgrade. Forgetting to set it to false during an upgrade will overwrite all of the settings listed above — resetting them to whatever the Ansible variables currently specify and discarding any manual changes you've made through the Admin UI.

RabbitMQ Configuration

These variables control the RabbitMQ message broker credentials used by Diskover workers and Celery. Primarily used by the file actions in the Diskover GUI.

rabbitmq_user

The username for the RabbitMQ virtual host used by Diskover. This user is created by the playbook during installation.

rabbitmq_user: "diskover"

rabbitmq_pass

The password for the RabbitMQ user. The default value (darkdata) is intended for lab and development use only.

rabbitmq_pass: "your-secure-rabbitmq-password"

Important: Always change this from the default for any production or customer-facing deployment. The playbook configures both the RabbitMQ user and the Diskover Admin connection with this value.

Elasticsearch Configuration

These variables control how Elasticsearch is installed and configured. Elasticsearch is the search and analytics engine that stores all of Diskover's indexed data.

Using AWS OpenSearch? If your environment uses AWS OpenSearch instead of self-managed Elasticsearch, you can skip this entire section. These variables only apply to the Elasticsearch role that the playbook runs on the elasticsearch host group. With AWS OpenSearch, you would exclude the elasticsearch host group from your inventory and configure the OpenSearch endpoint directly in Diskover Admin after deployment.

es_heap_size

The JVM heap size in gigabytes for Elasticsearch. This directly impacts how much data Elasticsearch can handle and how fast searches run.

Sizing rule of thumb: Set to approximately half of the host's available RAM, but never exceed 31 GB (due to the JVM compressed object pointers limit).

es_heap_size: 8

Warning: Setting this too high (more than half of available RAM or above 31 GB) can cause Elasticsearch to crash or perform poorly. Setting it too low will limit the amount of data Elasticsearch can index efficiently. For a deeper explanation of why the 31 GB ceiling exists and how JVM heap sizing affects Elasticsearch performance, see the Elasticsearch JVM settings documentation.

es_memory_lock

When true, Elasticsearch locks its process memory to prevent the operating system from swapping it to disk. Swapping Elasticsearch memory to disk causes severe performance degradation.

es_memory_lock: true

The playbook configures the necessary systemd overrides (LimitMEMLOCK=infinity) to support memory locking.

es_network_host

Controls which network interface Elasticsearch binds to. The default 0.0.0.0 means Elasticsearch listens on all interfaces, making it accessible from any network the host is connected to.

# Listen on all interfaces (default)
es_network_host: "0.0.0.0"

# Listen only on a specific interface
es_network_host: "10.0.1.40"

# Listen only on localhost (single-host deployments only)
es_network_host: "127.0.0.1"

Important: If you set this to 127.0.0.1, Elasticsearch will only be accessible from the same machine. This works for single-host deployments but will break multi-host deployments where the web and worker hosts need to reach Elasticsearch over the network.

es_cluster_name

The name of the Elasticsearch cluster. All nodes in a cluster must share the same cluster name to discover and join each other.

es_cluster_name: "diskover"

For most deployments, the default is fine. Only change this if you have multiple Elasticsearch clusters on the same network segment.

es_security_enabled

Enables Elasticsearch security features — authentication (username/password) and TLS encryption between nodes. When enabled, all connections to Elasticsearch require authentication.

es_security_enabled: true

When this is true, the playbook automatically resets the elastic user password on the first Elasticsearch node and saves it to /root/.config/elastic.txt on that node (with 0400 permissions, readable only by root). The Diskover Admin API configuration play then reads this password file and uses it to configure the Elasticsearch connection in Diskover Admin — so you don't need to copy the password manually.

Security best practice: After the initial deployment is verified and working, copy the password from /root/.config/elastic.txt into your organization's corporate password manager, then delete the file from the Elasticsearch host:

cat /root/.config/elastic.txt   # Copy this value to your password manager
rm -f /root/.config/elastic.txt

Leaving plaintext credentials on disk is a security risk. Store the elastic user password somewhere safe — you'll need it if you ever need to manually configure or troubleshoot Elasticsearch connections.

es_security_enrollment_enabled

Enables Elasticsearch 8.x enrollment-based security setup. When a new node joins the cluster, it automatically configures TLS certificates through the enrollment process.

es_security_enrollment_enabled: true

es_data_dir

The directory where Elasticsearch stores its index data. For production deployments with large datasets, you might want this on a dedicated high-performance volume (e.g., NVMe SSD).

# Default location
es_data_dir: "/var/lib/elasticsearch"

# Custom location (e.g., a dedicated data volume)
es_data_dir: "/data/elasticsearch"

Note: The directory must exist and be writable by the elasticsearch user. The playbook handles permissions for the default path, but you may need to set permissions manually for custom paths.

Do not use NFS for Elasticsearch data directories. Elasticsearch requires low-latency, high-throughput local storage with POSIX filesystem semantics. NFS introduces network latency, file locking issues, and potential data corruption that can cause index failures, cluster instability, and data loss. Use local disk (SSD or NVMe strongly recommended) or a block storage volume (e.g., AWS EBS, Azure Managed Disk) mounted as a local filesystem.

es_log_dir

The directory where Elasticsearch writes its log files. These logs are useful for diagnosing performance issues and errors.

es_log_dir: "/var/log/elasticsearch"

es_restart_on_change

When true, the playbook automatically restarts Elasticsearch whenever its configuration files are modified. When false, configuration changes are applied to the files but Elasticsearch continues running with the old settings until you restart it manually.

# Automatic restart (default)
es_restart_on_change: true

# Manual restart (useful during maintenance windows)
es_restart_on_change: false

es_start_service

When true, the playbook starts the Elasticsearch service after installation and configuration. Set to false if you need to make additional manual changes before starting the service (e.g., custom JVM options, additional plugins).

es_start_service: true

SSL/TLS Configuration

These variables enable HTTPS for the Diskover Web UI. When SSL is enabled, Nginx is configured for TLS termination using your provided certificate and key.

ssl_enabled

When true, the playbook configures Nginx with TLS using the certificate and key specified below. HTTP traffic on port 80 is automatically redirected to HTTPS on port 443.

ssl_enabled: true

When you set this to true, you must also set ssl_domain, ssl_cert_source, and ssl_key_source.

ssl_domain

The fully qualified domain name for the SSL certificate. This value is used in the Nginx server_name directive inside /etc/nginx/conf.d/diskover-web.conf.

ssl_domain: "diskover.example.com"

Important: This domain must resolve to the web host's IP address (via DNS or /etc/hosts) and must match the Common Name (CN) or Subject Alternative Name (SAN) in your SSL certificate.

ssl_cert_source

The absolute path on the Ansible control machine to the SSL certificate file (.crt or .pem). During the playbook run, this file is copied to the target web host.

ssl_cert_source: "/root/certs/diskover.crt"

The path must be absolute (e.g., /root/certs/diskover.crt, not ~/certs/diskover.crt). The file must exist on the control machine, not on the target host.

ssl_key_source

The absolute path on the Ansible control machine to the SSL private key file. During the playbook run, this file is copied to the target web host.

ssl_key_source: "/root/certs/diskover.key"

ssl_force_reconfigure

When running the playbook on a host that already has SSL configured, the SSL role skips reconfiguration by default (to avoid overwriting a working setup). Set this to true to force the role to re-deploy certificates, update the Nginx configuration, and refresh the Python certificate trust store.

# Default — skip SSL reconfiguration if already set up
ssl_force_reconfigure: false

# Force reconfiguration (e.g., after renewing or replacing certificates)
ssl_force_reconfigure: true

Common reasons to set this to true:

• You've renewed or replaced your SSL certificate

• You're changing the SSL domain name

• Python SSL verification is failing after enabling SSL (the trust store needs updating)

MCP Connector Configuration

deploy_mcp_server

When true, the playbook installs the Diskover MCP (Model Context Protocol) connector and Node.js on the web host. The MCP Connector enables AI-powered integrations with Diskover.

The Diskover MCP Connector is a paid add-on feature. It requires prior authorization and licensing from the Diskover Data team before it can be used. Setting this to true will install the software, but the connector will not function without a valid MCP license. Contact Diskover Support or your Diskover account representative to learn more about MCP Connector licensing.

deploy_mcp_server: true

When false (the default), the MCP role is skipped entirely. Leave this as false unless you have already arranged MCP Connector licensing with Diskover Data.

Example: Minimal all.yml for a First-Time Install

Here's the minimal set of changes you need to make for a first-time online installation:

# Version to install
diskover_version: 2.5.0

# JFrog credentials (provided by Diskover Data)
jfrog_user: your-jfrog-username
jfrog_pass: your-jfrog-api-key

# Auto-configure Diskover Admin (first install)
config_diskover_admin_api: true

# RabbitMQ password — change from the default!
rabbitmq_user: "diskover"
rabbitmq_pass: "your-secure-password"

# Elasticsearch — adjust heap size for your host's RAM
es_heap_size: 4

Example: all.yml for an Upgrade

When upgrading an existing Diskover deployment to a new version:

# New version to install
diskover_version: 2.5.1

# JFrog credentials (same as before)
jfrog_user: your-jfrog-username
jfrog_pass: your-jfrog-api-key

# IMPORTANT: Set to false to preserve existing Admin configuration!
config_diskover_admin_api: false

# Keep all other settings the same as your current deployment
rabbitmq_user: "diskover"
rabbitmq_pass: "your-secure-password"
es_heap_size: 4

Example: all.yml for an Offline Installation

For air-gapped environments with no internet access:

# Enable offline mode
offline_install: true
offline_rpms_location: /home/admin/diskover-offline/

# Version must match the offline artifacts
diskover_version: 2.5.0

# JFrog credentials are NOT needed for offline installs
# jfrog_user and jfrog_pass can be left blank

# Auto-configure Diskover Admin
config_diskover_admin_api: true

# RabbitMQ password
rabbitmq_user: "diskover"
rabbitmq_pass: "your-secure-password"

Example: all.yml with SSL Enabled

For enabling HTTPS on the Diskover Web UI:

diskover_version: 2.5.0
jfrog_user: your-jfrog-username
jfrog_pass: your-jfrog-api-key
config_diskover_admin_api: true
rabbitmq_user: "diskover"
rabbitmq_pass: "your-secure-password"

# SSL configuration
ssl_enabled: true
ssl_domain: "diskover.example.com"
ssl_cert_source: "/root/certs/diskover.crt"
ssl_key_source: "/root/certs/diskover.key"

Next Steps

With your variables configured, you're ready to run the playbook. See the Running Playbooks guide for execution commands, targeting specific hosts, performing upgrades, and more.