InfluxDB 3 Core configuration options

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

Configure your server

Pass configuration options to the influxdb serve server using either command options or environment variables. Command options take precedence over environment variables.

Example influxdb3 serve command options

influxdb3 serve \
  --node-id node0 \

  --object-store file \
  --data-dir ~/.influxdb3 \
  --log-filter info

Example environment variables

export INFLUXDB3_NODE_IDENTIFIER_PREFIX=my-node
export INFLUXDB3_OBJECT_STORE=file
export INFLUXDB3_DB_DIR=~/.influxdb3
export LOG_FILTER=info

influxdb3 serve

Server configuration options

• General

  • data-dir

  • node-id

  • object-store

• Security

  • tls-key
  • tls-cert
  • tls-minimum-versions
  • without-auth
  • disable-authz
  • admin-token-recovery-http-bind
  • admin-token-file

• 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

• Google Cloud Service

  • google-service-account

• Microsoft Azure

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

• Object Storage

  • bucket
  • object-store-connection-limit
  • object-store-http2-only
  • object-store-http2-max-frame-size
  • object-store-max-retries
  • object-store-retry-timeout
  • object-store-cache-endpoint

• Logs

  • log-filter
  • log-destination
  • log-format
  • query-log-size

• 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

• DataFusion

  • datafusion-num-threads
  • datafusion-runtime-type
  • datafusion-runtime-disable-lifo-slot
  • datafusion-runtime-event-interval
  • datafusion-runtime-global-queue-interval
  • datafusion-runtime-max-blocking-threads
  • datafusion-runtime-max-io-events-per-tick
  • datafusion-runtime-thread-keep-alive
  • datafusion-runtime-thread-priority
  • datafusion-max-parquet-fanout
  • datafusion-use-cached-parquet-loader
  • datafusion-config

• HTTP

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

• Memory

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

• Write-Ahead Log (WAL)

  • wal-flush-interval
  • wal-snapshot-size
  • wal-max-write-buffer-size
  • snapshotted-wal-files-to-keep
  • wal-replay-fail-on-error
  • wal-replay-concurrency-limit

• Compaction

  • gen1-duration

• Caching

  • preemptive-cache-age

  • parquet-mem-cache-size

  • parquet-mem-cache-prune-percentage

  • parquet-mem-cache-prune-interval

  • parquet-mem-cache-query-path-duration

  • disable-parquet-mem-cache

  • table-index-cache-max-entries

  • table-index-cache-concurrency-limit

  • last-cache-eviction-interval

  • distinct-cache-eviction-interval

  • query-file-limit

• Processing Engine

  • plugin-dir
  • virtual-env-location
  • package-manager

• Data Lifecycle Management

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

• Telemetry

  • telemetry-disable-upload
  • telemetry-endpoint

• TCP Listeners

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

General

• data-dir

• node-id

• object-store

• query-file-limit

data-dir

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

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.

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)

Security

• tls-key
• tls-cert
• tls-minimum-versions
• without-auth
• disable-authz
• admin-token-recovery-http-bind
• admin-token-file

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 and admin token offline
influxdb3 create token \
  --admin \
  --name "example-admin-token" \
  --expiry 1d \
  --offline \
  --output-file 
./path/to/admin-token.json

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

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-max-retries
• object-store-retry-timeout
• object-store-cache-endpoint

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-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.

Logs

• log-filter
• log-destination
• log-format
• query-log-size

log-filter

Sets the filter directive for logs.

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-size

Defines the size of 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-runtime-type
• datafusion-runtime-disable-lifo-slot
• datafusion-runtime-event-interval
• datafusion-runtime-global-queue-interval
• datafusion-runtime-max-blocking-threads
• datafusion-runtime-max-io-events-per-tick
• datafusion-runtime-thread-keep-alive
• datafusion-runtime-thread-priority
• 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-runtime-type

Specifies the DataFusion tokio runtime type.

This option supports the following values:

• current-thread
• multi-thread (default)
• multi-thread-alt

Default: multi-thread

datafusion-runtime-disable-lifo-slot

Disables the LIFO slot of the DataFusion runtime.

This option supports the following values:

• true
• false

datafusion-runtime-event-interval

Sets the number of scheduler ticks after which the scheduler of the DataFusion tokio runtime polls for external events–for example: timers, I/O.

datafusion-runtime-global-queue-interval

Sets the number of scheduler ticks after which the scheduler of the DataFusion runtime polls the global task queue.

datafusion-runtime-max-blocking-threads

Specifies the limit for additional threads spawned by the DataFusion runtime.

datafusion-runtime-max-io-events-per-tick

Configures the maximum number of events processed per tick by the tokio DataFusion runtime.

datafusion-runtime-thread-keep-alive

Sets a custom timeout for a thread in the blocking pool of the tokio DataFusion runtime.

datafusion-runtime-thread-priority

Sets the thread priority for tokio DataFusion runtime workers.

Default: 10

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.

Default: 10485760

http-bind

Defines the address on which InfluxDB serves HTTP API requests.

Default: 0.0.0.0:8181

Memory

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

exec-mem-pool-bytes

Specifies the size of memory pool used during query execution. Can be given as absolute value in bytes or as a percentage of the total available memory–for example: 8000000000 or 10%).

Default: 8589934592

force-snapshot-mem-threshold

Specifies the threshold for the internal memory buffer. Supports either a percentage (portion of available memory) or absolute value in MB–for example: 70% or 1000.

Default: 70%

Write-Ahead Log (WAL)

• wal-flush-interval
• wal-snapshot-size
• wal-max-write-buffer-size
• snapshotted-wal-files-to-keep
• wal-replay-fail-on-error
• wal-replay-concurrency-limit

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.

Default: 1s

wal-snapshot-size

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-write-buffer-size

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

Sets the maximum number of concurrent WAL replay operations.

Default: 16

Compaction

• gen1-duration

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 that the compactor in InfluxDB 3 Enterprise can merge into larger generations.

Default: 10m

Caching

• preemptive-cache-age

• parquet-mem-cache-size

• parquet-mem-cache-prune-percentage

• parquet-mem-cache-prune-interval

• parquet-mem-cache-query-path-duration

• disable-parquet-mem-cache

• table-index-cache-max-entries

• table-index-cache-concurrency-limit

• last-cache-eviction-interval

• distinct-cache-eviction-interval

preemptive-cache-age

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

Default: 3d

parquet-mem-cache-size

Specifies the size of the in-memory Parquet cache in megabytes (MB).

Default: 1000

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

parquet-mem-cache-query-path-duration

Specifies

the time window for caching recent Parquet files in memory. Default is 5h.

Only files containing data with a timestamp between now and now - duration are cached when accessed during queries–for example, with the default 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: Parquet files with data from 2024-06-10 14:00 (within 5-hour window)
• Not cached: Parquet files with data from 2024-06-09 (outside 5-hour window)

disable-parquet-mem-cache

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

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-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-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 Core returns an error.

Default: 432

With the default 432 setting and the default gen1-duration setting of 10 minutes, queries can access up to a 72 hours of data, but potentially less depending on whether all data for a given 10 minute block of time was ingested during the same period.

You can increase this limit to allow more files to be queried, but be aware of the following side-effects:

• Degraded query performance for queries that read more Parquet files
• Increased memory usage
• Your system potentially killing the influxdb3 process due to Out-of-Memory (OOM) errors
• If using object storage to store data, many GET requests to access the data (as many as 2 per file)

Processing Engine

• plugin-dir
• virtual-env-location
• package-manager

plugin-dir

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

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.

This option supports the following values:

• discover (default): Automatically discover available package manager
• pip: Use pip package manager
• uv: Use uv package manager

Default: discover

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

Defines how often the system checks for data that should be deleted according to retention policies.

Default: 1h

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

• telemetry-disable-upload
• telemetry-endpoint

telemetry-disable-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.