.. _ConfigFile: Configuration File ================== ApertureDB reads server settings from a JSON configuration file. The ``-cfg`` flag specifies its path: ./aperturedb -cfg config.json Without ``-cfg``, ApertureDB reads ``config.json`` from the working directory. The server does not start if the file is missing. Parameters ---------- All configuration keys are optional. Omitted settings use environment variables or built-in defaults according to the precedence below. For settings read by the server, the first available value is used: 1. A **nonempty** environment variable with prefix ``ADB_`` and the key in upper case, such as ``ADB_PORT`` or ``ADB_SESSION_TOKEN_MAX_AGE_SEC``. 2. The value in the JSON configuration file. 3. The server's built-in default. An empty environment variable falls through to JSON or the default. Use ``true``/``false`` for boolean environment values, decimal numbers for numeric values, and raw text for strings. Do not add JSON quotes around string values in the environment. Shell or deployment-file quoting is separate. The JSON file is parsed and validated **before** environment overrides are read. Unknown keys, wrong JSON types, and out-of-range JSON values prevent startup even when an environment variable would override them. Environment values are parsed when the consuming setting is read; the JSON validator does not validate the final merged configuration. Follow the documented ranges for both sources. Restart the consuming process after configuration changes. These defaults describe the database binary. Deployment packages supply additional values and configure separate processes; see :ref:`configuration-deployment-mapping`. The following table describes commonly used parameters: .. list-table:: :widths: 20 40 20 :header-rows: 1 * - Parameter - Explanation - Default * - master_key - The master key that initializes admin password on the first run. - ``""`` (Range: any string) * - port - TCP port for incoming connections - 55555 (Range: 1-65535) * - enable_health_port - Enable/disable the health check port - false (Range: true/false) * - health_port - TCP port for health checks - 55563 (Range: 1-65535) * - timeout_receive - Enable/disable connection receive timeouts - true (Range: true/false) * - network_threads - Threads servicing asynchronous connections; idle clients do not occupy query workers. - Up to 4, based on available CPU cores (Range: 1–1024) * - query_threads - Workers executing queries. Separate from the number of accepted connections. - Up to 16, based on available CPU cores (Range: 1–65536) * - query_queue_bytes_mb - MiB budget shared by all connections for retained request/response bytes, including streamed blob chunks. Also bounds bytes admitted to the query worker pool and the largest request. Allow headroom above the largest encoded request for metadata and worker bookkeeping; concurrent requests and responses compete for this budget. Exhaustion closes the connection. - 256 (Range: > 0) * - max_read_transactions - Maximum simultaneous database read transactions, independent of socket count. - Greater of 126 or five times query_threads (Range: 1–1048576) * - max_connection_message_size_mb - Maximum native query/response message size in MiB (1,048,576 bytes). A value of 0 uses the libcomm default. Set ``query_queue_bytes_mb`` above this limit, with headroom for concurrent retained data and bookkeeping. This does not set HTTP proxy limits. - 0 (Range: >= 0) * - force_ssl - Flag that indicates whether or not SSL-based communication will be enforced by the server - true (Range: true/false) * - db_root_path - Path to the root folder where all files/objects will be stored - db (Range: any valid path) * - storage_type - Storage backend: ``ext4`` for local files, ``s3`` for S3, or ``gs`` for Google Cloud Storage. - ``"ext4"`` * - storage_bucket_name - Bucket name for S3 or Google Cloud Storage. - ``""`` * - storage_credentials - Storage credential JSON encoded as a string. See :doc:`Deployment` for credential examples. - ``"{}"`` * - log_path - Directory where logs will be placed. - ``"/tmp"`` (Range: any valid path) * - log_level - Levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively - 1 (WARNING) (Range: 0-3) * - verbose_log_level - Verbosity level beyond INFO, for debugging. Will set log_level = 0. Check Google glog documentation for details - -1 (no verbosity beyond INFO) (Range: >= -1) * - log_cerr_threshold - Specify level of logging which will also be sent to stderr - 3 (FATAL) (Range: 0-3) * - enable_audit_logs - Enable/disable audit logs - false (Range: true/false) * - include_audit_logs - When true, audit logs will be included in ApertureDB logs - false (Range: true/false) * - kvgd_db_size - Initial graph database mapping size in MiB. The mapping can grow; this is not a RAM reservation or a physical disk capacity limit. - 10 (Range: > 0) * - kvgd_db_sync - Enable/disable sync operation to disk on every transaction. When disabled, latency will decrease but data loss may occur in case of crash - true (Range: true/false) * - locale_name - Locale used for string comparison - en_US (Range: any valid locale) * - zk_servers - Comma-separated list of Zookeeper server:port - ``""`` (Range: any string) * - zk_prefix - Same instance of Zookeeper can be used by multiple aperturedb clusters. Each cluster uses a different prefix to provide isolation between clusters. The config parameter zk_prefix specifies the path for the instance. - ``"testing"`` (Range: any string) * - checkpoints_to_keep - Number of checkpoints that will be kept for recovery - 4 (Range: > 0) * - seconds_between_checkpoints - Interval in seconds between scheduled checkpoints. At least one new changelog is required; commit count does not trigger an earlier checkpoint. - 7200 (2 hours) (Range: > 0) * - descriptorset_flusher_interval - Number of seconds between descriptor set cleanup operations - 1800 (Range: >= 0) * - descriptor_index_cache_size_mb - RAM budget in MiB for immutable descriptor index snapshots, their background copies, and private arrays for eligible HNSW appends. Synchronous and lazy indexing share this cache. Zero disables it. Queries use the transactional LMDB index while a matching snapshot is unavailable. - 512 (Range: >= 0, must fit the platform byte count) The descriptor cache budget includes snapshots still held by queries or construction after cache eviction. HNSW native construction scratch and dirty records remain bounded by the mutation workspace, separately from cache-charged arrays. Eligible owned-array construction accounts for native scratch per worker before admission; it can reduce the worker count or use the serial record path when the available budgets do not fit. Explicit mutation limits remain strict. The cache budget excludes query scratch, graph transaction buffers, and the operating system's LMDB page cache. The lazily allocated admission observation table is also separate (at most 32 namespaces, about 18 KiB on supported 64-bit platforms). A snapshot whose construction estimate exceeds the budget remains searchable directly from LMDB. Cache construction uses one background worker and never blocks a query waiting for completion. Automatic admission requires reuse evidence for the same index revision: 32 eligible absent observations, or a later observation at least one second after the current observation window began. A new revision starts a new window; idle time alone does not start a build. When the bounded observation table is full, new namespaces replace its least recently observed entry and qualify immediately. These fixed heuristics are not query-latency or cache-readiness guarantees. To verify warmup on an otherwise idle server, issue representative queries and observe an increase in ``descriptor_index_cache_hits_total``. These global counters cannot attribute individual requests on a server with other traffic. A nonzero budget, a resident entry, elapsed wall time or a completed build alone does not prove that the current query revision used the cache. ``reason="deferred"`` in the rejected-by-reason metric indicates that automatic admission is waiting for reuse evidence. Measure warmup and post-write behavior separately from steady-state resident queries. Security and connection limits ------------------------------ These settings apply per server. All values must be positive integers. .. list-table:: :header-rows: 1 * - Setting - Default - Behavior * - ``session_token_max_age_sec`` - 36000 - Session token lifetime in seconds (10 hours). * - ``refresh_token_max_age_sec`` - 360000 - Refresh token lifetime in seconds (100 hours). * - ``max_sessions_per_user`` - 1024 - Maximum sessions per user. Signing in or refreshing revokes the oldest sessions as needed to stay within the limit. * - ``max_sessions_in_cache`` - 1024 - Successful session checks kept for reuse. Lower limits reduce retained authentication data and may require more checks; session lifetime and revocation rules stay the same. * - ``max_remote_connections`` - 32 - Connections kept for reuse with external origins. Lower limits may require more connection setup; ongoing requests are unaffected. This does not limit concurrent requests or connections to the database's own storage. See :doc:`AccessControl` and :doc:`RemoteCredentials` for session limits and the effects of changing permissions or credentials. .. _configuration-https: HTTPS origin limits ------------------- These optional integer settings control reads from registered HTTPS origins. They do not configure inbound HTTPS or change the HTTP proxy's request limit. See :ref:`https-credentials` for authentication, URL restrictions, and recovery. .. list-table:: HTTPS fetch controls :header-rows: 1 :widths: 35 15 20 30 * - JSON key / environment suffix - Default - Range - Scope * - ``https_max_object_size_mb`` / ``HTTPS_MAX_OBJECT_SIZE_MB`` - 16 MiB - 1–64 MiB - Maximum bytes in one remote object. * - ``https_timeout_ms`` / ``HTTPS_TIMEOUT_MS`` - 10000 ms - 1–30000 ms - Maximum time for one fetch, also bounded by its remaining active fetch budget. * - ``https_operations_limit`` / ``HTTPS_OPERATIONS_LIMIT`` - 4 - 1–32 - Concurrent HTTPS operations/readers per server process. Prefix the environment suffix with ``ADB_``. Independently, one query has a 64 MiB total download budget, at most 32 HTTPS requests, 60 seconds of cumulative active fetch time, and at most two active fetches. Waiting for the client to consume a lazy blob response does not consume the fetch-time budget. These per-query limits are not increased by the three settings above. A size check can make a HEAD request in addition to a GET. Split large workloads into smaller queries and reduce concurrency when limits are reached; retries also consume resources. .. _configuration-advanced: .. _advanced-and-compatibility-settings: Advanced settings ----------------- These settings control resource limits and background work. Their appropriate values depend on the deployment layout and workload; changes require coordination with the deployment administrator or ApertureData support. The table lists server defaults before package overrides. .. list-table:: Advanced settings :header-rows: 1 :widths: 40 20 40 * - Key - Default - Purpose and JSON range * - ``storage_operations_limit`` - 100 - Concurrent object-store operations; integer ≥ 1. * - ``storage_part_size_mb`` - 8 - Multipart/cache part size in MiB; integer 5–512. * - ``storage_read_cache_parts`` - 4 - Cached parts per reader; integer 1–64. Memory depends on part size. * - ``storage_retry_limit`` / ``storage_retry_delay_ms`` - 5 / 200 - Retry count (integer ≥ 0) and initial backoff in ms (integer ≥ 1). * - ``objects_partition_count`` / ``objects_directory_count`` - 4 / 4096 - Object-store layout; integers ≥ 1. Do not change an existing layout casually. * - ``resources_max_storage`` / ``resources_check_storage_limit`` - 0 / 99 - Storage reference limit in GiB (0 disables this limit) and percentage threshold (number 0–100). * - ``task_executor_threads`` - 100 - Executor thread count; integer ≥ 1. * - ``enable_blacklist`` - 0 - Connection blacklist switch; JSON integer 0 or 1, not a JSON boolean. * - ``max_failed_connections`` / ``blacklist_time_minutes`` - 10 / 5 - Blacklist failure threshold and duration in minutes; integers ≥ 1. * - ``kvgd_db_inc_size`` - 0 - Graph mapping growth increment in MB; integer ≥ 0. * - ``kvgd_readahead`` / ``validate_write_txn`` - false / false - Graph read-ahead and additional write validation; booleans. * - ``merge_write_request_upto`` - 0 - Internal write-merging control; integer ≥ 0. * - ``refresh_dset_on_startup`` - false - Accepted with no effect. Descriptor indexes are maintained transactionally. ``more-info`` is a string annotation accepted in the JSON file; it changes no server behavior and has no environment override. ``ADB_HOST_IP`` is an environment-only server setting for the advertised host identity; its default is the machine hostname. ``host_ip`` is not an accepted JSON key. .. _configuration-deployment-mapping: Deployment settings and process boundaries ------------------------------------------ A client first reaches Lenz for the native protocol, or the web proxy and Lenz for REST. The database is a separate backend. Each process reads its own configuration; changing a database variable does not configure the gateway. .. list-table:: Where to configure a setting :header-rows: 1 :widths: 20 25 25 30 * - Consumer / purpose - Compose - Helm - OpenTofu * - Database bootstrap password - ``ADB_MASTER_KEY`` - ``masterKey.password`` or ``masterKey.existingSecret`` - ``master_key.password`` or ``master_key.existing_secret`` * - Database storage - ``ADB_STORAGE_TYPE``, ``ADB_STORAGE_BUCKET_NAME``, ``ADB_STORAGE_CREDENTIALS`` in distributed-cloud - ``storage.type``, ``storage.bucket``, ``storage.credentials`` / ``existingSecret`` - ``storage.type``, ``storage.bucket``, ``storage.credentials`` / ``existing_secret`` * - Database HTTPS fetch controls - Custom Compose override for each database service's ``environment``; the published environment template does not forward these keys. - ``aperturedb.extraEnv.ADB_HTTPS_*`` - ``aperturedb.extra_env`` map with ``ADB_HTTPS_*`` keys * - Lenz native TLS - ``LNZ_FORCE_SSL``; default ``false`` - Enabled by the chart's Lenz template - Enabled by the module's Lenz configuration * - Web HTTPS certificates - ``TLS_CERT_DIR`` and certificate filenames, or ``TLS_CERT_HOSTNAMES`` for the generated certificate - ``tls`` settings - ``tls`` settings * - Maximum HTTP request body size - ``HTTP_BODY_LIMIT``; default ``268435456`` bytes - ``http.bodyLimit`` in bytes - ``http.body_limit`` in bytes * - HTTP upstream inactivity timeout - ``HTTP_TIMEOUT_SECONDS``; default ``300`` seconds - ``http.timeoutSeconds`` - ``http.timeout_seconds`` * - Web redirect and application URL port - ``HTTPS_PORT``; default ``443`` - ``http.publicPort``; set to the public port, normally ``443`` - ``http.public_port``; set to the public port, normally ``443`` * - Workflow HTTP routes - Mount an HTTP route configuration with a Compose override - ``http.routes`` - ``http.routes`` * - Published native port - ``ADB_TCP_PORT``; default ``55555`` - ``service.port``; default ``55555``; ``service.nodePort`` for a fixed node port - ``service.port``; default ``55555``; ``service.node_port`` for a fixed node port * - Published Lenz health port - ``ADB_HEALTH_PORT``; default ``58085`` - Not configurable; published on an assigned node port when ``service.type`` is ``NodePort`` - Not configurable; published on an assigned node port when ``service.type`` is ``NodePort`` All three packages set backend ``ADB_FORCE_SSL=false`` and use Lenz for native client TLS. In Helm and OpenTofu, native TLS is enabled by default; Compose requires ``LNZ_FORCE_SSL=true`` to enforce it. HTTP TLS is configured separately. A certificate alone does not enable Compose's native TLS requirement. The web port settings control redirects and application URLs. In Kubernetes, set the public port explicitly when a load balancer forwards to backend NodePorts. Workflow routes and Grafana allow one hour between response reads for interactive sessions. Compose substitutes only variables named by its template. Exporting an arbitrary ``ADB_*`` variable on the host does not inject it into a container. Helm's ``aperturedb.extraEnv`` and OpenTofu's ``aperturedb.extra_env`` add variables to database containers; use the separate Lenz and checkpointer maps for those processes. Prefer named package values when available, and inspect rendered configuration before introducing a duplicate environment key. For examples and lifecycle commands, see :doc:`Deployment`. Config File Example ------------------- This example sets common parameters to their default values. Omitted parameters use their defaults. For a new database, also set ``ADB_MASTER_KEY`` to a strong password before starting the server. .. code-block:: json { "port": 55555, "network_threads": 4, "query_threads": 16, "query_queue_bytes_mb": 256, "max_read_transactions": 126, "max_connection_message_size_mb": 0, "force_ssl": true, "db_root_path": "db", "storage_type": "ext4", "log_path": "/tmp", "log_level": 1, "verbose_log_level": -1, "log_cerr_threshold": 3 } Default Directories Structure ----------------------------- ApertureDB creates the following directories under its default data path: .. code-block:: console db ├── acl ├── binlogs ├── descriptors ├── graph ├── objects └── tmp