Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Plugin settings

Setup settings

The Setup plugin is configured through settings in opensearch.yml. All settings use the plugins.setup prefix.

  • plugins.setup.timeout (Integer, default 30, range 5–120) — timeout in seconds for index and search operations.
  • plugins.setup.backoff (Integer, default 15, range 5–60) — delay in seconds for the retry mechanism involving initialization tasks.
  • plugins.setup.max_retries (Integer, default 1, range 0–10) — number of times an initialization task that timed out is re-attempted, each attempt separated by plugins.setup.backoff. 0 disables retrying. The budget is per task: each index, index template and ISM policy gets its own. When it runs out the exception is rethrown, initialization stops, every index registered after the failing one is skipped, and the setup status is marked failed. Raise it on clusters where a cluster-manager election, and therefore the first index creation, routinely outlasts the default single re-attempt.
  • plugins.setup.settings_update.enabled (Boolean, default true) — when false, the settings update endpoint (PUT /_plugins/_setup/settings) returns 403 Forbidden for every caller, regardless of role. See Protecting sensitive configuration for the full disable-endpoint pattern shared with Content Manager.

Content Manager settings

The Content Manager plugin is configured through settings in opensearch.yml. All settings use the plugins.content_manager prefix.

  • plugins.content_manager.cti.api (String, default https://api.pre.cloud.wazuh.com/api/v1) — base URL for the Wazuh CTI API. Covers both the catalog endpoints (snapshots, changes, plans) and the CTI Console ones (instance registration, environment lookup, resource-token exchange).

  • plugins.content_manager.catalog.sync_interval (Integer, default 60, range 10–1440, dynamic) — interval, in minutes, between scheduled synchronizations.

  • plugins.content_manager.setup_wait.max_retries (Integer, default 4, range 0–10) — number of retries the catalog sync job performs while waiting for the Setup plugin to report readiness on startup, before giving up until the next scheduled sync.

  • plugins.content_manager.setup_wait.backoff_base_seconds (Integer, default 20, range 1–120) — base delay, in seconds, for the exponential backoff between those retries (delay for retry n is base * 2^n; with the defaults, 20s/40s/80s/160s = 300s / 5 min worst case).

  • plugins.content_manager.max_items_per_bulk (Integer, default 1000, range 10–1000) — maximum documents per bulk indexing request.

  • plugins.content_manager.max_concurrent_bulks (Integer, default 5, range 1–5) — maximum concurrent bulk operations.

  • plugins.content_manager.max_bulk_bytes (Long, default 5242880 / 5 MB, range 1048576–104857600 / 1–100 MB) — maximum request body size, in bytes, for a single bulk indexing request.

  • plugins.content_manager.logtest.max_body_bytes (Long, default 1048576 / 1 MiB, range 1024–16777216 / 1 KiB–16 MiB, dynamic) — maximum size, in bytes, of a logtest request body (POST /logtest, /logtest/normalization, /logtest/detection). Requests whose body exceeds this are rejected with HTTP 413 at the REST layer, before parsing or dispatch, so an oversized event cannot be amplified into the response and exhaust the indexer’s heap.

  • plugins.content_manager.client.timeout (Long, default 10, range 10–50) — HTTP client timeout in seconds for CTI API requests.

  • plugins.content_manager.client.max_retries (Integer, default 3, range 0–10) — number of times a CTI API request is retried after an HTTP 429 (Too Many Requests) response, before the 429 is returned to the caller.

  • plugins.content_manager.client.retry_backoff_base_seconds (Integer, default 30, range 1–300) — base delay, in seconds, for the exponential backoff used between 429 retries when the response carries no usable Retry-After header (delay for retry n is base * 2^n).

  • plugins.content_manager.pit_keepalive (Long, default 120, range 60–600) — point-in-time keepalive in seconds used during paginated index scans.

  • plugins.content_manager.engine.mock (Boolean, default false) — bypasses real Engine socket calls, returning mocked responses instead. Intended for testing only.

  • plugins.content_manager.catalog.update_on_start (Boolean, default true) — trigger content sync when the plugin starts.

  • plugins.content_manager.catalog.update_on_schedule (Boolean, default true, dynamic) — enable the periodic sync job. When false the job is disabled and any scheduled run is refused, so no content is fetched from Wazuh CTI on a schedule. On-demand updates (POST /update) are unaffected — they are controlled by plugins.content_manager.catalog.update_on_demand.

  • plugins.content_manager.catalog.ruleset (String, default "") — full CTI consumer URL for ruleset content.

  • plugins.content_manager.catalog.iocs (String, default "") — full CTI consumer URL for IoC content.

  • plugins.content_manager.catalog.vulnerabilities (String, default "") — full CTI consumer URL for vulnerabilities content.

  • plugins.content_manager.catalog.create_detectors (Boolean, default true) — automatically create Ruleset Management detectors from CTI content.

  • plugins.content_manager.telemetry.enabled (Boolean, default true, dynamic) — enable or disable the daily Update check service ping.

  • plugins.content_manager.catalog.update_on_demand (Boolean, default true) — when false, on-demand content updates (POST /update) return 403 Forbidden for every caller, regardless of role.

  • plugins.content_manager.catalog.policy_update.enabled (Boolean, default true) — when false, policy updates (PUT /policy/{space}) return 403 Forbidden for every caller, regardless of role.

  • plugins.content_manager.max_integrations (Integer, default 100, minimum 0, no upper bound, dynamic) — maximum number of integrations that can be created. Requests that would exceed this limit are rejected with HTTP 400.

  • plugins.content_manager.max_decoders (Integer, default 200, minimum 0, no upper bound, dynamic) — maximum number of decoders that can be created. Requests that would exceed this limit are rejected with HTTP 400.

  • plugins.content_manager.max_rules (Integer, default 200, minimum 0, no upper bound, dynamic) — maximum number of rules that can be created. Requests that would exceed this limit are rejected with HTTP 400.

  • plugins.content_manager.max_kvdbs (Integer, default 100, minimum 0, no upper bound, dynamic) — maximum number of KVDBs that can be created. Requests that would exceed this limit are rejected with HTTP 400.

  • plugins.content_manager.max_filters (Integer, default 100, minimum 0, no upper bound, dynamic) — maximum number of filters that can be created per space. Requests that would exceed this limit are rejected with HTTP 400.

  • plugins.content_manager.cti.console.timeout (Integer, default 5, range 1–120) — request timeout, in seconds, for CTI Console calls (instance registration, plans, token exchange). The catalog client has its own timeout in plugins.content_manager.client.timeout; the Console endpoints resolve against plugins.content_manager.cti.api, so moving that setting moves both services.

  • plugins.content_manager.bulk.retry.shed.max_retries (Integer, default 3, range 0–10, dynamic) — number of times a bulk operation the cluster shed under load (circuit breaker trip, indexing-pressure rejection, HTTP 429/503) is re-submitted before its documents are counted as dropped.

  • plugins.content_manager.bulk.retry.shed.initial_backoff_millis (Long, default 1000, range 100–60000, dynamic) — delay, in milliseconds, before the first re-submission of a shed bulk operation. Each subsequent retry doubles it, capped at the max backoff.

  • plugins.content_manager.bulk.retry.shed.max_backoff_millis (Long, default 30000, range 100–60000, dynamic) — ceiling, in milliseconds, for the exponential backoff between shed bulk re-submissions.

  • plugins.content_manager.bulk.retry.topology.max_retries (Integer, default 5, range 0–10, dynamic) — number of times a bulk operation deferred by a transient cluster-topology change (an index recreated mid-load, a shard left unavailable, the node holding it leaving) is re-submitted before its documents are counted as dropped. The default was sized to outlast one rolling restart; raise it on clusters where a restart takes longer, otherwise a synchronization running across a restart drops documents.

  • plugins.content_manager.bulk.retry.topology.initial_backoff_millis (Long, default 5000, range 100–60000, dynamic) — delay, in milliseconds, before the first re-submission of a topology-deferred bulk operation. Each subsequent retry doubles it, capped at the max backoff.

  • plugins.content_manager.bulk.retry.topology.max_backoff_millis (Long, default 30000, range 100–60000, dynamic) — ceiling, in milliseconds, for the exponential backoff between topology-deferred bulk re-submissions.

  • plugins.content_manager.job_schedule.max_retries (Integer, default 3, range 0–10) — number of attempts to register a periodic job with the job scheduler before giving up and logging an error.

  • plugins.content_manager.job_schedule.retry_backoff_seconds (Integer, default 15, range 1–300) — base delay, in seconds, for the linear backoff between job-registration attempts (delay before attempt n is base * n).

  • plugins.content_manager.resource_lock.max_retries (Integer, default 20, range 1–100, dynamic) — number of attempts to acquire the resource-creation lock before the request is rejected with HTTP 503.

  • plugins.content_manager.resource_lock.retry_backoff_millis (Long, default 100, range 10–10000, dynamic) — delay, in milliseconds, between resource-creation lock acquisition attempts.

  • plugins.content_manager.resource_lock.stale_threshold_millis (Long, default 30000, range 5000–600000, dynamic) — age, in milliseconds, past which a held resource-creation lock is treated as orphaned by a crashed node and stolen by the next caller. Set this to the same value on every node, and above the worst-case resource-creation time: the lock is cluster-wide but the setting is read from each node’s own configuration, so nodes that disagree can both consider themselves inside the critical section. The holder never renews the lock, so a value below the time a creation takes lets every concurrent request steal it and the mutex stops working.

  • plugins.content_manager.user_overrides.max_update_attempts (Integer, default 3, range 1–20, dynamic) — number of attempts to write the shared user-overrides registry document before giving up. The registry is a single document, so concurrent writers are serialized optimistically and each version conflict re-reads and re-applies.

  • plugins.content_manager.integration.max_update_attempts (Integer, default 5, range 1–20, dynamic) — number of attempts to update an integration document on a version conflict, when linking or unlinking a resource, before the operation fails.

  • plugins.content_manager.engine.socket_path (String, default /usr/share/wazuh-indexer/engine/sockets/engine-api-http.sock) — filesystem path of the Unix domain socket the Engine API listens on.

  • plugins.content_manager.engine.reload_timeout_minutes (Integer, default 10, range 1–1440) — upper bound, in minutes, on how long a single Engine content reload may stay in flight. It guards against a lost callback wedging the single-flight guard forever.

  • plugins.content_manager.engine.not_ready_grace_minutes (Integer, default 5, range 1–1440) — how long, in minutes, the content indices may stay unable to serve reads before the deferral is escalated from a debug line to a warning.

  • plugins.content_manager.security_analytics.sync_timeout_seconds (Integer, default 60, range 1–3600) — how long, in seconds, a Ruleset Management bulk synchronization step (uploading rules or integrations) may run before it is abandoned and the pass reported as unsuccessful.

  • plugins.content_manager.security_analytics.detector_timeout_seconds (Integer, default 30, range 1–3600) — how long, in seconds, to wait for the first detector creation to complete.

  • plugins.content_manager.security_analytics.cleanup_timeout_seconds (Integer, default 120, range 120–3600) — how long, in seconds, to wait for the deletion of stale Ruleset Management rules and integrations after a content swap. The floor is the default: on timeout the deletion is not retried, so lowering it would make stale resources routine rather than exceptional.

  • plugins.content_manager.security_analytics.detector_interval (Integer, default 2, range 1–10080, dynamic) — detector schedule interval, in minutes, applied when the CTI integration document does not specify one, or specifies one outside the bounds Ruleset Management accepts.

  • plugins.content_manager.update_sub_batch_size (Integer, default 50, range 1–1000) — maximum number of UPDATE offsets batched into a single MultiGet + bulk request while applying a catalog changeset.

  • plugins.content_manager.offset_flush_interval (Integer, default 10, range 1–1000) — how many batches (changeset application) or bulks (snapshot load) are processed between consumer-offset checkpoints. A smaller value narrows the window of work replayed after a crash, at the cost of more writes to the consumer-state document.

  • plugins.content_manager.search_page_size (Integer, default 10000, range 100–10000) — page size used by the paginated IoC reconciliation scan. Lower values mean more round trips over the same documents, not fewer documents.

Settings marked dynamic can be changed on a running cluster and take effect on the next operation:

curl -sk -u admin:$WAZUH_INDEXER_ADMIN_PASSWORD -X PUT "https://127.0.0.1:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
  "persistent": {
    "plugins.content_manager.bulk.retry.topology.max_retries": 8,
    "plugins.content_manager.bulk.retry.topology.max_backoff_millis": 45000
  }
}'

Ruleset Management settings

The Ruleset Management plugin is configured through settings in opensearch.yml. All node-scope settings use the plugins.security_analytics prefix. Almost every setting is dynamic and can be changed at runtime via the Cluster Settings API.

  • plugins.security_analytics.alert_finding_enabled (Boolean, default false) — enable rollover for the finding history indices, and keep the current write index out of the retention sweep while it is on. Retention deletion itself runs either way. It does not make raw findings be stored; that is the Alerting plugin’s plugins.alerting.alert_finding_enabled.
  • plugins.security_analytics.alert_finding_max_docs (Long, default 1000, minimum 0) — Deprecated. Maximum document count for a finding history index before rollover.
  • plugins.security_analytics.alert_finding_rollover_period (Time, default 12h) — how often the finding history rollover job runs.
  • plugins.security_analytics.alert_history_enabled (Boolean, default false) — enable rollover for the alert history indices, and keep the current write index out of the retention sweep while it is on. Retention deletion itself runs either way.
  • plugins.security_analytics.alert_history_max_age (Time, default 30d) — maximum age of an alert history index before rollover.
  • plugins.security_analytics.alert_history_max_docs (Long, default 1000, minimum 0) — maximum document count for an alert history index before rollover.
  • plugins.security_analytics.alert_history_retention_period (Time, default 60d) — retention period after which alert history indices are deleted.
  • plugins.security_analytics.alert_history_rollover_period (Time, default 12h) — how often the alert history rollover job runs.
  • plugins.security_analytics.auto_correlations_enabled (Boolean, default false) — automatically generate correlation rules from new findings.
  • plugins.security_analytics.correlation.detector_cache_ttl (Time, default 5m) — TTL for the in-memory monitor-id to detector cache. Set to 0s to disable the cache.
  • plugins.security_analytics.correlation.events_backpressure.enabled (Boolean, default true) — write-block the events indices when the correlation backlog fills, so ingestion pauses and the backlog drains instead of the node running out of memory.
  • plugins.security_analytics.correlation.events_backpressure.high_watermark_percent (Integer, default 100, range 1–100) — backlog level, as a percent of correlation.max_pending_findings, at or above which the events indices are write-blocked.
  • plugins.security_analytics.correlation.events_backpressure.low_watermark_percent (Integer, default 60, range 0–99) — backlog level, as a percent of correlation.max_pending_findings, at or below which the events-index write block is lifted.
  • plugins.security_analytics.correlation.max_in_flight_findings (Integer, default 50, range 1–1000) — maximum number of correlation pipelines running concurrently.
  • plugins.security_analytics.correlation.max_pending_findings (Integer, default 10000, range 1–1000000) — maximum findings waiting for a free correlation slot. When the backlog is full, new findings are shed (correlation and enrichment skipped) so the node does not run out of memory under overload.
  • plugins.security_analytics.correlation.metadata_cache_ttl (Time, default 5m) — TTL for the in-memory caches of log-type list and correlation rules by detector type. Set to 0s to disable both caches.
  • plugins.security_analytics.correlation_history_max_age (Time, default 30d) — maximum age of a correlation history index before rollover.
  • plugins.security_analytics.correlation_history_max_docs (Long, default 1000, minimum 0) — maximum document count for a correlation history index before rollover.
  • plugins.security_analytics.correlation_history_retention_period (Time, default 60d) — retention period after which correlation history indices are deleted.
  • plugins.security_analytics.correlation_history_rollover_period (Time, default 12h) — how often the correlation history rollover job runs.
  • plugins.security_analytics.correlation_time_window (Time, default 5m) — time window used to group findings into correlations.
  • plugins.security_analytics.enable_detectors_with_dedicated_query_indices (Boolean, default true) — create dedicated query indices for new detectors.
  • plugins.security_analytics.enable_workflow_usage (Boolean, default true) — use Alerting composite workflows when running detectors.
  • plugins.security_analytics.enriched_findings_bulk_size (Integer, default 100, range 10–1000) — number of enriched findings accumulated before a bulk index request is fired.
  • plugins.security_analytics.enriched_findings_enrich_batch_size (Integer, default 100, range 1–1000) — maximum number of findings drained from the queue per in-flight permit, fetched via a single combined MultiGet.
  • plugins.security_analytics.enriched_findings_flush_interval (Integer, default 5, range 1–60) — interval in seconds at which pending enriched findings are flushed regardless of batch size.
  • plugins.security_analytics.enriched_findings_index_enabled (Boolean, default true) — toggle the enriched findings pipeline (see Architecture).
  • plugins.security_analytics.enriched_findings_max_in_flight (Integer, default 5, range 1–10) — maximum number of concurrent async enrichment chains.
  • plugins.security_analytics.enriched_findings_rule_cache_max_size (Integer, default 10000, minimum 0, static — requires a node restart to change) — maximum number of rule-metadata entries cached in memory. Least-recently-used entries are evicted past this size.
  • plugins.security_analytics.filter_by_backend_roles (Boolean, default false) — restrict access to detectors, rules, and findings based on the requester’s backend roles.
  • plugins.security_analytics.finding_history_max_age (Time, default 30d) — maximum age of a finding history index before rollover.
  • plugins.security_analytics.finding_history_retention_period (Time, default 60d) — retention period after which finding history indices are deleted.
  • plugins.security_analytics.index_timeout (Time, default 60s) — timeout for Ruleset Management index operations.
  • plugins.security_analytics.max_case_management_bulk_size (Integer, default 10, range 0–100, dynamic) — maximum number of findings that can be updated in a single request to the update findings endpoint. Setting it to 0 disables the endpoint entirely.
  • plugins.security_analytics.max_detectors (Integer, default 10, minimum 0, no upper bound, dynamic) — maximum number of user-created detectors (Content Manager detectors do not count).
  • plugins.security_analytics.max_rules_per_detector (Integer, default 50, minimum 0, no upper bound, dynamic) — maximum number of rules (custom or pre-packaged) allowed in a single detector input. Requests that would exceed this limit are rejected with HTTP 400.
  • plugins.security_analytics.mappings.default_schema (String, default ecs) — default field-mapping schema used to resolve a Sigma rule’s raw field names to Wazuh Common Schema fields when a log type does not declare its own schema.