InfluxDB 3 Enterprise configuration options

InfluxDB 3 Enterprise lets you customize your configuration by using influxdb3 command options or by setting environment variables.

Configure your server

Pass configuration options using either command options or environment variables. Command options take precedence over environment variables.

TOML configuration files

DEB and RPM installs include a TOML configuration file at /etc/influxdb3/influxdb3-enterprise.conf. The systemd launcher reads this file and converts each entry to an INFLUXDB3_* environment variable (the pattern is INFLUXDB3_<KEY> with hyphens replaced by underscores and uppercased) before invoking influxdb3 serve.

influxdb3 serve does not yet natively read TOML; the file’s effect is applied through the environment variables the launcher sets. CLI flags passed to influxdb3 serve still override values defined in the TOML file because they override the environment variables that file becomes.

For day-to-day systemd operation — including the edit-and-restart workflow for applying changes — see Run as a system service (Linux).

Global vs serve-specific options

Some options are global (specified before the command) while others are serve-specific (specified after serve):

• Global options: Apply to the influxdb3 CLI itself (for example, --num-io-threads)
• Serve options: Apply only to the serve command (for example, --node-id, --object-store, --verbose)

Example command with global and serve-specific options

influxdb3 --num-io-threads=4 serve \
  --node-id node0 \
  --cluster-id cluster0 \
  --license-email example@email.com \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --verbose \
  --log-filter info

Example environment variables

export INFLUXDB3_LICENSE_EMAIL=example@email.com
export INFLUXDB3_CLUSTER_ID=cluster0

export INFLUXDB3_NODE_ID=my-node
export INFLUXDB3_OBJECT_STORE=file
export INFLUXDB3_DATA_DIR=~/.influxdb3
export INFLUXDB3_LOG_FILTER=info

influxdb3 serve

Deprecated environment variable names

Several environment variables were renamed so that each variable matches its command option. In addition, Enterprise-specific variables dropped the ENTERPRISE_ segment–for example, INFLUXDB3_ENTERPRISE_LICENSE_EMAIL is now INFLUXDB3_LICENSE_EMAIL.

Legacy names remain supported as deprecated aliases; the server logs a deprecation warning at startup when it detects one. If both the new and the legacy name are set, the new name takes precedence. Option tables on this page list deprecated aliases where they exist.

Use the following tables to migrate a deployment configuration–for example, Helm values or a systemd environment file–in one pass.

Renamed options (legacy names aliased)

The following influxdb3 serve options and their environment variables were renamed. Legacy names remain supported as deprecated aliases.

Renamed environment variables (legacy names aliased)

The following environment variables were renamed to match their command options; the option names are unchanged. Legacy names remain supported as deprecated aliases.

Renamed Enterprise environment variables (legacy names aliased)

Enterprise-specific environment variables dropped the ENTERPRISE_ segment. Legacy names remain supported as deprecated aliases.

Removed pt- option names (no aliases)

Options for the upgraded storage engine (PachaTree) dropped the pt- prefix without backward compatibility: old --pt-* flags cause a startup error, and legacy INFLUXDB3_PT_* and INFLUXDB3_ENTERPRISE_PT_* environment variables are ignored (the server logs a warning at startup for each one that is still set). For the complete old-to-new name table, see Migrate from --pt-* option names.

Size option values

Options that accept a size value require an explicit unit:

• Append a unit suffix b, kb, mb, gb, or tb (case-insensitive)–for example, 10mb or 8GB.
• Where noted, a percentage of total available memory is accepted–for example, 20%.
• Bare numbers are rejected. Historically, a bare number meant megabytes for some options and bytes for others, so sizes always carry an explicit unit.

Global configuration options

The following options apply to the influxdb3 CLI globally and must be specified before any subcommand (for example, serve):

num-io-threads

Sets the number of threads allocated to the IO runtime thread pool. IO threads handle HTTP request serving, line protocol parsing, and file operations.

Default: 2 on Parquet-engine clusters; the licensed core count on clusters running the upgraded storage engine (the default for new clusters). Values above the licensed core count are capped with a startup warning.

# Set IO threads (global option before serve)
influxdb3 --num-io-threads=8 serve --node-id=node0 --object-store=file

For detailed information about thread allocation, see the Resource Limits section.

Server configuration options

• General

  • Licensing

• Security

• AWS

• Google Cloud Service

• Microsoft Azure

• Object Storage

• Logs

• Traces

• DataFusion

• HTTP

• Memory

• Write-Ahead Log (WAL)

• Compaction

• Caching

• Processing Engine

• Cluster Management

• Resource Limits

• Data Lifecycle Management

• Telemetry

• TCP Listeners

General

• cluster-id

• data-dir

• mode

• node-id

• node-id-from-env

• object-store

• query-file-limit

• upgrade-pacha-tree

cluster-id

Specifies the cluster identifier that prefixes the object store path for the Enterprise Catalog. This value must be different than the --node-id value.

data-dir

For the file object store, defines the location InfluxDB 3 Enterprise uses to store files locally. Required when using the file object store.

mode

Sets the mode to start the server in, allowing you to create specialized nodes in a distributed cluster.

This option supports the following values:

• all (default): Enables all server modes
• ingest: Enables only data ingest capabilities
• query: Enables only query capabilities
• compact: Enables only compaction processes
• process: Activates the Processing Engine so the node can execute trigger plugins. process has no API surface of its own — it doesn’t accept writes or serve queries. Setting --plugin-dir implicitly adds process mode regardless of --mode. Conversely, --mode=process requires --plugin-dir. In a multi-node cluster, combine process with another mode (typically query) so plugins can call influxdb3_local.query() locally.

You can specify multiple modes using a comma-delimited list (for example, ingest,query).

Default: all

Example configurations:

# High-throughput ingest node (32 cores)
influxdb3 --num-io-threads=12 serve --mode=ingest --datafusion-num-threads=20

# Query-optimized node (32 cores)
influxdb3 --num-io-threads=4 serve --mode=query --datafusion-num-threads=28

# Balanced all-in-one (32 cores)
influxdb3 --num-io-threads=6 serve --mode=all --datafusion-num-threads=26

node-id

Specifies the node identifier used as a prefix in all object store file paths. This should be unique for any hosts sharing the same object store configuration–for example, the same bucket.

node-id-from-env

Specifies the node identifier used as a prefix in all object store file paths. Takes the name of an environment variable as an argument and uses the value of that environment variable as the node identifier. This option cannot be used with the --node-id option.

Example using –node-id-from-env

export DATABASE_NODE=node0 && influxdb3 serve \
  --node-id-from-env DATABASE_NODE \
  --cluster-id cluster0 \
  --object-store file \
  --data-dir ~/.influxdb3/data

object-store

Specifies which object storage to use to store Parquet files. This option supports the following values:

• memory: Effectively no object persistence
• memory-throttled: Like memory but with latency and throughput that somewhat resembles a cloud object store
• file: Stores objects in the local filesystem (must also set --data-dir)
• s3: Amazon S3 (must also set --bucket, --aws-access-key-id, --aws-secret-access-key, and possibly --aws-default-region)
• google: Google Cloud Storage (must also set --bucket and --google-service-account)
• azure: Microsoft Azure blob storage (must also set --bucket, --azure-storage-account, and --azure-storage-access-key)

upgrade-pacha-tree

Migrates the cluster’s existing Parquet data to the upgraded storage engine.

New clusters default to the upgraded storage engine. Clusters that started on 3.10 or earlier keep the Parquet engine until you run the storage engine upgrade by restarting the cluster with --upgrade-pacha-tree. New clusters do not need this flag. For the upgrade procedure, see Upgrade from Parquet.

Default: false

Licensing

license-email

Specifies the email address to associate with your InfluxDB 3 Enterprise license and automatically responds to the interactive email prompt when the server starts. This option is mutually exclusive with license-file.

license-file

Specifies the path to a license file for InfluxDB 3 Enterprise. When provided, the license file’s contents are used instead of requesting a new license. This option is mutually exclusive with license-email.

license-type

Specifies the type of InfluxDB 3 Enterprise license to use and bypasses the interactive license prompt. Provide one of the following license types:

• home
• trial
• commercial

Security

• tls-key
• tls-cert
• tls-minimum-versions
• without-auth
• disable-authz
• admin-token-recovery-http-bind
• admin-token-file
  • permission-tokens-file
• without-user-auth
• jwt-key-id
• jwt-private-key
• jwt-issuer
• jwt-default-ttl-seconds
• oauth-issuer
• oauth-audience
• oauth-client-id
• oauth-scopes
• rbac-authoring-disabled

tls-key

The path to a key file for TLS to be enabled.

tls-cert

The path to a cert file for TLS to be enabled.

tls-minimum-version

The minimum version for TLS. Valid values are tls-1.2 or tls-1.3. Default is tls-1.2.

without-auth

Disables authentication for all server actions (CLI commands and API requests). The server processes all requests without requiring tokens or authentication.

disable-authz

Optionally disable authz by passing in a comma separated list of resources. Valid values are health, ping, and metrics.

admin-token-recovery-http-bind

Enables an admin token recovery HTTP server on a separate port. This server allows regenerating lost admin tokens without existing authentication. The server automatically shuts down after a successful token regeneration.

Default: 127.0.0.1:8182 (when enabled)

Example usage

# Start server with recovery endpoint
influxdb3 serve --admin-token-recovery-http-bind

# In another terminal, regenerate the admin token
influxdb3 create token --admin --regenerate --host http://127.0.0.1:8182

admin-token-file

Specifies an offline admin token file to use if no tokens exist when the server starts. Once started, you can interact with the server using the provided token. Offline admin tokens are designed to help with automated deployments.

Offline admin tokens are defined in a JSON-formatted file. Use the following command to generate an offline admin token file:

influxdb3 create token --admin \
  --name "example-admin-token" \
  --expiry 1d \
  --offline \
  --output-file 
./path/to/admin-token.json

{
  "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
  "name": "example-admin-token",
  "expiry_millis": 1756400061529
}

Example usage

# Generate an admin token offline
influxdb3 create token \
  --admin \
  --name "example-admin-token" \
  --expiry 1d \
  --offline \
  --output-file 
./path/to/admin-token.json

# Start InfluxDB 3 Enterprise using the generated token
influxdb3 serve --admin-token-file 
./path/to/admin-token.json

permission-tokens-file

Specifies an offline permission (resource) tokens file to use if no resource tokens exist when the server starts. Once started, you can interact with the server using the provided tokens. Offline permission tokens are designed to help with automated deployments.

Multiple tokens with database-level permissions can be defined. You can also specify databases to create at startup. Use the a command similar to the following to generate an offline permission token file:

influxdb3 create token \
  --name "example-token" \
  --permission "db:db1,db2:read,write" \
  --permission "db:db3:read" \
  --expiry 1d \
  --offline \
  --create-databases db1,db2 \
  --output-file 
./path/to/tokens.json

{
  "create_databases": [
    "db1",
    "db2",
    "d3"
  ],
  "tokens": [
    {
      "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
      "name": "example-token",
      "expiry_millis": 1756400061529,
      "permissions": [
        "db:db1,db2:read,write",
        "db:db3:read"
      ]
    }
  ]
}

Example usage

# Generate an admin token offline
influxdb3 create token \
  --name "example-token" \
  --permission "db:db1,db2:read,write" \
  --permission "db:db3:read" \
  --expiry 1d \
  --offline \
  --create-databases db1,db2 \
  --output-file 
./path/to/tokens.json

# Start InfluxDB 3 Enterprise using the generated token
influxdb3 serve --permission-tokens-file 
./path/to/tokens.json

without-user-auth

Disables user authentication. Set to false to enable multi-user authentication, where users authenticate with a username and password to receive a JWT.

Default: true

jwt-key-id

RSA key ID used for signing JWTs for user authentication. Required together with jwt-private-key to enable JWT authentication.

jwt-private-key

RSA private key (PEM) used for signing JWTs for user authentication. Required together with jwt-key-id to enable JWT authentication.

jwt-issuer

Issuer claim for user authentication JWTs.

Default: influxdb3-enterprise

jwt-default-ttl-seconds

Default TTL (in seconds) for user authentication JWTs.

oauth-issuer

OAuth issuer URL for validating OAuth tokens. Required together with oauth-audience to enable OAuth authentication.

oauth-audience

OAuth audience for validating OAuth tokens. Required together with oauth-issuer to enable OAuth authentication.

oauth-client-id

OAuth client ID for the device-code login flow. Required to enable influxdb3 auth login --oauth.

oauth-scopes

OAuth scopes to request during device-code login (comma-separated).

Default: openid,offline_access

rbac-authoring-disabled

Disables RBAC authoring (creating or modifying custom roles). Accepts true or false.

AWS

• aws-access-key-id
• aws-secret-access-key
• aws-default-region
• aws-endpoint
• aws-session-token
• aws-allow-http
• aws-skip-signature
• aws-credentials-file

aws-access-key-id

When using Amazon S3 as the object store, set this to an access key that has permission to read from and write to the specified S3 bucket.

aws-secret-access-key

When using Amazon S3 as the object store, set this to the secret access key that goes with the specified access key ID.

aws-default-region

When using Amazon S3 as the object store, set this to the region that goes with the specified bucket if different from the fallback value.

Default: us-east-1

aws-endpoint

When using an Amazon S3 compatibility storage service, set this to the endpoint.

aws-session-token

When using Amazon S3 as an object store, set this to the session token. This is handy when using a federated login or SSO and fetching credentials via the UI.

aws-allow-http

Allows unencrypted HTTP connections to AWS.

aws-skip-signature

If enabled, S3 object stores do not fetch credentials and do not sign requests.

aws-credentials-file

Specifies the path to your S3 credentials file. When using a credentials file, settings in the file override the corresponding CLI flags.

S3 credential files are JSON-formatted and should contain the following:

{
  "aws_access_key_id": "
AWS_ACCESS_KEY_ID
",
  "aws_secret_access_key": "
AWS_SECRET_ACCESS_KEY
",
  "aws_session_token": "
AWS_SESSION_TOKEN
",
  "expiry": "
UNIX_SECONDS_TIMESTAMP
"
}

The aws_session_token and expiry fields are optional. The file is automatically checked for updates at the expiry time or at 1-hour intervals.

If the object store returns an “Unauthenticated” error, InfluxDB will attempt to update its in-memory credentials from this file and then retry the object store request.

Google Cloud Service

• google-service-account

google-service-account

When using Google Cloud Storage as the object store, set this to the path to the JSON file that contains the Google credentials.

Microsoft Azure

• azure-storage-account
• azure-storage-access-key
• azure-endpoint
• azure-allow-http

azure-storage-account

When using Microsoft Azure as the object store, set this to the name you see when navigating to All Services > Storage accounts > [name].

azure-storage-access-key

When using Microsoft Azure as the object store, set this to one of the Key values in the Storage account’s Settings > Access keys.

azure-endpoint

When using Microsoft Azure as the object store, set this to the Azure Blob Storage endpoint.

azure-allow-http

When using Microsoft Azure as the object store, allow unencrypted HTTP requests to Azure Blob Storage.

Default: false

Object Storage

• bucket
• object-store-connection-limit
• object-store-http2-only
• object-store-http2-max-frame-size
• object-store-request-timeout
• object-store-max-retries
• object-store-retry-timeout
• object-store-cache-endpoint
• object-store-tls-allow-insecure
• object-store-tls-ca

bucket

Sets the name of the object storage bucket to use. Must also set --object-store to a cloud object storage for this option to take effect.

object-store-connection-limit

When using a network-based object store, limits the number of connections to this value.

Default: 16

object-store-http2-only

Forces HTTP/2 connections to network-based object stores.

object-store-http2-max-frame-size

Sets the maximum frame size (in bytes/octets) for HTTP/2 connections.

object-store-request-timeout

Sets the HTTP request timeout for object store requests.

Default: 30s

object-store-max-retries

Defines the maximum number of times to retry a request.

object-store-retry-timeout

Specifies the maximum length of time from the initial request after which no further retries are be attempted.

object-store-cache-endpoint

Sets the endpoint of an S3-compatible, HTTP/2-enabled object store cache.

object-store-tls-allow-insecure

Allows invalid TLS certificates when connecting to object storage.

object-store-tls-ca

Specifies the path to a custom CA certificate file (PEM format) for verifying object store connections. Use this when your object store uses a certificate signed by a private CA.

Logs

• log-filter
• log-destination
• log-format
• query-log-max-entries

log-filter

Sets the filter directive for logs. Use this option to control the verbosity of server logs globally or for specific components.

Log levels

The following log levels are available (from least to most verbose):

Basic usage

To set the log level globally, pass one of the log levels:

influxdb3 serve --log-filter debug

Targeted filtering

Globally enabling debug or trace produces a high volume of log output. For more targeted debugging, you can set different log levels for specific components using the format <global_level>,<component>=<level>.

Debug write buffer operations

influxdb3 serve --log-filter info,influxdb3_write_buffer=debug

Trace WAL operations

influxdb3 serve --log-filter info,influxdb3_wal=trace

Multiple targeted filters

influxdb3 serve --log-filter info,influxdb3_write_buffer=debug,influxdb3_wal=debug

Debug Enterprise storage engine operations

influxdb3 serve --log-filter info,influxdb3_enterprise=debug

Common component names

The following are common component names you can use for targeted filtering:

log-destination

Specifies the destination for logs.

This option supports the following values:

• stdout (default)
• stderr

Default: stdout

log-format

Defines the message format for logs.

This option supports the following values:

• full (default)

Default: full

query-log-max-entries

Defines the maximum number of entries in the query log. Up to this many queries remain in the log before older queries are evicted to make room for new ones.

Default: 1000

Traces

• traces-exporter
• traces-exporter-jaeger-agent-host
• traces-exporter-jaeger-agent-port
• traces-exporter-jaeger-service-name
• traces-exporter-jaeger-trace-context-header-name
• traces-jaeger-debug-name
• traces-jaeger-tags
• traces-jaeger-max-msgs-per-second

traces-exporter

Sets the type of tracing exporter.

Default: none

traces-exporter-jaeger-agent-host

Specifies the Jaeger agent network hostname for tracing.

Default: 0.0.0.0

traces-exporter-jaeger-agent-port

Defines the Jaeger agent network port for tracing.

Default: 6831

traces-exporter-jaeger-service-name

Sets the Jaeger service name for tracing.

Default: iox-conductor

traces-exporter-jaeger-trace-context-header-name

Specifies the header name used for passing trace context.

Default: uber-trace-id

traces-jaeger-debug-name

Specifies the header name used for force sampling in tracing.

Default: jaeger-debug-id

traces-jaeger-tags

Defines a set of key=value pairs to annotate tracing spans with.

traces-jaeger-max-msgs-per-second

Specifies the maximum number of messages sent to a Jaeger service per second.

Default: 1000

DataFusion

• datafusion-num-threads
• datafusion-max-parquet-fanout
• datafusion-use-cached-parquet-loader
• datafusion-config

datafusion-num-threads

Sets the maximum number of DataFusion runtime threads to use.

datafusion-max-parquet-fanout

When multiple Parquet files are required in a sorted way (deduplication for example), specifies the maximum fanout.

Default: 1000

datafusion-use-cached-parquet-loader

Uses a cached Parquet loader when reading Parquet files from the object store.

datafusion-config

Provides custom configuration to DataFusion as a comma-separated list of key:value pairs.

HTTP

• max-http-request-size
• http-bind

max-http-request-size

Specifies the maximum size of HTTP requests. Requires a unit suffix–for example, 10mb.

Default: 10mb

http-bind

Defines the address on which InfluxDB serves HTTP API requests.

Default: 0.0.0.0:8181

Memory

• exec-mem-pool-size
• force-snapshot-mem-threshold

exec-mem-pool-size

Specifies the size of the memory pool used for query processing and data operations. This memory pool is used when InfluxDB 3 Enterprise processes queries and performs internal data management tasks. Provide a value with a unit suffix or as a percentage of the total available memory–for example: 8gb or 10%.

Default: 20%

force-snapshot-mem-threshold

Specifies the threshold for the internal memory buffer. Supports either a percentage (portion of available memory) or a value with a unit suffix–for example: 70% or 1000mb.

Default: 50%

Write-Ahead Log (WAL)

• checkpoint-interval
• wal-flush-interval
• wal-files-per-snapshot
• wal-max-buffered-writes
• snapshotted-wal-files-to-keep
• wal-replay-fail-on-error
• wal-replay-concurrency-limit

checkpoint-interval

Sets the interval for consolidating snapshots into monthly checkpoints for faster server startup. Snapshots accumulate in object storage over time and are not automatically deleted.

Without checkpointing, the server loads individual snapshots on startup. The number of snapshots is determined by the lookback window (gen1-lookback-duration, default 1 month) divided by gen1-duration (default 10 minutes), with a minimum of 100. With default settings, that can be up to ~4,320 snapshots.

With checkpointing enabled, the server periodically consolidates snapshot metadata into checkpoints in object storage. On startup, the server loads one to two checkpoints per calendar month, then loads only snapshots created since the last checkpoint. Enabling checkpointing does not delete old snapshots.

Up to 10 checkpoints load concurrently during startup. The server retains two checkpoints per calendar month and handles month rollovers automatically.

Accepts a duration value–for example: 1h, 30m, 10m.

Default: Not set (disabled)

Example

influxdb3 serve --checkpoint-interval 1h

wal-flush-interval

Specifies the interval to flush buffered data to a WAL file. Writes that wait for WAL confirmation take up to this interval to complete. Use s for seconds or ms for milliseconds. For local disks, 100 ms is recommended.

Default: 1s

wal-files-per-snapshot

Defines the number of WAL files to attempt to remove in a snapshot. This, multiplied by the interval, determines how often snapshots are taken.

Default: 600

wal-max-buffered-writes

Specifies the maximum number of write requests that can be buffered before a flush must be executed and succeed.

Default: 100000

snapshotted-wal-files-to-keep

Specifies the number of snapshotted WAL files to retain in the object store. Flushing the WAL files does not clear the WAL files immediately; they are deleted when the number of snapshotted WAL files exceeds this number.

Default: 300

wal-replay-fail-on-error

Determines whether WAL replay should fail when encountering errors.

Default: false

wal-replay-concurrency-limit

Concurrency limit during WAL replay. Setting this number too high can lead to OOM. The default is dynamically determined.

Default: max(num_cpus, 10)

Compaction

• compaction-row-limit

• compaction-max-num-files-per-plan

• compaction-gen2-duration

• compaction-multipliers

• compaction-cleanup-wait

• compaction-check-interval

• compacted-data-load-concurrency-limit

• compacted-data-skip-file-index

• gen1-duration

compaction-row-limit

Specifies the soft limit for the number of rows per file that the compactor writes. The compactor may write more rows than this limit.

Default: 1000000

compaction-max-num-files-per-plan

Sets the maximum number of files included in any compaction plan.

Default: 500

compaction-gen2-duration

Specifies the duration of the first level of compaction (gen2). Later levels of compaction are multiples of this duration. This value should be equal to or greater than the gen1 duration.

Default: 20m

compaction-multipliers

Specifies a comma-separated list of multiples defining the duration of each level of compaction. The number of elements in the list determines the number of compaction levels. The first element specifies the duration of the first level (gen3); subsequent levels are multiples of the previous level.

Default: 3,4,6,5

compaction-cleanup-wait

Specifies the amount of time that the compactor waits after finishing a compaction run to delete files marked as needing deletion during that compaction run.

Default: 10m

compaction-check-interval

Specifies how often the compactor checks for new compaction work to perform.

Default: 10s

compacted-data-load-concurrency-limit

Specifies the maximum number of concurrent object store fetches while a node loads compacted data (compaction detail and generation detail files), both at startup and when a consumer picks up new compaction summaries.

The default bounds the transient memory used by in-flight downloads and is sized so the load saturates neither a 10 GbE network interface nor the shared object store connection pool (see object-store-connection-limit). Increase the limit for faster startup when the compaction index is large and the host has network headroom; decrease it if the object store throttles the load or memory is tight during startup.

This option isn’t supported in the TOML configuration file; use the command option or environment variable.

Default: 20

compacted-data-skip-file-index

Loads compacted data without building the in-memory file index.

Use this option when the file index has grown too large to fit in host memory and the node can’t start. Without the index, queries can’t prune to a subset of files and instead scan all files in the matching time range, so queries are correct but slower. Pruning generations by time range is unaffected.

The setting applies to the node as a whole: a node started with this option also skips index merges for newly compacted generations, and continues to persist full indexes to the object store for other nodes to use.

This option isn’t supported in the TOML configuration file; use the command option or environment variable.

Default: false

gen1-duration

Specifies the duration that Parquet files are arranged into. Data timestamps land each row into a file of this duration. Supported durations are 1m, 5m, and 10m. These files are known as “generation 1” files, which the compactor can merge into larger generations

.

Default: 10m

Caching

• preemptive-cache-age

• file-cache-size

• parquet-mem-cache-prune-percentage

• parquet-mem-cache-prune-interval

• file-cache-recency

• disable-file-cache

• table-index-cache-max-entries

• table-index-cache-concurrency-limit

• last-value-cache-disable-from-history

• last-cache-eviction-interval

• distinct-value-cache-disable-from-history

• distinct-cache-eviction-interval

preemptive-cache-age

Specifies the interval to prefetch into the Parquet cache during compaction.

Default: 3d

file-cache-size

Specifies the size of the in-memory data file cache. Provide a value with a unit suffix or as a percentage of total available memory–for example, 4gb or 20%.

This is a total budget.

With the Parquet engine, the budget is used entirely by the in-memory Parquet cache. During the storage engine upgrade with hybrid query enabled, the budget is split 50/50 between the hybrid-query Parquet cache and the upgraded engine’s file cache; otherwise, the single active cache receives the full budget.

Default: 20%

parquet-mem-cache-prune-percentage

Specifies the percentage of entries to prune during a prune operation on the in-memory Parquet cache.

Default: 0.1

parquet-mem-cache-prune-interval

Sets the interval to check if the in-memory Parquet cache needs to be pruned.

Default: 1s

file-cache-recency

A duration that specifies

the time window for caching recent data files in memory.

Default: 3d

Only files containing data with a timestamp between now and now - duration are cached when accessed during queries–for example, with a 5h setting:

• Current time: 2024-06-10 15:00:00
• Cache window: Last 5 hours (2024-06-10 10:00:00 to now)

If a query requests data from 2024-06-09 (old) and 2024-06-10 14:00 (recent):

• Cached: data files with data from 2024-06-10 14:00 (within 5-hour window)
• Not cached: data files with data from 2024-06-09 (outside 5-hour window)

disable-file-cache

Disables the in-memory data file cache. By default, the cache is enabled.

This disables data file caching in both the Parquet and upgraded storage engines.

table-index-cache-max-entries

Specifies the maximum number of entries in the table index cache.

Default: 1000

table-index-cache-concurrency-limit

Limits the concurrency level for table index cache operations.

Default: 8

last-value-cache-disable-from-history

Disables populating the last-N-value cache from historical data. If disabled, the cache is still populated with data from the write-ahead log (WAL).

last-cache-eviction-interval

Specifies the interval to evict expired entries from the Last-N-Value cache, expressed as a human-readable duration–for example: 20s, 1m, 1h.

Default: 10s

distinct-value-cache-disable-from-history

Disables populating the distinct value cache from historical data. If disabled, the cache is still populated with data from the write-ahead log (WAL).

distinct-cache-eviction-interval

Specifies the interval to evict expired entries from the distinct value cache, expressed as a human-readable duration–for example: 20s, 1m, 1h.

Default: 10s

query-file-limit

Limits the number of Parquet files a query can access. If a query attempts to read more than this limit, InfluxDB 3 Enterprise returns an error.

Processing Engine

• plugin-dir
• plugin-repo
• virtual-env-location
• package-manager
• restrict-plugin-triggers-to
  • plugin-dir-only

plugin-dir

Specifies the local directory that contains Python plugins and their test files.

Default behavior by deployment type

Disable the Processing Engine

To disable the Processing Engine, ensure plugin-dir is not configured.

Docker: Use INFLUXDB3_UNSET_VARS to unset default environment variables that are preconfigured in the container image.

INFLUXDB3_UNSET_VARS accepts a comma-separated list of environment variable names to unset in the container entrypoint before InfluxDB 3 Enterprise starts. This lets you disable or override image defaults (for example, INFLUXDB3_PLUGIN_DIR, logging, or other configuration variables) without modifying the container image itself.

To disable the default plugin directory, unset INFLUXDB3_PLUGIN_DIR:

docker run -e INFLUXDB3_UNSET_VARS="INFLUXDB3_PLUGIN_DIR" influxdb:3-enterprise

systemd (DEB/RPM): Comment out or remove plugin-dir in the configuration file:

sudo nano /etc/influxdb3/influxdb3-enterprise.conf

# plugin-dir="/var/lib/influxdb3/plugins"

Then restart the service:

sudo systemctl restart influxdb3-enterprise

When the Processing Engine is disabled:

• The Python environment and PyO3 bindings are not initialized
• Plugin-related operations return a “No plugin directory configured” error
• The server runs with reduced resource usage

plugin-repo

Specifies the base URL of the remote repository used when referencing plugins with the gh: prefix. When you create a trigger with a plugin filename starting with gh:, InfluxDB fetches the plugin code from this repository URL.

The URL construction automatically handles trailing slashes—both formats work identically:

• https://example.com/plugins/ (with trailing slash)
• https://example.com/plugins (without trailing slash)

Default: The official InfluxDB 3 plugins repository at https://raw.githubusercontent.com/influxdata/influxdb3_plugins/main/

Example usage

# Use a custom organization repository
influxdb3 serve \
  --plugin-dir ~/.plugins \
  --plugin-repo "https://raw.githubusercontent.com/myorg/influxdb-plugins/main/"

# Use an internal mirror
influxdb3 serve \
  --plugin-dir ~/.plugins \
  --plugin-repo "https://internal.company.com/influxdb-plugins/"

# Set via environment variable
export INFLUXDB3_PLUGIN_REPO="https://custom-repo.example.com/plugins/"
influxdb3 serve --plugin-dir ~/.plugins

virtual-env-location

Specifies the location of the Python virtual environment that the processing engine uses.

package-manager

Specifies the Python package manager that the Processing Engine uses to install plugin dependencies.

This option supports the following values:

• discover (default): Automatically detect and use available package manager (uv or pip)
• pip: Use pip package manager exclusively
• uv: Use uv package manager exclusively
• disabled: Disable automatic package installation (all dependencies must be pre-installed)

Default: discover

Security mode (disabled)

When set to disabled, InfluxDB 3 Enterprise blocks all package installation attempts for security and compliance requirements. The Processing Engine and plugins continue to function normally, but package installation requests (via CLI or API) return a 403 Forbidden error.

This mode is designed for:

• Enterprise security requirements: Prevent arbitrary package installation
• Compliance environments: Control exactly which packages are available
• Air-gapped deployments: Pre-install all dependencies before deployment
• Multi-tenant scenarios: Prevent tenants from installing potentially malicious packages

Example:

# Start InfluxDB 3 with disabled package manager
influxdb3 serve \
  --node-id node0 \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --plugin-dir ~/.plugins \
  --package-manager disabled

For more information about plugins and package management, see Processing Engine plugins.

restrict-plugin-triggers-to

Restrict plugin triggers to one or more trigger types. Provide one or more of wal, schedule, or request.

plugin-dir-only

Only allow plugins that already exist in the configured plugin directory. Blocks plugin installation from any other source.

Cluster Management

• replication-interval
• catalog-sync-interval
• wait-for-running-ingester
• conn-info

replication-interval

Specifies the interval at which data replication occurs between cluster nodes.

Default: 250ms

catalog-sync-interval

Defines how often the catalog synchronizes across cluster nodes.

Default: 10s

wait-for-running-ingester

Specifies how long to wait for a running ingester during startup.

Default: 10s

conn-info

In multi-node deployments, specifies the connection information used to reach the ingester over the internode gRPC port (not the HTTP port). Required for Processing Engine plugin writes from non-ingester nodes, and used together with the --internode-bind-addr option.

Resource Limits

• num-cores

• max-concurrent-queries

• datafusion-num-threads

• num-io-threads - See Global configuration options

• num-database-limit

• num-table-limit

• num-total-columns-per-table-limit

num-cores

Limits the number of CPU cores that the InfluxDB 3 Enterprise process can use when running on systems where resources are shared.

Default: All available cores on the system

Maximum cores allowed is determined by your InfluxDB 3 Enterprise license:

• Trial: up to 256 cores
• At-Home: 2 cores
• Commercial: per contract

When specified, InfluxDB automatically assigns the number of DataFusion threads and IO threads based on the core count.

Default thread assignment logic when num-cores is set:

• 1-2 cores: 1 IO thread, 1 DataFusion thread
• 3 cores: 1 IO thread, 2 DataFusion threads
• 4+ cores: 2 IO threads, (n-2) DataFusion threads

This automatic allocation applies when you don’t explicitly set --num-io-threads and --datafusion-num-threads.

Constraints (Parquet-engine clusters):

• Must be at least 2
• Cannot exceed the number of cores available on the system
• Total thread count from --num-io-threads (global option) and --datafusion-num-threads cannot exceed the num-cores value

max-concurrent-queries

Limits the number of queries that can run concurrently. You can also update the limit at runtime with POST /api/v3/configure/query_concurrency_limit.

datafusion-num-threads

Sets the number of threads allocated to the DataFusion runtime thread pool. DataFusion threads handle:

• Query execution and processing
• Data aggregation and transformation
• Snapshot creation (sort/dedupe operations)
• Parquet file generation

Default:

• Clusters running the upgraded storage engine (the default for new clusters): the licensed core count
• Parquet-engine clusters, if --num-cores is not set: all available cores minus IO threads
• Parquet-engine clusters, if --num-cores is set: automatically determined based on core count (see --num-cores)

Constraints: On Parquet-engine clusters, when used with --num-cores, the sum of --num-io-threads and --datafusion-num-threads cannot exceed the num-cores value. On clusters running the upgraded storage engine, values above the licensed core count are capped with a startup warning.

num-database-limit

Limits the total number of active databases. Default is 100.

num-table-limit

Limits the total number of active tables across all databases. Default is 10000.

num-total-columns-per-table-limit

Limits the total number of columns per table. Default is 500.

Data Lifecycle Management

• gen1-lookback-duration
• retention-check-interval
• delete-grace-period
• hard-delete-default-duration

gen1-lookback-duration

Specifies how far back to look when creating generation 1 Parquet files.

Default: 24h

retention-check-interval

The interval at which retention policies are checked and enforced. Enter as a human-readable time–for example: 30m or 1h.

Default: 30m

delete-grace-period

Specifies the grace period before permanently deleting data.

Default: 24h

hard-delete-default-duration

Sets the default duration for hard deletion of data.

Default: 90d

Telemetry

• disable-telemetry-upload
• telemetry-endpoint

disable-telemetry-upload

Disables the upload of telemetry data to InfluxData.

Default: false

telemetry-endpoint

Specifies the endpoint for telemetry data uploads.

TCP Listeners

• tcp-listener-file-path
• admin-token-recovery-tcp-listener-file-path

tcp-listener-file-path

Specifies the file path for the TCP listener configuration.

admin-token-recovery-tcp-listener-file-path

Specifies the TCP listener file path for admin token recovery operations.