---
title: "Update system settings"
method: PATCH
path: "/system/settings/conf"
tags: ["system"]
---

# Update system settings

`PATCH /system/settings/conf`

Update the specified Cribl system settings.<br/><br/>Provide only the top-level sections (<code>api</code>, <code>workers</code>, <code>tls</code>, <code>proxy</code>, etc.) you want to change. Omitted sections stay unchanged. Each provided section fully replaces the existing one — send the complete section object, not only the changed fields.

## Request body

- SystemSettingsConfUpdate
  - `api` object — API server configuration for the Cribl instance.
    - `baseUrl` string — Base URL for the API server. Used when the server is behind a reverse proxy.
    - `disableApiCache` boolean — If <code>true</code>, disable the API response cache. Otherwise, <code>false</code>.
    - `disabled` boolean — If <code>true</code>, the API server is disabled. Otherwise, <code>false</code>.
    - `headers` object — Custom HTTP response headers to include in every API response.
    - `host` string — Hostname or IP address the API server listens on.
    - `idleSessionTTL` integer — Idle session timeout in seconds. Sessions are invalidated after the specified seconds of inactivity.
    - `listenOnPort` boolean — If <code>true</code>, bind to the configured port as the server listen port. Otherwise, <code>false</code>.
    - `loginRateLimit` string — Rate limit for login attempts. Value is a string such as <code>100/min</code>.
    - `port` integer — Port number the API server listens on.
    - `protocol` string — API protocol: <code>http</code> or <code>https</code>.
    - `scripts` boolean — If <code>true</code>, enable JavaScript scripting support in the API. Otherwise, <code>false</code>.
    - `sensitiveFields` string[] — List of field names whose values are redacted in API responses and logs.
    - `ssl` object — TLS configuration for the API server.
      - `caPath` string — Filesystem path to the PEM-encoded Certificate Authority (CA) certificate for client authentication.
      - `certPath` string — Filesystem path to the PEM-encoded TLS certificate.
      - `disabled` boolean — If <code>true</code>, TLS is disabled for the API server. Otherwise, <code>false</code>.
      - `passphrase` string — Passphrase to decrypt the TLS private key, if encrypted.
      - `privKeyPath` string — Filesystem path to the PEM-encoded TLS private key.
    - `ssoRateLimit` string — Rate limit for SSO authentication attempts. Value is a string such as <code>100/min</code>.
    - `workerRemoteAccess` boolean — If <code>true</code>, enable remote access (teleporting) to Worker Processes via the API. Otherwise, <code>false</code>.
  - `apps` object — App configuration.
    - `enabled` boolean — If <code>true</code>, enable Apps. Otherwise, <code>false</code>.
  - `backups` union
    - object
      - `backupPersistence` string, required — How long to retain backups. Value is a duration string such as <code>24h</code>.
      - `backupsDirectory` string, required — Filesystem path where configuration backups are stored.
    - EmptyObject — An object that must not contain any properties.
  - `customLogo` object — Custom logo configuration for the Cribl UI login page and navigation bar.
    - `enabled` boolean — If <code>true</code>, display the custom logo in the UI. Otherwise, <code>false</code>.
    - `logoDescription` string — Description text displayed alongside the custom logo.
    - `logoImage` string — Custom logo image as a base64-encoded data URI (PNG or JPEG, maximum 2 MB).
  - `pii` union
    - object
      - `enablePiiDetection` boolean, required — If <code>true</code>, enable PII detection for events processed by the Cribl instance. Otherwise, <code>false</code>.
    - EmptyObject — An object that must not contain any properties.
  - `proxy` object — HTTP proxy configuration for outbound connections.
    - `useEnvVars` boolean — If <code>true</code>, use proxy settings from environment variables (<code>HTTP_PROXY</code>, <code>HTTPS_PROXY</code>, <code>NO_PROXY</code>). Otherwise, <code>false</code>.
  - `rollback` union
    - object
      - `rollbackEnabled` boolean, required — If <code>true</code>, enable automatic rollback if an upgrade fails. Otherwise, <code>false</code>.
      - `rollbackRetries` integer — Number of times to retry a rollback before marking it as failed.
      - `rollbackTimeout` integer — Maximum duration in milliseconds to wait for a rollback to complete before marking it as failed.
    - EmptyObject — An object that must not contain any properties.
  - `shutdown` object — Graceful shutdown configuration.
    - `drainTimeout` integer — Maximum time in milliseconds to wait for in-flight events to drain before forcing a shutdown.
  - `sni` union
    - object
      - `disableSNIRouting` boolean, required — If <code>true</code>, disable Server Name Indication (SNI) routing. Otherwise, <code>false</code>.
    - EmptyObject — An object that must not contain any properties.
  - `sockets` SocketsTypeSystemSettingsConf — Unix domain socket configuration.
    - `directory` string — Filesystem directory path where Unix domain socket files are created.
  - `support` object — Support and diagnostics settings.
    - `featureFlagOverrides` object[] — List of feature flag overrides applied to this Cribl instance.
      - `disabled` boolean — If <code>true</code>, the feature flag is disabled. Otherwise, <code>false</code>.
      - `flagId` string — Unique identifier of the feature flag to override.
    - `logFileMaxFiles` integer — Maximum number of log files to retain before rotating.
    - `logFileMaxSize` string — Maximum size of each log file. Value is a numeral and unit such as <code>10 MB</code>.
  - `system` object — System-level operational settings for the Cribl instance.
    - `intercom` boolean — If <code>true</code>, enable Intercom integration for in-product messaging. Otherwise, <code>false</code>.
    - `upgrade` unknown
  - `tls` union
    - object
      - `defaultCipherList` string, required — Cipher suite list to use for TLS connections. <code>DEFAULT</code> means the system default.
      - `defaultEcdhCurve` string, required — ECDH curve name for TLS key exchange. Use <code>auto</code> to let Node.js choose.
      - `maxVersion` string, required — Maximum TLS protocol version to accept.
      - `minVersion` string, required — Minimum TLS protocol version to accept.
      - `rejectUnauthorized` boolean, required — If <code>true</code>, reject TLS certificates that cannot be verified against a valid Certificate Authority. Otherwise, <code>false</code>.
    - EmptyObject — An object that must not contain any properties.
  - `upgradeGroupSettings` UpgradeGroupSettings
    - `isRolling` boolean — If <code>true</code>, perform a rolling upgrade that updates nodes incrementally. If <code>false</code>, upgrade all nodes simultaneously.
    - `quantity` integer — Percentage of nodes to upgrade at a time during a rolling upgrade.
    - `retryCount` integer — Number of times to retry upgrading a node before marking it as failed.
    - `retryDelay` integer — Delay in milliseconds between upgrade retries when a node fails to upgrade.
  - `upgradeSettings` UpgradeSettings
    - `automaticUpgradeCheckPeriod` string — How frequently to check for available upgrades. Value is a duration string such as <code>24h</code>.
    - `disableAutomaticUpgrade` boolean — If <code>true</code>, automatic upgrades are disabled. Otherwise, <code>false</code>.
    - `enableLegacyEdgeUpgrade` boolean — If <code>true</code>, enable the legacy upgrade flow for Edge Nodes. Otherwise, <code>false</code>.
    - `packageUrls` UpgradePackageUrls[] — List of custom package URLs to use for manual upgrades.
      - `packageHashUrl` string — URL of the hash file used to verify the package download.
      - `packageUrl` string, required — URL of the upgrade package file.
    - `rejectUnauthorized` boolean — If <code>false</code>, skip TLS certificate validation when downloading upgrade packages. Defaults to <code>true</code> (validate). Set to <code>false</code> only when a trusted TLS-inspecting proxy is in use (insecure).
    - `upgradeSource` string — Upgrade source: <code>cribl</code> for official Cribl packages or <code>custom</code> for a custom package URL.
  - `workers` object — Worker Process configuration.
    - `count` integer — Number of Worker Processes to spawn. Set to <code>0</code> to use the number of available CPU cores.
    - `enableHeapSnapshots` boolean — If <code>true</code>, enable V8 heap snapshot generation on out-of-memory errors. Otherwise, <code>false</code>.
    - `loadThrottlePerc` integer — CPU load percentage threshold above which new connections are throttled.
    - `memory` integer — Maximum memory (in MB) per Worker Process. Set to <code>0</code> for no limit.
    - `minimum` integer — Minimum number of Worker Processes to keep running.
    - `restartUnresponsiveProcesses` boolean — If <code>true</code>, automatically restart Worker Processes that become unresponsive. Otherwise, <code>false</code>.
    - `startupMaxConns` integer — Maximum number of connections to accept during Worker Process startup before throttling begins.
    - `startupThrottleTimeout` integer — Timeout in milliseconds to wait for Worker Processes to reach idle before ending the startup throttle period.
    - `v8SingleThread` boolean — If <code>true</code>, run all worker threads in a single V8 isolate. Otherwise, <code>false</code>.
    - `workerProcessConfigUpdateConcurrency` integer — Maximum number of Worker Processes that can reload configuration concurrently.
    - `workerProcessReloadTimeout` integer — Timeout in milliseconds to wait for a Worker Process to reload configuration before treating the reload as failed.
    - `workerThreadPoolSize` integer — Size of the Worker thread pool used for CPU-bound tasks.

## Response `200`

The updated system settings.

- CountedSystemSettingsConfResponse
  - `count` integer, required — number of items present in the items array
  - `items` SystemSettingsConfResponse[], required — List of items in this response.
    - `api` object, required
      - `baseUrl` string — Base URL for the API server. Used when the server is behind a reverse proxy.
      - `disableApiCache` boolean — If <code>true</code>, disable the API response cache. Otherwise, <code>false</code>.
      - `disabled` boolean, required — If <code>true</code>, the API server is disabled. Otherwise, <code>false</code>.
      - `headers` object — Custom HTTP response headers to include in every API response.
      - `host` string, required — Hostname or IP address the API server listens on.
      - `idleSessionTTL` integer — Idle session timeout in seconds. Sessions are invalidated after the specified seconds of inactivity.
      - `listenOnPort` boolean — If <code>true</code>, bind to the configured port as the server listen port. Otherwise, <code>false</code>.
      - `loginRateLimit` string — Rate limit for login attempts. Value is a string such as <code>100/min</code>.
      - `port` integer, required — Port number the API server listens on.
      - `protocol` string — API protocol: <code>http</code> or <code>https</code>.
      - `scripts` boolean — If <code>true</code>, enable JavaScript scripting support in the API. Otherwise, <code>false</code>.
      - `sensitiveFields` string[] — List of field names whose values are redacted in API responses and logs.
      - `ssl` SslTypeSystemSettingsConfApi — TLS configuration for the API server.
        - `caPath` string — Filesystem path to the PEM-encoded Certificate Authority (CA) certificate for client authentication.
        - `certPath` string, required — Filesystem path to the PEM-encoded TLS certificate.
        - `disabled` boolean, required — If <code>true</code>, TLS is disabled for the API server. Otherwise, <code>false</code>.
        - `passphrase` string, required — Passphrase to decrypt the TLS private key, if encrypted.
        - `privKeyPath` string, required — Filesystem path to the PEM-encoded TLS private key.
      - `ssoRateLimit` string — Rate limit for SSO authentication attempts. Value is a string such as <code>100/min</code>.
      - `workerRemoteAccess` boolean — If <code>true</code>, enable remote access (teleporting) to Worker Processes via the API. Otherwise, <code>false</code>.
    - `apps` AppsTypeSystemSettingsConf — App configuration.
      - `enabled` boolean, required — If <code>true</code>, enable Apps. Otherwise, <code>false</code>.
    - `backups` union
      - object
        - `backupPersistence` string, required — How long to retain backups. Value is a duration string such as <code>24h</code>.
        - `backupsDirectory` string, required — Filesystem path where configuration backups are stored.
      - EmptyObject — An object that must not contain any properties.
    - `customLogo` CustomLogoTypeSystemSettingsConf — Custom logo configuration for the Cribl UI login page and navigation bar.
      - `enabled` boolean, required — If <code>true</code>, display the custom logo in the UI. Otherwise, <code>false</code>.
      - `logoDescription` string — Description text displayed alongside the custom logo.
      - `logoImage` string — Custom logo image as a base64-encoded data URI (PNG or JPEG, maximum 2 MB).
    - `pii` union
      - object
        - `enablePiiDetection` boolean, required — If <code>true</code>, enable PII detection for events processed by the Cribl instance. Otherwise, <code>false</code>.
      - EmptyObject — An object that must not contain any properties.
    - `proxy` ProxyTypeSystemSettingsConf — HTTP proxy configuration for outbound connections.
      - `useEnvVars` boolean, required — If <code>true</code>, use proxy settings from environment variables (<code>HTTP_PROXY</code>, <code>HTTPS_PROXY</code>, <code>NO_PROXY</code>). Otherwise, <code>false</code>.
    - `rollback` union
      - object
        - `rollbackEnabled` boolean, required — If <code>true</code>, enable automatic rollback if an upgrade fails. Otherwise, <code>false</code>.
        - `rollbackRetries` integer — Number of times to retry a rollback before marking it as failed.
        - `rollbackTimeout` integer — Maximum duration in milliseconds to wait for a rollback to complete before marking it as failed.
      - EmptyObject — An object that must not contain any properties.
    - `shutdown` ShutdownTypeSystemSettingsConf — Graceful shutdown configuration.
      - `drainTimeout` integer, required — Maximum time in milliseconds to wait for in-flight events to drain before forcing a shutdown.
    - `sni` union
      - object
        - `disableSNIRouting` boolean, required — If <code>true</code>, disable Server Name Indication (SNI) routing. Otherwise, <code>false</code>.
      - EmptyObject — An object that must not contain any properties.
    - `sockets` SocketsTypeSystemSettingsConf — Unix domain socket configuration.
      - `directory` string — Filesystem directory path where Unix domain socket files are created.
    - `support` SupportTypeSystemSettingsConf — Support and diagnostics settings.
      - `featureFlagOverrides` FeatureFlagOverrideConfSystemSettingsConf[] — List of feature flag overrides applied to this Cribl instance.
        - `disabled` boolean, required — If <code>true</code>, the feature flag is disabled. Otherwise, <code>false</code>.
        - `flagId` string, required — Unique identifier of the feature flag to override.
      - `logFileMaxFiles` integer — Maximum number of log files to retain before rotating.
      - `logFileMaxSize` string — Maximum size of each log file. Value is a numeral and unit such as <code>10 MB</code>.
    - `system` object, required
      - `intercom` boolean, required — If <code>true</code>, enable Intercom integration for in-product messaging. Otherwise, <code>false</code>.
      - `upgrade` unknown, required
    - `tls` union
      - object
        - `defaultCipherList` string, required — Cipher suite list to use for TLS connections. <code>DEFAULT</code> means the system default.
        - `defaultEcdhCurve` string, required — ECDH curve name for TLS key exchange. Use <code>auto</code> to let Node.js choose.
        - `maxVersion` string, required — Maximum TLS protocol version to accept.
        - `minVersion` string, required — Minimum TLS protocol version to accept.
        - `rejectUnauthorized` boolean, required — If <code>true</code>, reject TLS certificates that cannot be verified against a valid Certificate Authority. Otherwise, <code>false</code>.
      - EmptyObject — An object that must not contain any properties.
    - `upgradeGroupSettings` UpgradeGroupSettings
      - `isRolling` boolean — If <code>true</code>, perform a rolling upgrade that updates nodes incrementally. If <code>false</code>, upgrade all nodes simultaneously.
      - `quantity` integer — Percentage of nodes to upgrade at a time during a rolling upgrade.
      - `retryCount` integer — Number of times to retry upgrading a node before marking it as failed.
      - `retryDelay` integer — Delay in milliseconds between upgrade retries when a node fails to upgrade.
    - `upgradeSettings` UpgradeSettings
      - `automaticUpgradeCheckPeriod` string — How frequently to check for available upgrades. Value is a duration string such as <code>24h</code>.
      - `disableAutomaticUpgrade` boolean — If <code>true</code>, automatic upgrades are disabled. Otherwise, <code>false</code>.
      - `enableLegacyEdgeUpgrade` boolean — If <code>true</code>, enable the legacy upgrade flow for Edge Nodes. Otherwise, <code>false</code>.
      - `packageUrls` UpgradePackageUrls[] — List of custom package URLs to use for manual upgrades.
        - `packageHashUrl` string — URL of the hash file used to verify the package download.
        - `packageUrl` string, required — URL of the upgrade package file.
      - `rejectUnauthorized` boolean — If <code>false</code>, skip TLS certificate validation when downloading upgrade packages. Defaults to <code>true</code> (validate). Set to <code>false</code> only when a trusted TLS-inspecting proxy is in use (insecure).
      - `upgradeSource` string — Upgrade source: <code>cribl</code> for official Cribl packages or <code>custom</code> for a custom package URL.
    - `workers` WorkersTypeSystemSettingsConf — Worker Process configuration.
      - `count` integer, required — Number of Worker Processes to spawn. Set to <code>0</code> to use the number of available CPU cores.
      - `enableHeapSnapshots` boolean — If <code>true</code>, enable V8 heap snapshot generation on out-of-memory errors. Otherwise, <code>false</code>.
      - `loadThrottlePerc` integer — CPU load percentage threshold above which new connections are throttled.
      - `memory` integer, required — Maximum memory (in MB) per Worker Process. Set to <code>0</code> for no limit.
      - `minimum` integer, required — Minimum number of Worker Processes to keep running.
      - `restartUnresponsiveProcesses` boolean — If <code>true</code>, automatically restart Worker Processes that become unresponsive. Otherwise, <code>false</code>.
      - `startupMaxConns` integer — Maximum number of connections to accept during Worker Process startup before throttling begins.
      - `startupThrottleTimeout` integer — Timeout in milliseconds to wait for Worker Processes to reach idle before ending the startup throttle period.
      - `v8SingleThread` boolean — If <code>true</code>, run all worker threads in a single V8 isolate. Otherwise, <code>false</code>.
      - `workerProcessConfigUpdateConcurrency` integer — Maximum number of Worker Processes that can reload configuration concurrently.
      - `workerProcessReloadTimeout` integer — Timeout in milliseconds to wait for a Worker Process to reload configuration before treating the reload as failed.
      - `workerThreadPoolSize` integer — Size of the Worker thread pool used for CPU-bound tasks.

## Other responses

- `400` — Failed validation or malformed input, such as missing or invalid parameters.
- `401` — Authentication failed (missing or invalid credentials or Bearer token).
- `403` — Not authorized to perform this action, or the requested change is not permitted in this deployment.
- `500` — Unexpected server error.

## Changes

- **2026-08-14** `f24e21d4ad84` — 10 breaking, 20 info
  - the response property `items/items/backups` became optional for the status `200`
  - the response property `items/items/pii` became optional for the status `200`
  - the response property `items/items/proxy` became optional for the status `200`
  - the response property `items/items/rollback` became optional for the status `200`
  - …26 more
- **2026-07-21** `e9bef570d106` — 15 breaking, 28 info
  - the `api/idleSessionTTL` request property type/format changed from `number`/`` to `integer`/``
  - the `api/port` request property type/format changed from `number`/`` to `integer`/``
  - the `rollback/oneOf[subschema #1]/rollbackRetries` request property type/format changed from `number`/`` to `integer`/``
  - the `rollback/oneOf[subschema #1]/rollbackTimeout` request property type/format changed from `number`/`` to `integer`/``
  - …39 more
- **2026-05-14** `484cda0ad459` — 3 breaking, 15 info
  - removed `subschema #1, subschema #2` from the `upgradeGroupSettings` request property `oneOf` list
  - the `upgradeGroupSettings` request property type/format changed from ``/`` to `object`/``
  - the `items/items/upgradeGroupSettings` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - added the new optional request property `apps`
  - …14 more
- **2026-01-19** `62472462b0c0` — 1 breaking
  - api path removed without deprecation
  - …this revision’s changelog is incomplete
- …earlier changes not shown

[Full history](https://skmtc.dev/criblio/apis/cribl-api-reference/changes/system/settings/conf/patch.md)

---

[API](https://skmtc.dev/criblio/apis/cribl-api-reference.md) · [All operations](https://skmtc.dev/criblio/apis/cribl-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/criblio/cribl-api-reference/revisions/56cb25079271/schema)