core/configs/server.toml

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

[data_maintenance.archiver]
# Enables or disables the archiver process.
enabled = false

# Kind of archiver to use. Available options: "disk".
kind = "disk"

[data_maintenance.archiver.disk]
# Path for storing the archived data on disk.
path = "local_data/archive"

[data_maintenance.archiver.s3]
# Access key ID for the S3 bucket.
key_id = "123"

# Secret access key for the S3 bucket
key_secret = "secret"

# Name of the S3 bucket.
bucket = "iggy"

# Endpoint of the S3 region.
endpoint = "http://localhost:9000"

# Region of the S3 bucket.
region = "eu-west-1"

# Temporary directory for storing the data before uploading to S3.
tmp_upload_dir = "local_data/s3_tmp"

[data_maintenance.messages]
# Enables or disables the archiver process for closed segments containing messages.
archiver_enabled = false

# Enables or disables the expired message cleaner process.
cleaner_enabled = false

# Interval for running the message archiver and cleaner.
interval = "1 m"

[data_maintenance.state]
# Enables or disables the archiver process for state log.
archiver_enabled = false

# Sets whether the state archiver should overwrite existing log archive or always create a new one.
overwrite = true

# Interval for running the state archiver
interval = "1 m"

# HTTP server configuration
[http]
# Determines if the HTTP server is active.
# `true` enables the server, allowing it to handle HTTP requests.
# `false` disables the server, preventing it from handling HTTP requests.
enabled = true

# Specifies the network address and port for the HTTP server.
# The format is "HOST:PORT". For example, "0.0.0.0:3000" listens on all network interfaces on port 3000.
address = "0.0.0.0:3000"

# Maximum size of the request body in bytes. For security reasons, the default limit is 2 MB.
max_request_size = "2 MB"

# Configuration for Cross-Origin Resource Sharing (CORS).
[http.cors]
# Controls whether CORS is enabled for the HTTP server.
# `true` allows handling cross-origin requests with specified rules.
# `false` blocks cross-origin requests, enhancing security.
enabled = true

# Specifies which HTTP methods are allowed when CORS is enabled.
# For example, ["GET", "POST"] would allow only GET and POST requests.
allowed_methods = ["GET", "POST", "PUT", "DELETE"]

# Defines which origins are permitted to make cross-origin requests.
# An asterisk "*" allows all origins. Specific domains can be listed to restrict access.
allowed_origins = ["*"]

# Lists allowed headers that can be used in CORS requests.
# For example, ["content-type"] permits only the content-type header.
allowed_headers = ["content-type"]

# Headers that browsers are allowed to access in CORS responses.
# An empty array means no additional headers are exposed to browsers.
exposed_headers = [""]

# Determines if credentials like cookies or HTTP auth can be included in CORS requests.
# `true` allows credentials to be included, useful for authenticated sessions.
# `false` prevents credentials, enhancing privacy and security.
allow_credentials = false

# Allows or blocks requests from private networks in CORS.
# `true` permits requests from private networks.
# `false` disallows such requests, providing additional security.
allow_private_network = false

# JWT (JSON Web Token) configuration for HTTP.
[http.jwt]
# Specifies the algorithm used for signing JWTs.
# For example, "HS256" indicates HMAC with SHA-256.
algorithm = "HS256"

# The issuer of the JWT, typically a URL or an identifier of the issuing entity.
issuer = "iggy.apache.org"

# Intended audience for the JWT, usually the recipient or system intended to process the token.
audience = "iggy.apache.org"

# Lists valid issuers for JWT validation to ensure tokens are from trusted sources.
valid_issuers = ["iggy.apache.org"]

# Lists valid audiences for JWT validation to confirm tokens are for the intended recipient.
valid_audiences = ["iggy.apache.org"]

# Expiry time for access tokens.
access_token_expiry = "1 h"

# Tolerance for timing discrepancies during token validation.
clock_skew = "5 s"

# Time before which the token should not be considered valid.
not_before = "0 s"

# Secret key for encoding JWTs.
encoding_secret = "top_secret$iggy123$_jwt_HS256_key#!"

# Secret key for decoding JWTs.
decoding_secret = "top_secret$iggy123$_jwt_HS256_key#!"

# Indicates if the secret key is base64 encoded.
# `true` means the secret is base64 encoded.
# `false` means the secret is in plain text.
use_base64_secret = false

# Metrics configuration for HTTP.
[http.metrics]
# Enable or disable the metrics endpoint.
# `true` makes metrics available at the specified endpoint.
# `false` disables metrics collection.
enabled = true

# Specifies the endpoint for accessing metrics, e.g., "/metrics".
endpoint = "/metrics"

# TLS (Transport Layer Security) configuration for HTTP.
[http.tls]
# Controls the use of TLS for encrypted HTTP connections.
# `true` enables TLS, enhancing security.
# `false` disables TLS, which may be appropriate in secure internal networks.
enabled = false

# Path to the TLS certificate file.
cert_file = "certs/iggy_cert.pem"

# Path to the TLS key file.
key_file = "certs/iggy_key.pem"

# TCP server configuration.
[tcp]
# Determines if the TCP server is active.
# `true` enables the TCP server for handling TCP connections.
# `false` disables it, preventing any TCP communication.
enabled = true

# Defines the network address and port for the TCP server.
# For example, "0.0.0.0:8090" listens on all network interfaces on port 8090.
address = "0.0.0.0:8090"

# Whether to use ipv4 or ipv6
ipv6 = false

# TLS configuration for the TCP server.
[tcp.tls]
# Enables or disables TLS for TCP connections.
# `true` secures TCP connections with TLS.
# `false` leaves TCP connections unencrypted.
enabled = false

# Path to the TLS certificate for TCP.
certificate = "certs/iggy.pfx"

# Password for the TLS certificate, required for accessing the private key.
password = "iggy123"

# Configuration for the TCP socket
[tcp.socket]
# Whether to overwrite the OS-default socket parameters
override_defaults = false

# SO_RCVBUF: maximum size of the receive buffer, can be clamped by the OS
recv_buffer_size = "100 KB"

# SO_SNDBUF: maximum size of the send buffer, can be clamped by the OS
send_buffer_size = "100 KB"

# SO_KEEPALIVE: whether to regularly send a keepalive packet maintaining the connection
keepalive = false

# TCP_NODELAY: enable/disable the Nagle algorithm which buffers data before sending segments
nodelay = false

# SO_LINGER: delay to wait for while data is being transmitted before closing the socket after a
# close or shutdown call has been received
linger = "0 s"

# QUIC protocol configuration.
[quic]
# Controls whether the QUIC server is enabled.
# `true` enables QUIC for fast, secure connections.
# `false` disables QUIC, possibly for compatibility or simplicity.
enabled = true

# Network address and port for the QUIC server.
# For example, "0.0.0.0:8080" binds to all interfaces on port 8080.
address = "0.0.0.0:8080"

# Maximum number of simultaneous bidirectional streams in QUIC.
max_concurrent_bidi_streams = 10_000

# Size of the buffer for sending datagrams in QUIC.
datagram_send_buffer_size = "100 KB"

# Initial Maximum Transmission Unit (MTU) for QUIC connections.
initial_mtu = "8 KB"

# Size of the sending window in QUIC, controlling data flow.
send_window = "100 KB"

# Size of the receiving window in QUIC, controlling data flow.
receive_window = "100 KB"

# Interval for sending keep-alive messages in QUIC.
keep_alive_interval = "5 s"

# Maximum idle time before a QUIC connection is closed.
max_idle_timeout = "10 s"

# QUIC certificate configuration.
[quic.certificate]
# Indicates whether the QUIC certificate is self-signed.
# `true` for self-signed certificates, often used in internal or testing environments.
# `false` for certificates issued by a certificate authority, common in production.
self_signed = true

# Path to the QUIC TLS certificate file.
cert_file = "certs/iggy_cert.pem"

# Path to the QUIC TLS key file.
key_file = "certs/iggy_key.pem"

# Message cleaner configuration.
[message_cleaner]
# Enables or disables the background process for deleting expired messages.
# `true` activates the message cleaner.
# `false` turns it off, messages will not be auto-deleted based on expiry.
enabled = true

# Interval for running the message cleaner.
interval = "1 m"

# Message saver configuration.
[message_saver]
# Enables or disables the background process for saving buffered data to disk.
# `true` ensures data is periodically written to disk.
# `false` turns off automatic saving, relying on other triggers for data persistence.
enabled = true

# Controls whether data saving is synchronous (enforce fsync) or asynchronous.
# `true` for synchronous saving, ensuring data integrity at the cost of performance.
# `false` for asynchronous saving, improving performance but with delayed data writing.
enforce_fsync = true

# Interval for running the message saver.
interval = "30 s"

# Personal access token configuration.
[personal_access_token]
# Sets the maximum number of active tokens allowed per user.
max_tokens_per_user = 100

# Personal access token cleaner configuration.
[personal_access_token.cleaner]
# Enables or disables the token cleaner process.
# `true` activates periodic token cleaning.
# `false` disables it, tokens remain active until manually revoked or expired.
enabled = true

# Interval for running the token cleaner.
interval = "1 m"

# Heartbeat configuration
[heartbeat]
# Enables or disables the client heartbeat verification process.
enabled = false
# Interval for expected client heartbeats
interval = "5 s"

# OpenTelemetry configuration
[telemetry]
# Enables or disables telemetry.
enabled = false
# Service name for telemetry.
service_name = "iggy"

# OpenTelemetry logs configuration
[telemetry.logs]
# Transport for sending logs. Options: "grpc", "http".
transport = "grpc"
# Endpoint for sending logs.
endpoint = "http://localhost:7281/v1/logs"

# OpenTelemetry traces configuration
[telemetry.traces]
# Transport for sending traces. Options: "grpc", "http".
transport = "grpc"
# Endpoint for sending traces.
endpoint = "http://localhost:7281/v1/traces"

# System configuration.
[system]
# Base path for system data storage.
path = "local_data"

# Backup configuration
[system.backup]
# Path for storing backup.
path = "backup"

# Compatibility conversion configuration
[system.backup.compatibility]
# Subpath of the backup directory where converted segment data is stored after compatibility conversion.
path = "compatibility"

[system.state]
# Determines whether to enforce file synchronization on state updates (boolean).
# `true` ensures immediate writing of data to disk for durability.
# `false` allows the OS to manage write operations, which can improve performance.
enforce_fsync = false

# Maximum number of retries for a failed file operation (e.g., append, overwrite).
# This defines how many times the system will attempt the operation before failing.
max_file_operation_retries = 1

# Delay between retries in case of a failed file operation.
# This helps to avoid immediate repeated attempts and can reduce load.
retry_delay = "1 s"

# Runtime configuration.
[system.runtime]
# Path for storing runtime data.
# Specifies the directory where any runtime data is stored, relative to `system.path`.
path = "runtime"

# Logging configuration.
[system.logging]
# Path for storing log files.
path = "logs"

# Level of logging detail. Options: "debug", "info", "warn", "error".
level = "info"

# Maximum size of the log files before rotation.
max_size = "512 MB"

# Time to retain log files before deletion.
retention = "7 days"

# Interval for printing system information to the log.
sysinfo_print_interval = "10 s"

# Encryption configuration
[system.encryption]
# Determines whether server-side data encryption for the messages payloads and state commands is enabled (boolean).
# `true` enables encryption for stored data using AES-256-GCM.
# `false` means data is stored without encryption.
enabled = false

# The encryption key used when encryption is enabled (string).
# Should be a 32 bytes length key, provided as a base64 encoded string.
# This key is required and used only if encryption is enabled.
key = ""

# Compression configuration
[system.compression]
# Allows overriding the default compression algorithm per data segment (boolean).
# `true` permits different compression algorithms for individual segments.
# `false` means all data segments use the default compression algorithm.
allow_override = false

# The default compression algorithm used for data storage (string).
# "none" indicates no compression, other values can specify different algorithms.
default_algorithm = "none"

# Stream configuration
[system.stream]
# Path for storing stream-related data (string).
# Specifies the directory where stream data is stored, relative to `system.path`.
path = "streams"

# Topic configuration
[system.topic]
# Path for storing topic-related data (string).
# Specifies the directory where topic data is stored, relative to `stream.path`.
path = "topics"

# Configures the topic size-based expiry setting.
# "unlimited" or "0" means topics are kept indefinitely.
# A size value in human-readable format determines the maximum size of a topic.
# When a topic reaches this size, the oldest messages are deleted to make room for new ones.
# Messages are removed in full segments, so if segment size is 1 GiB and the topic size is 10 GiB,
# the oldest segment will be deleted upon reaching 10 GiB.
# Example: `max_topic_size = "10 GiB"` means oldest messages in topics will be deleted when they reach 10 GiB.
# Note: this setting can be overwritten with CreateTopic and UpdateTopic requests.
max_size = "unlimited"

# Configures whether the oldest segments are deleted when a topic reaches its maximum size (boolean).
# Note: segments are removed in intervals defined by `system.message_cleaner.interval`.
delete_oldest_segments = false

# Partition configuration
[system.partition]
# Path for storing partition-related data (string).
# Specifies the directory where partition data is stored, relative to `topic.path`.
path = "partitions"

# Determines whether to enforce file synchronization on partition updates (boolean).
# `true` ensures immediate writing of data to disk for durability.
# `false` allows the OS to manage write operations, which can improve performance.
enforce_fsync = false

# Enables checksum validation for data integrity (boolean).
# `true` activates CRC checks when loading data, guarding against corruption.
# `false` skips these checks for faster loading at the risk of undetected corruption.
validate_checksum = false

# The count threshold of buffered messages before triggering a save to disk (integer).
# Specifies how many messages accumulate before persisting to storage.
# Adjusting this can balance between write performance and data durability.
# This is soft limit, actual number of messages may be higher, depending on last batch size.
# Together with `size_of_messages_required_to_save` it defines the threshold of buffered messages.
# Minimum value is 32. Value has to be a multiple of 32 due to minimum
# direct I/O block size (512 bytes) and message index size (16 bytes per message).
# With direct I/O, writes must occur in blocks of at least 512 bytes, which equals 32 message indices.
messages_required_to_save = 1024

# The size threshold of buffered messages before triggering a save to disk (string).
# Specifies how much size of messages accumulate before persisting to storage.
# Adjusting this can balance between write performance and data durability.
# This is soft limit, actual number of messages may be higher, depending on last batch size.
# Together with `messages_required_to_save` it defines the threshold of buffered messages.
# Minimum value is 512 B. Value has to be a multiple of 512 B due to direct I/O requirements.
# Direct I/O operations must align with the underlying storage block size (typically 512 B or 4 KiB).
size_of_messages_required_to_save = "1 MiB"

# Segment configuration
[system.segment]
# Defines the soft limit for the size of a storage segment.
# When a segment reaches this size, a new segment is created for subsequent data.
# Example: if `size` is set "1GiB", the actual segment size may be 1GiB + the size of remaining messages in received batch.
# Maximum size is 1 GiB. Size has to be a multiple of 512 B.
size = "1 GiB"

# Configures the message time-based expiry setting.
# "none" means messages are kept indefinitely.
# A time value in human-readable format determines the lifespan of messages.
# Example: `message_expiry = "2 days 4 hours 15 minutes"` means messages will expire after that duration.
message_expiry = "none"

# Defines the file system confirmation behavior during state updates.
# Controls how the system waits for file write operations to complete.
# Possible values:
# - "wait": waits for the file operation to complete before proceeding.
# - "no_wait": proceeds without waiting for the file operation to finish, potentially increasing performance but at the cost of durability.
server_confirmation = "wait"

# Configures whether expired segments are archived (boolean) or just deleted without archiving.
archive_expired = false

# Controls whether to cache indexes (time and positional) for segment access.
# Possible values:
# - "true" or "all": keeps indexes in memory, speeding up data retrieval at the cost of memory
# - "open_segment": keeps indexes in memory only for the currently open segment
# - "false" or "none": reads indexes from disk, which can conserve memory at the cost of access speed
cache_indexes = "open_segment"

# Message deduplication configuration
[system.message_deduplication]
# Controls whether message deduplication is enabled (boolean).
# `true` activates deduplication, ignoring messages with duplicate IDs.
# `false` treats each message as unique, even if IDs are duplicated.
enabled = false
# Maximum number of ID entries in the deduplication cache (u64).
max_entries = 10000
# Maximum age of ID entries in the deduplication cache in human-readable format.
expiry = "1 m"

# Recovery configuration in case of lost data
[system.recovery]
# Controls whether streams/topics/partitions should be recreated if the expected data for existing state is missing (boolean).
recreate_missing_state = false

# Memory pool configuration
[system.memory_pool]
# Enables or disables the memory pool (boolean).
# `true` enables the memory pool.
# `false` disables the memory pool.
enabled = true

# Size of the memory pool (string).
# Example: "512 MiB" or "1 GiB".
# This defines the maximum, total memory allocated for the memory pool.
# Note: This number has to be multiplication of 4096 (default linux page size).
# Minimum size is 512 MiB due to internal implementation details.
size = "4 GiB"

# Maximum number of buffers in each bucket (u32).
# There are 32 buckets in the memory pool. Each bucket can hold up to this number of buffers
# and holds different buffer sizes, from 256 B to 512 MiB.
# Note: This number has to be a power of 2. Minimum value is 128 due to internal implementation details.
bucket_capacity = 8192