Global Configurations

The global configuration file for rekuiper is $kuiper/etc/kuiper.yaml. The file uses YAML syntax.

You can override YAML configurations using environment variables. Environment variables take precedence over file settings. Format variable names using the KUIPER__ prefix followed by YAML path keys separated by double underscores (__):

KUIPER__BASIC__DEBUG=true

Basic Configuration Options

The basic section configures runtime logging, network binding, and security policies:

basic:
  # debug | info | warn | error | fatal | panic
  loglevel: info 
  # true | false: enables verbose debug logging
  debug: false
  # true | false: outputs logs to stdout console
  consoleLog: false
  # true | false: outputs logs to the log file
  fileLog: true
  # syslog settings
  syslog:
    enable: false
    network: udp
    address: localhost:514
    level: info
    tag: kuiper
  # Maximum file size in bytes before rotation
  rotateSize: 10485760 # 10 MB
  # Maximum number of rotated log files to retain
  rotateCount: 3
  # Rotation interval in hours
  rotateTime: 24
  # Maximum file retention duration in hours
  maxAge: 72
  # Case sensitivity for SQL processing
  ignoreCase: false
  sql:
    # Max connections per database instance group; 0 = unlimited
    maxConnections: 0
  # Interval for rule schedule reconciliation
  rulePatrolInterval: 10s
  # Storage backend for configurations: file or kv
  cfgStorageType: file
  # Log each REST API invocation
  enableRestAuditLog: false
  # Allow rules to connect to private network addresses
  enablePrivateNet: false
  # Allow APIs to access files outside data/uploads
  allowExternalFileAccess: false

Security Options

enablePrivateNet

The enablePrivateNet option determines whether rules and sinks can connect to private networks (such as localhost or 127.0.0.1). Default is false for security.

WARNING

Since version 2.4.0, enablePrivateNet defaults to false. The engine blocks connections to private network addresses by default. If your rules require local network access (such as local REST services or edge brokers), you must set this value to true.

allowExternalFileAccess

The allowExternalFileAccess option specifies whether file access APIs (such as file:// URIs) can read files outside the data/uploads directory. Default is false to prevent path traversal vulnerabilities.

WARNING

When allowExternalFileAccess is false, file access is strictly restricted to data/uploads. Set to true only if you require access to other host filesystem paths.

ignoreCase

The ignoreCase option controls case sensitivity in SQL processing. When false, the engine enforces case matching for column names to optimize parsing performance. Default is false.

Logging Configuration

basic:
  loglevel: info 
  debug: false
  consoleLog: false
  fileLog: true
  logDisableTimestamp: false
  rotateTime: 24
  maxAge: 72

When debug is true, the engine forces log output to debug level regardless of loglevel. Set logDisableTimestamp to true when forwarding logs to external aggregators that inject timestamps.

System Log (syslog)

Enable syslog forwarding by setting basic.syslog.enable: true or by setting the environment variable KuiperSyslogKey=true.

syslog:
  enable: false
  network: udp
  address: localhost:514
  level: info
  tag: kuiper

If you leave network and address empty, rekuiper connects to the local system syslog daemon.

Log File Rotation

When fileLog is enabled, the engine rotates logs by size or elapsed time.

Rotate by Size

rotateSize: 10485760 # 10 MB
rotateCount: 3

When the file size exceeds rotateSize, the engine rotates the file. The engine retains up to rotateCount archive files.

Rotate by Time

rotateTime: 24
maxAge: 72

The engine splits log files every rotateTime hours and deletes archives older than maxAge hours.

Global Timezone

timezone: UTC

Specify a timezone name from the IANA Time Zone Database. If empty, the engine uses UTC. Set to Local to adopt the host system timezone.

NOTE

In Alpine Linux containers, you must install tzdata (apk add tzdata) to provide timezone definitions.

CLI Network Binding

basic:
  ip: 0.0.0.0
  port: 20498

Configures the listening address and TCP port for the rekuiper CLI server daemon.

REST Service Configuration

basic:
  restIp: 0.0.0.0
  restPort: 9081
  restTls:
    certfile: /var/https-server.crt
    keyfile: /var/https-server.key

• restPort: The HTTP port for the REST API server.
• restTls: Paths to TLS certificates and private keys. When configured, the REST API listens on HTTPS.

REST Authentication

basic:
  authentication: false

When true, rekuiper requires JWT RSA256 tokens for REST API calls. Refer to REST Authentication.

Rule Patrol Interval

basic:
  rulePatrolInterval: "10s"

Specifies the reconciliation interval used by the internal scheduler to inspect and trigger periodic rules.

Prometheus Metrics Export

basic:
  prometheus: true
  prometheusPort: 20499

When enabled, rekuiper exports Prometheus metrics on http://localhost:20499/metrics. You can set prometheusPort to match restPort to serve metrics through the REST API port.

Plugin Hosts (Legacy Compatibility)

NOTE

Go C-shared native dynamic plugins (.so) are not supported in rekuiper. Built-in connectors (including Kafka, SQL, Redis, and WebSocket) are compiled into the core engine. Custom functions and extensions run via WebAssembly (Wasm) or external service microservices.

In legacy installations, pluginHosts specifies the repository URL hosting prebuilt native plugins:

Plugin Type	Legacy Plugins
source	random, zmq
sink	file, image, influx, redis, tdengine, zmq
function	accumulateWordCount, countPlusOne, echo, geohash, image, labelImage

Sink Cache Configuration

Configure default caching behavior for output sinks. You can override these settings at the rule level. Refer to Sink Caching.

sink:
  enableCache: false
  memoryCacheThreshold: 1024
  maxDiskCache: 1024000
  bufferPageSize: 256
  resendInterval: 0
  cleanCacheAtStop: false

• enableCache: Enables or disables disk/memory sink caching.
• memoryCacheThreshold: Maximum message count retained in memory before writing to disk.
• maxDiskCache: Maximum message count retained in disk storage.
• bufferPageSize: Message batch size per disk read/write operation.
• resendInterval: Retransmission interval in milliseconds.
• cleanCacheAtStop: Clears cached data when the rule stops.

State and Configuration Storage

basic:
  cfgStorageType: file

Set cfgStorageType to kv to store configuration data in the database backend defined under store.

Store Settings

store:
  type: sqlite
  extStateType: redis
  redis:
    host: localhost
    port: 6379
    password: kuiper
    timeout: 1000
    connectionSelector: edgex.redismsgbus
  sqlite:
    name: sqliteKV.db

• type: Database backend for internal state (sqlite, redis, or fdb).
• extStateType: Storage backend queried by SQL get_keyed_state.
• sqlite.name: SQLite database filename (defaults to sqliteKV.db).
• redis.connectionSelector: Reuses connection credentials defined in etc/connections/connection.yaml.

Portable Plugin Runtime

Configure execution parameters for Python portable plugins:

portable:
  pythonBin: python
  initTimeout: 5000
  sendTimeout: 5000
  recvTimeout: 5000

• pythonBin: Path to the Python executable.
• initTimeout: Initialization timeout in milliseconds.
• sendTimeout: IPC message send timeout in milliseconds.
• recvTimeout: IPC message receive timeout in milliseconds.

Ruleset Provisioning

rekuiper supports automatic provisioning on first startup. Place a ruleset file named init.json into the etc directory. The engine loads this ruleset once during initial startup.

FoundationDB Storage Backend

To use FoundationDB as the metadata storage engine:

1. Install FoundationDB client libraries on the host. Refer to the FoundationDB Documentation.
2. Download matching Go bindings in the rekuiper directory:

go get github.com/apple/foundationdb/bindings/[email protected]

3. Compile the binary using make build_with_fdb.
4. Configure store settings in etc/kuiper.yaml:

store:
  type: fdb
  extStateType: fdb
  fdb:
    path: /etc/foundationdb/fdb.cluster