Agent Configuration

The agent is configured entirely via environment variables. No YAML editing is required for standard deployments.

Environment variables

Required

Variable	Description
`LOGYSTERA_ENTITY_TOKEN`	Your entity's public token. Get from the Logystera dashboard → Entity → Credentials.
`LOGYSTERA_ENTITY_SECRET`	Your entity's HMAC signing secret. Never expose this value.
`LOGYSTERA_CLIENT_ID`	A unique identifier for this agent instance. Used in log context. No spaces.

Gateway

Variable	Default	Description
`LOGYSTERA_GATEWAY_URL`	`https://gateway.logystera.com/v1/ingest`	Gateway endpoint. Do not change unless instructed.

Agent identification

These values appear in the Logystera dashboard and alert context. Use them to identify where a signal came from.

Variable	Default	Description
`LOGYSTERA_CUSTOMER_ID`	`default_customer`	Your organisation name or slug.
`LOGYSTERA_CLUSTER_ID`	`default_cluster`	Vault cluster identifier (e.g. `vault-prod`, `vault-dr`).
`LOGYSTERA_NODE_ID`	`default_node`	Individual node identifier (e.g. `vault-node-1`). Required for multi-node clusters.
`LOGYSTERA_ENVIRONMENT`	`dev`	Deployment environment (e.g. `production`, `staging`).

Log source

Variable	Default	Description
`LOGYSTERA_LOG_PATH`	`/var/log/vault/audit.log`	Absolute path to the Vault audit log file inside the container (Docker) or on the host (systemd).

Docker-specific

Variable	Default	Description
`HOST_VAULT_LOG_DIR`	`/var/log/vault`	Host directory mounted read-only into the container at `/var/log/vault`. Only used in `docker-compose.yml`.

Fluentd tuning

The generated fluent.conf (or Docker entrypoint config) controls batching and delivery behaviour. These settings do not require changes for most deployments.

Batch settings

Parameter	Default	Description
`batch_size`	`50`	Number of log events to accumulate before flushing.
`flush_interval`	`5` (seconds)	Maximum time to wait before flushing a partial batch.

Events are sent when either limit is reached first.

Buffer settings

Parameter	Default	Description
`flush_interval`	`5s`	How often the output buffer is flushed to the gateway.
`retry_forever`	`true`	Keep retrying indefinitely on gateway errors. Events are not dropped.
`retry_max_interval`	`300` (seconds)	Maximum backoff interval between retries.
`chunk_limit_size`	`4MB`	Maximum size of a single buffer chunk.
`total_limit_size`	`512MB`	Maximum total buffer size on disk.

The buffer is file-backed and persisted at /var/log/logystera-agent/gateway-buffer. Events survive agent restarts.

HTTP timeouts

Parameter	Default	Description
`open_timeout`	`5` (seconds)	TCP connection timeout to the gateway.
`read_timeout`	`10` (seconds)	HTTP response timeout.
`ssl_verify`	`true`	Verify the gateway's TLS certificate. Do not disable in production.

Manual Fluentd configuration

For advanced deployments (non-standard log paths, multiple sources, custom tags), you can write a custom fluent.conf.

The full pipeline structure:

# SOURCE: read Vault audit log
<source>
  @type tail
  path /var/log/vault/audit.log
  pos_file /var/log/logystera-agent/audit.pos
  tag vault.audit
  read_from_head false

  <parse>
    @type json
  </parse>
</source>

# FILTER: batch events
<filter vault.audit>
  @type logystera_batch

  client_id vault-prod-agent
  customer_id acme-corp
  cluster_id vault-prod
  node_id vault-node-1
  environment production
  application vault
  name vault_audit_logs
  log_type audit
  emit_tag vault.audit.batch

  batch_size 50
  flush_interval 5
</filter>

# OUTPUT: send to gateway
<match vault.audit.batch>
  @type logystera_gateway

  endpoint https://gateway.logystera.com/v1/ingest
  entity_token YOUR_TOKEN
  entity_secret YOUR_SECRET

  payload_schema vault.events.v1

  <buffer>
    @type file
    path /var/log/logystera-agent/gateway-buffer
    flush_interval 5s
    retry_forever true
    retry_max_interval 300
    chunk_limit_size 4m
    total_limit_size 512m
  </buffer>
</match>

# FALLBACK: dead-letter queue for unmatched events
<match vault.audit.**>
  @type file
  path /var/log/logystera-agent/dlq
</match>

For systemd deployments, place the custom config at /etc/logystera-agent/fluent.conf. The service loads this file on start.

Multi-source configuration

To tail multiple audit log files (e.g. multiple Vault nodes on the same host, or additional log sources):

<source>
  @type tail
  path /var/log/vault/node1/audit.log
  pos_file /var/log/logystera-agent/node1.pos
  tag vault.audit.node1
  <parse>
    @type json
  </parse>
</source>

<source>
  @type tail
  path /var/log/vault/node2/audit.log
  pos_file /var/log/logystera-agent/node2.pos
  tag vault.audit.node2
  <parse>
    @type json
  </parse>
</source>

# Apply different node_id per source
<filter vault.audit.node1>
  @type logystera_batch
  node_id vault-node-1
  # ... other params
</filter>

<filter vault.audit.node2>
  @type logystera_batch
  node_id vault-node-2
  # ... other params
</filter>