Varnish Orca Configuration

Virtual Registry #

virtual_registry:
  registries:
   - name: example
     remotes:
     - url: https://example.com

Configuration for the Virtual Registry. A registry should have a name and must have a remote, all other parameters are optional.

registries list#

List of virtual registries.

name string#

virtual_registry:
  registries:
  - name: example

Default: default

The registry name should be short, unique, and recognizable. It is used for subdomain routing when there are multiple registries and metrics are segmented on registry name.

default boolean#

virtual_registry:
  registries:
  - name: example
    default: true

Default: false

If set to true, all requests that don’t match any other registry subdomain will be handled by this registry. Only one registry can be the default registry.

If only one registry is specified, it automatically becomes the default registry.

load_balancer string#

virtual_registry:
  registries:
  - name: example
    load_balancer: random

Default: fallback

The load balancing policy to use when there are multiple remotes.

• fallback: Use remotes in order of appearance. The first remote is selected first, then retries go down through the list.
• random: Balance traffic to remotes evenly. A random remote is selected from the list and retries never pick the same backend twice for a given fetch.
• hash: Pick the same remote for the same cache key. A consistent hashing algorithm is used to select a remote and retries pick new remotes in a consistent order.

auth_ttl number#

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    auth_ttl: 3600

Default: 3600

The number of seconds to cache each users authorization per artifact. Setting this to 0 causes the users authorization to be checked against the remote registry on every request.

default_ttl number#

virtual_registry:
  registries:
  - name: example
    default_ttl: 3600

Default: 120

The number of seconds to cache objects that are not otherwise covered by a specific cache policy or considered uncacheable.

Overrides the global varnish.params.default_ttl for this registry.

default_grace number#

virtual_registry:
  registries:
  - name: example
    default_grace: 3600

Default: 10

The number of seconds to grace objects that are not otherwise covered by a specific cache policy or considered uncacheable.

Overrides the global varnish.params.default_grace for this registry.

default_keep number#

virtual_registry:
  registries:
  - name: example
    default_keep: 3600

Default: 0

The number of seconds to keep stale objects that are not otherwise covered by a specific cache policy or considered uncacheable.

Overrides the global varnish.params.default_keep for this registry.

extra_vcl list#

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    extra_vcl:
    - /etc/varnish-supervisor/example.vcl

Extra VCL to prepend to the configuration generated by the Virtual Registry. Extra VCLs are included in the order they appear in this list.

base_url string#

virtual_registry:
  registries:
  - name: example
    base_url: https://my-registry.example.com

Base URL of the virtual registry. This is used when the registry needs to generate URLs that point back to itself (e.g., in manifests or redirect responses).

base_url can be set to http:// or https:// without a domain to determine the scheme used for the redirect. This can be useful when the Virtual Registry is placed behind a TLS terminating proxy, especially when preserve_subdomain is enabled for the Virtual Registry remote.

readonly boolean#

virtual_registry:
  registries:
  - name: example
    readonly: true

Default: false

Whether this registry should be treated as read-only. When enabled, write operations (push, delete) are rejected.

enable_firewall boolean#

virtual_registry:
  registries:
  - name: example
    enable_firewall: true

Default: false

Enable the Artifact Firewall for this registry. When enabled, requests are evaluated against the configured firewall rules. Requires a top-level firewall configuration.

enable_cluster boolean#

virtual_registry:
  registries:
  - name: example
    enable_cluster: true

Default: false

Enable clustering for this registry. When enabled, cluster-wide request coalescing is enabled for package requests to this Virtual Registry. Requires a top-level cluster configuration.

Only package requests are coalesced between cluster nodes, manifest and preflight auth requests go directly to the remote.

preserve_manifest boolean#

virtual_registry:
  registries:
  - name: example
    preserve_manifest: true

Default: false

Preserve original manifests from the remote without inserting the base URL. When disabled, the registry rewrites manifest URLs to point through the virtual registry.

routes list#

virtual_registry:
  registries:
  - name: example
    routes:
    - glob: "*.example.com"

Additional routes to associate with this registry. Routes allow matching requests to registries based on the Host header using glob patterns.

glob string#

virtual_registry:
  registries:
  - name: example
    routes:
    - glob: "*.example.com"

Glob pattern to match against the Host header for routing requests to this registry.

remotes list#

virtual_registry:
  registries:
   - name: example
     remotes:
     - url: https://example.com

List of remotes. See remotes configuration.

Remotes #

Configuration of remotes for virtual_registry.

virtual_registry:
  registries:
   - name: example
     remotes:
     - url: https://example.com

Remotes are selected according to the defined load_balancer policy (fallback by default). When a remote does not respond, or responds with response status 5xx, a different remote is selected and the fetch is retried. Fetches are retried until one of the following conditions are met:

• We get a non-5xx response from the remote.
• We have retried varnish.params.max_retries times.
• We have tried all the remotes.

url string#

# (...)
     remotes:
     - url: https://example.com

URL of the remote, on the form scheme://host:port.

Scheme can be http or https. If omitted, defaults to https if port has been set to 443, defaults to http otherwise.

Host can be an IP address or a domain name. If the domain name resolves to multiple IP addresses, traffic is load balanced evenly over them.

priority integer#

# (...)
     remotes:
     - url: https://example.com
       priority: 2

Default: 1

Priority can be used to divide a list of remotes into distinct load balancer groups. A remote from the highest priority group is always chosen first, and groups with lower priority are only selected if none of the higher priority give a successful response.

Priority increases with a lower numerical value. 1 is the highest possible priority.

weight number#

# (...)
     remotes:
     - url: https://example.com
       weight: 10

Default: 1

Weight can be used to shift the traffic distribution over the list of remotes. Has no effect when the failover load balancer policy is used.

Weight increases with a higher numerical value. 1 is the lowest possible weight.

dns_ttl number#

# (...)
     remotes:
     - url: https://example.com
       dns_ttl: 300

Override the interval at which DNS is resolved for this remote, in seconds. By default, DNS resolution follows the TTL from the DNS response.

preserve_subdomain boolean#

# (...)
     remotes:
     - url: https://example.com
       preserve_subdomain: true

Default: false

Preserve the subdomain from the original request when fetching from this remote. When enabled, the subdomain portion of the incoming request’s Host header is prepended to the remote’s hostname. The final hostname is also used for DNS and TLS SNI when accessing the remote.

probe#

Configuration for a health check probe to monitor the availability of a remote.

url string#

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz

URL of the remote, on the form /path. It is mandatory to set either url or tcponly, and they are mutually exclusive.

interval number#

Default: 5

The number of seconds between health checks.

timeout number#

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz
         interval: 5

Default: 2

The timeout in seconds for each health check.

expected_response integer#

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz
         expected_response: 404

Default: 200

Expected HTTP status code from the health check endpoint.

window integer#

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz
         window: 5

Default: 8

The number of most recent health check results to consider when determining health.

threshold integer#

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz
         threshold: 4

Default: 3

The minimum number of successful checks in the window required to be considered healthy

tcponly boolean#

# (...)
     remotes:
     - url: https://example.com
       probe:
         tcponly: true

Default: false

Perform a TCP health check instead of HTTP.

OpenTelemetry #

Configuration for the integrated OpenTelemetry exporter. A recognizable service_name should be set, and at least one endpoint. All other parameters are optional.

otel:
  service_name: example
  metrics:
    endpoint: http://prometheus:9090/api/v1/otlp/v1/metrics

service_name string#

otel:
  service_name: example

Default: varnish-supervisor

Service name for metrics identification

metrics#

Metrics exporter configuration.

enabled boolean#

otel:
  metrics:
    enabled: false

Default: true

Enable metrics export.

endpoint string#

otel:
  metrics:
    endpoint: http://prometheus:9090/api/v1/otlp/v1/metrics

OpenTelemetry endpoint URL for metrics export.

protocol string#

otel:
  metrics:
    protocol: grpc

Default: http/protobuf

Options:

• http/protobuf
• grpc
• http/json

Protocol to use when exporting metrics.

export_interval integer#

otel:
  metrics:
    export_interval: 30

Default: 60

Metrics export interval in seconds.

tracing#

Note: Orca Premium feature

enabled boolean#

otel:
  tracing:
    enabled: true

Default: false

Enable tracing export. Requires the vmod-otel license addon.

endpoint string#

otel:
  tracing:
    endpoint: http://prometheus:9090/api/v1/otlp/v1/metrics

OpenTelemetry endpoint URL for trace export.

protocol string#

otel:
  tracing:
    protocol: grpc

Default: http/protobuf

Options:

• http/protobuf
• grpc
• http/json

Protocol to use when exporting traces.

export_interval integer#

otel:
  tracing:
    export_interval: 5

Default: 5

Tracing batch export interval in seconds.

sampler string#

otel:
  tracing:
    sampler: parentbased_traceidratio

Default: always_on

Trace sampler type. Controls how traces are sampled.

Options:

• always_on: Sample all traces.
• always_off: Sample no traces.
• traceidratio: Sample a fraction of traces based on sampler_arg.
• parentbased_always_on: Follow parent span’s sampling decision, default to always on.
• parentbased_always_off: Follow parent span’s sampling decision, default to always off.
• parentbased_traceidratio: Follow parent span’s sampling decision, default to ratio-based.

sampler_arg number#

otel:
  tracing:
    sampler: traceidratio
    sampler_arg: 0.1

Default: 1.0

Sampler argument for ratio-based samplers. A value between 0.0 (sample nothing) and 1.0 (sample everything).

logs#

Logs exporter configuration.

enabled boolean#

otel:
  logs:
    enabled: true

Default: true (when endpoint is configured)

Enable logs export.

endpoint string#

otel:
  logs:
    endpoint: http://loki:3100/otlp/v1/logs

OTLP endpoint URL for logs export. When empty, logs export is disabled.

protocol string#

otel:
  logs:
    protocol: grpc

Default: http/protobuf

Options:

• http/protobuf
• grpc
• http/json

Protocol to use when exporting logs.

export_interval integer#

otel:
  logs:
    export_interval: 10

Default: 5

Logs export interval in seconds.

ACME #

Configuration for the ACME automated TLS certificate resolver.

acme:
  email: foo@example.com
  domains:
  - example.com

email string#

acme:
  email: foo@example.com

Email address for ACME account registration.

Type: String

domains list#

acme:
  domains:
  - example.com

Domains to obtain certificates for.

Type: List of strings

ca_server string#

acme:
  ca_server: staging

Default: production

ACME CA server URL.

Options:

• production: LetsEncrypt production server (https://acme-v02.api.letsencrypt.org/directory)
• staging: LetsEncrypt staging server (https://acme-staging-v02.api.letsencrypt.org/directory)
• Custom URL

http_port integer#

acme:
  http_port: 6080

Default: 80

Port for ACME HTTP-01 challenge server.

renew_before_days integer#

acme:
  renew_before_days: `15`

Default: 30

Days before expiry to renew certificates.

fetch_timeout_sec integer#

acme:
  fetch_timeout_sec: 150

Default: 300

Timeout for initial certificate fetching.

Artifact Firewall #

Note: Orca Premium feature

Configuration for the Varnish Artifact Firewall.

virtual_registry:
  registries:
  - name: npmjs
    default: true
    enable_firewall: true
    remotes:
    - url: https://registry.npmjs.org

firewall:
  default_action: allow
  rulesets:
  - path: /path/to/custom/ruleset.yaml
  - git:
      name: npm-osv-rules
      url: https://github.com/varnish/osv-rules.git
      sub_path: rulesets/npm/all.yaml

To enable the firewall for a specific virtual registry, set enable_firewall on the registry.

address string#

firewall:
  address: 0.0.0.0

Default: localhost

Address and/or port for the Artifact Firewall proxy to listen on. Defaults to localhost when behind Virtual Registry.

port integer#

firewall:
  port: 6089

Default: 6089

Port for the Artifact Firewall proxy to listen on.

log_level string#

firewall:
  log_level: info

Default: info

Log level for Artifact Firewall output.

Options:

• debug
• info
• warn
• error

log_output string#

firewall:
  log_output: stdout

Destination for Artifact Firewall logs.

Options:

• stdout
• stderr
• A file path (e.g. /var/log/artifact-firewall.log)

audit_log_output string#

firewall:
  audit_log_output: /var/log/artifact-firewall-audit.log

Default: stdout

Destination for the audit log, which records every decision made by the Artifact Firewall. When empty, audit logging is disabled.

Options:

• stdout
• stderr
• A file path (e.g. /var/log/artifact-firewall-audit.log)

default_action string#

firewall:
  default_action: deny

Default: allow

Action taken when a request does not match any rule in the configured rulesets.

Options:

• allow: Pass the request through.
• hide: Remove version from “latest” consideration.
• deny: Return a 403 response.

default_quarantine_days integer#

firewall:
  default_quarantine_days: 2

Default: 0 (disabled)

When set to a positive integer, newly published packages within this many days of their release are blocked regardless of ruleset matches. This provides a quarantine window to guard against newly introduced malicious packages.

Set to 0 to disable quarantine.

severity_deny_threshold number#

firewall:
  severity_deny_threshold: 9.0

Default: 9

Severity score at or above which a matching rule resolves to deny. Rules with a severity score at or above this threshold override their configured action and deny the request.

severity_allow_threshold number#

firewall:
  severity_allow_threshold: 4.0

Default: 4

Severity score at or below which a matching rule resolves to allow. Rules with a severity score at or below this threshold override their configured action and allow the request.

rulesets list#

firewall:
  rulesets:
  - path: /etc/orca/rulesets

List of ruleset sources. Each entry can reference either a local path or a remote Git repository.

path string#

firewall:
  rulesets:
  - path: /etc/orca/rulesets

Path to a ruleset file or a directory containing ruleset files. All files with a .yaml extension are interpreted as rulesets. Directories are scanned non-recursively.

git#

firewall:
  rulesets:
  - git:
      name: npm-osv-rules
      url: https://github.com/varnish/osv-rules.git
      sub_path: rulesets/npm/all.yaml

Fetch rulesets from a remote Git repository. The repository is cloned locally and refreshed on the configured interval.

name string#

Unique name for this Git ruleset source. Used to identify the source in logs and as a subdirectory name under work_dir.

url string#

URL of the Git repository.

ref string#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      ref: main

Default: repository default branch HEAD

Branch, tag, or commit SHA to check out.

sub_path string#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      sub_path: policies/npm

Path within the repository to use as the ruleset root. When empty, the repository root is used.

interval string#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      interval: 30m

Default: 1h

How often to pull updates from the remote repository. Accepts duration strings such as 30m or 2h.

fetch_timeout string#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      fetch_timeout: 60s

Default: 30s

Timeout for each fetch operation. Accepts duration strings such as 30s or 2m.

auth#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      auth:
        token_env: GITHUB_TOKEN

Credentials for authenticating with the Git remote.

token_env string#

Name of the environment variable that holds the authentication token. The token is passed as an HTTP Bearer token when fetching from the remote.

webhook#

firewall:
  webhook:
    url: https://example.com/hooks/ruleset-reloaded

Optional webhook called after rulesets are successfully reloaded. When url is not set, no webhook is sent.

Unavailable when using Artifact Firewall with Virtual Registry, as the webhook is used for manifest cache invalidation.

url string#

URL to send an HTTP request to when rulesets are reloaded.

method string#

firewall:
  webhook:
    url: https://example.com/hooks/ruleset-reloaded
    method: POST

Default: GET

HTTP method to use for the webhook request.

headers map#

firewall:
  webhook:
    url: https://example.com/hooks/ruleset-reloaded
    headers:
      Authorization: "Bearer my-secret-token"

Custom HTTP headers to include in the webhook request.

preserve_manifest boolean#

firewall:
  preserve_manifest: true

Default: false

Pass manifests through to the client without any transformation. When disabled, the firewall may rewrite manifest content.

max_manifest_size integer#

firewall:
  max_manifest_size: 67108864

Default: 67108864 (64 MiB)

Maximum manifest body size in bytes that the firewall will read and process. Manifests larger than this limit are rejected.

work_dir string#

firewall:
  work_dir: /var/cache/artifact-firewall

Working directory used to store cached data for remote ruleset sources (e.g., cloned Git repositories). Defaults to a temporary directory if not set.

metrics_address string#

firewall:
  metrics_address: :9090

Default: :9090

Address for the Prometheus metrics endpoint, in host:port form. When empty, the metrics server is disabled.

preserve_order boolean#

firewall:
  preserve_order: true

Default: false

Preserve the original JSON map key order in manifests. Enabling this is significantly slower and is primarily useful for debugging or diffing manifest transformations.

Artifact Firewall Ruleset #

Artifact Firewall Ruleset format.

- id: GHSA-8vvx-qvq9-5948
  match:
    - purl: pkg:npm/flowise
      version: vers:npm/<=2.2.7
  severity: 10
  reason: Flowise allows arbitrary file write to RCE

id string#

Unique identifier for the ruleset. Mandatory.

title string#

Human-readable title for the ruleset. Informational only. Optional.

date string#

Date the ruleset was authored. Informational only. Optional.

description string#

Description of the ruleset’s purpose. Informational only. Optional.

virtual_registries list#

id: my-ruleset
virtual_registries:
- npm-internal
rules: []

List of virtual registry names this ruleset applies to. When set, rules in this ruleset are only evaluated for requests routed through the listed registries. When empty, the ruleset applies to all registries.

rules list#

List of rules to evaluate. Rules are evaluated in order of priority value (higher priority takes precedence).

id: my-ruleset
rules:
- id: block-lodash
  match:
  - type: npm
    name: lodash
  action: deny
  reason: Unapproved package

id string#

Unique identifier for the rule within the ruleset. Mandatory.

aliases list#

rules:
- id: CVE-2021-44228
  aliases:
  - Log4Shell
  - GHSA-jfh8-c2jp-hdp

Alternative identifiers for the rule, such as CVE IDs or advisory references. Informational only.

priority integer#

rules:
- id: my-rule
  priority: 10

Default: 0

Priority for this rule. A higher numerical value means higher priority, and if multiple rules match at the highest priority level, the strongest rule applies: deny > hide > allow. The lowest possible priority is 0.

action string#

rules:
- id: my-rule
  action: deny

Action to take when the rule matches.

Options:

• allow: Pass the request through.
• hide: Remove version from “latest” consideration.
• deny: Return a 403 response.

severity number#

rules:
- id: my-rule
  severity: 8.5

Severity score for the rule, between 0.0 and 10.0. Used to determine the effective action when action is not set:

• At or above severity_deny_threshold (default 9): resolves to deny.
• At or below severity_allow_threshold (default 4): resolves to allow.
• Between the two thresholds: resolves to hide.

reason string#

rules:
- id: my-rule
  reason: Package has a known critical vulnerability

Informational. Human-readable explanation for the rule’s action. Included in audit log entries and denial responses.

quarantine_days integer#

rules:
- id: new-packages
  quarantine_days: 1

Overrides default_quarantine_days from the firewall configuration for packages matched by this rule.

match list#

rules:
- id: my-rule
  match:
  - type: npm
    name: lodash

List of selectors that must match for the rule to apply. A package must match at least one selector in the list.

exclude list#

rules:
- id: my-rule
  match:
  - type: npm
  exclude:
  - name: trusted-package

List of selectors that exempt a package from this rule. A package matching any exclude selector is not subject to the rule, even if it also matches a match selector.

Selectors#

Selectors are used in both match and exclude lists. All specified fields within a selector must match (AND logic). Multiple selectors in a list are combined with OR logic.

purl string#

- purl: pkg:npm/example@1.2.3

Match by Package URL (PURL). Package type and name are mandatory for PURLs, namespace and version are optional.

PURL only support exact versions. When a version range is needed, use the version field with VERS notation.

Mutually exclusive with type and name.

type string#

- type: npm
  name: example

Match by package ecosystem type (e.g. npm, pypi).

When type is used, name is also mandatory. Mutually exclusive with purl

namespace string#

- type: npm
  namespace: angular
  name: example

Match by package namespace (e.g. the npm scope). Simple glob patterns are supported.

name string#

- type: npm
  name: example

Match by package name. Simple glob patterns are supported.

When name is used, type is also mandatory. Mutually exclusive with purl

version string#

- purl: pkg:npm/example
  version: vers:npm/1.2.3|>=2.0.0|<5.0.0

Match by package version or version range.

Version ranges are supported with VERS notation.

Cluster #

Note: Orca Premium feature

Configuration for clustering multiple Virtual Registry nodes together.

For more information on the internals of clustering: https://docs.varnish-software.com/varnish-enterprise/features/cluster

cluster:
  token: secret
  peers:
  - url: http://orca-node-1:8080
  - url: http://orca-node-2:8080
  - url: http://orca-node-3:8080

Peers can be defined statically via peers, or discovered dynamically via peer_group. To enable clustering for a specific virtual registry, set enable_cluster on the registry.

token string#

cluster:
  token: secret

Shared secret used to authenticate cluster peers. All nodes in the cluster must be configured with the same token.

peer_group#

Dynamic cluster peer group configuration. Uses the same fields as remotes to point to a service that exposes the list of cluster peers.

cluster:
  token: secret
  peer_group:
    url: http://peer-discovery-service:8080

peers list#

cluster:
  token: secret
  peers:
  - url: http://orca-node-1:8080
  - url: http://orca-node-2:8080
  - url: http://orca-node-3:8080

List of individual peer nodes for a static cluster. Each entry uses the same fields as remotes.

All nodes in the cluster should be listed, including the node itself. Each node must be able to send HTTP requests to all other nodes, including itself. All inter-node communication happens over the regular HTTP(S) port.

Supervisor #

supervisor:
  log_level: error

Configuration for the Varnish Supervisor itself.

log_output string#

supervisor:
  log_output: stderr

Default: stdout

Where to write Supervisor (control plane) logs.

Options:

• stdout: Log to stdout
• stderr: Log to stderr
• discard: Discard logs
• file path: Write logs to a file

log_level string#

supervisor:
  log_level: warn

Default: stdout

Change the log level of the Supervisor (control plane) logs.

Options:

• info: Log at info level.
• warn: Log at warning level.
• error: Log at error level.
• debug: Log at debug level.

work_dir string#

supervisor:
  work_dir: /tmp/varnish-supervisor

Default: /var/lib/varnish-supervisor

The working directory for storing state, logs, and other runtime files.

License #

Configuration for the Premium License. The license unlocks Orca Premium functionality not available in the free version.

license:
  file: /etc/varnish-supervisor/license.lic

text string#

license:
  text: |
        <License>

Provide a license as text in the configuration.

file string#

license:
  file: /etc/varnish-supervisor/license.lic

Provide a path to the license.

Varnish #

varnish:
  http:
  - port: 80

General configuration for Varnish. At least one http or https listen endpoint must be specified, all other parameters are optional.

http list#

A list of HTTP ports for Varnish to bind and listen to. Varnish needs at least one http port or one https port.

port integer#

varnish:
  http:
  - port: 80

The port number to listen to. If address is not also specified, varnish will listen on all available interfaces.

address string#

varnish:
  http:
  - address: 127.0.0.1:80

The interface address to bind to. Can specify both address and port, or used in combination with port.

https list#

A list of HTTPS listeners for Varnish to bind to. Each listener must have at least one certificate.

port integer#

varnish:
  https:
  - port: 443
    certificates:
    - self_singed: example.com

The port number to listen to. If address is not also specified, varnish will listen on all available interfaces.

address string#

varnish:
  http:
  - address: 127.0.0.1:443
    certificates:
    - self_singed: example.com

The interface address to bind to. Can specify both address and port, or used in combination with port.

certificates list#

The certificates to use for this HTTPS listener.

combined string#

varnish:
  https:
  - port: 443
    certificates:
    - combined: /tmp/combined.pem

Path to a combined certificate and private key PEM file. Mutually exclusive with cert and private_key.

cert string#

varnish:
  https:
  - port: 443
    certificates:
    - cert: /etc/varnish-supervisor/cert.crt
      private_key: /etc/varnish-supervisor/private.key

Path to a certificate PEM file. If specified, a private_key must be specified as well.

private_key string#

varnish:
  https:
  - port: 443
    certificates:
    - cert: /etc/varnish-supervisor/cert.crt
      private_key: /etc/varnish-supervisor/private.key

Path to a private key PEM file. If specified, a cert must be specified as well.

self_signed string#

varnish:
  https:
  - port: 443
    certificates:
    - self_signed: "localhost"
    - self_signed: "*.localhost"
    - self_signed: "example.com"

Generate a self-signed certificate. This is useful for testing with clients that accept non-trusted certificates. Supports wildcards for wildcard TLS certificates.

For automatic trusted TLS, see ACME.

storage#

Note: Orca Premium feature

Configure a persistent cache for Varnish to use. This will generate the appropriate Massive Storage Engine (MSE) 4 configuration and initialize it with mkfs.mse4. Changes to the config will be applied upon restart of the Supervisor.

stores list#

A list of stores for the persisted cache. A store appears as a single large file on the file system and is used to persist chunks of cached objects.

An auxiliary file called a book is created alongside the store, which keeps track of where the object chunks in the store are and other metadata such as cache invalidation keys and checksums for durable storage.

Each store must have a name, path and size.

name string#

varnish:
  storage:
    stores:
    - name: disk1
      path: /etc/varnish-supervisor/storage/disk1
      size: 1000G

The unique identifying name for this store.

path string#

varnish:
  storage:
    stores:
    - name: disk1
      path: /etc/varnish-supervisor/storage/disk1
      size: 1000G

Path to a directory where the the store and book files will be created at Supervisor startup. The backing storage must have space to fit size bytes.

size string#

varnish:
  storage:
    stores:
    - name: disk1
      path: /etc/varnish-supervisor/storage/disk1
      size: 1000G

Size of the store to create. Available case-insensitive units are K, M, G, and T.

The size includes the size of the book (5G by default) and filesystem overhead (1G), so the size of the store file can be calculated as:

store_size = size - book_size - 1G.

Must be larger than book_size + 1G.

book_size string#

varnish:
  storage:
    stores:
    - name: disk1
      path: /etc/varnish-supervisor/storage/disk1
      size: 1000G
      book_size: 2G

Default: 5G

Change the size of a store’s book. When the size of a book is increased, the size of the store is decreased, and vice versa.

category string#

varnish:
  storage:
    default_category: other
    stores:
    - name: disk1
      path: /disk1
      size: 1000G
      category: media.video
    - name: disk2
      path: /disk2
      size: 1000G
      category: media.video
    - name: icons
      path: /disk3/icons
      size: 50G
      category: media.images.icons
    - name: pictures
      path: /disk3/pictures
      size: 150G
      category: media.images.pictures
    - name: other
      path: /disk3/other
      size: 800G
      category: other

Assign a category to the store. This reserves the store to be used exclusively for objects of the same category. Multiple stores can have the same category, in which case objects are spread evenly over the stores.

Object category can be set in VCL sub vcl_backend_response with the mse4 VMOD:

mse4.set_category("media.video");

If no category has been set in VCL, the category defined by default_category is used.

Categories are a tree structure, and each store category must be a leaf-node in that tree. This means that if one store has the category media.images.icons, another store cannot have the category media.images.

When categories are used, all stores must have a category and default_category must be set.

default_category string#

varnish:
  storage:
    default_category: blobs
    stores:
    - name: manifests
      path: /disk1/manifests
      size: 100G
      category: manifests
    - name: objects
      path: /disk1/objects
      size: 900G
      category: objects

The default category to use if no category have been set in VCL.

Required if categories are used.

admin_port integer#

varnish:
  admin_port: 1234

Default: 1092

Target port for the reverse admin interface.

work_dir string#

varnish:
  work_dir: /var/lib/varnish

Default: Derived from system defaults

Varnish working directory (equivalent to varnishd -n). This is the directory where Varnish stores its shared memory logs and other runtime files.

path string#

varnish:
  path: /path/to/varnishd

Default: Derived from system $PATH

Path to the varnishd binary to use.

params#

varnish:
  params:
    workspace_backend: 128k

Parameters for Varnish. See params.

Varnish Parameters #

Parameters for varnish.

varnish:
  params:
    workspace_backend: 128k

accept_filter boolean#

varnish:
  params:
    accept_filter:: true

Default: true

Enable kernel accept-filters.

acceptor_sleep_decay number#

varnish:
  params:
    acceptor_sleep_decay:: 0.9

Default: 0.9

Sleep duration reduction for each successful accept (0.9 = reduce by 10%).

acceptor_sleep_incr number#

varnish:
  params:
    acceptor_sleep_incr:: 0

Default: 0

How much longer we sleep, each time we fail to accept a new connection.

acceptor_sleep_max number#

varnish:
  params:
    acceptor_sleep_max:: 0.05

Default: 0.05

Maximum sleep duration between attempts to accept new connections.

auto_restart boolean#

varnish:
  params:
    auto_restart:: true

Default: true

Automatically restart the child/worker process if it dies.

backend_cooloff number#

varnish:
  params:
    backend_cooloff:: 60

Default: 60

How long we wait before cleaning up deleted backends.

backend_idle_timeout number#

varnish:
  params:
    backend_idle_timeout:: 60

Default: 60

Timeout before we close unused backend connections.

backend_local_error_holddown number#

varnish:
  params:
    backend_local_error_holddown:: 10

Default: 10

Prevent connection attempts after local resource shortage errors.

backend_remote_error_holddown number#

varnish:
  params:
    backend_remote_error_holddown:: 0.25

Default: 0.25

Prevent connection attempts after remote connection errors.

backend_wait_limit integer#

varnish:
  params:
    backend_wait_limit:: 0

Default: 0

Maximum transactions that can queue waiting for a backend connection.

backend_wait_timeout number#

varnish:
  params:
    backend_wait_timeout:: 0

Default: 0

Default time transactions wait for backend connections before giving up.

ban_cutoff integer#

varnish:
  params:
    ban_cutoff:: 0

Default: 0

Expurge long tail content to keep bans below this value. 0 disables.

ban_dups boolean#

varnish:
  params:
    ban_dups:: true

Default: true

Eliminate older identical bans when a new ban is added.

ban_lurker_age number#

varnish:
  params:
    ban_lurker_age:: 60

Default: 60

The ban lurker will ignore bans until they are this old.

ban_lurker_batch integer#

varnish:
  params:
    ban_lurker_batch:: 1000

Default: 1000

Ban lurker sleeps after examining this many objects.

ban_lurker_holdoff number#

varnish:
  params:
    ban_lurker_holdoff: 0.01

Default: 0.01

How long ban lurker sleeps when giving way to lookup due to lock contention.

ban_lurker_sleep number#

varnish:
  params:
    ban_lurker_sleep:: 0.01

Default: 0.01

How long ban lurker sleeps after examining objects.

between_bytes_timeout number#

varnish:
  params:
    between_bytes_timeout:: 60

Default: 60

Seconds to wait between bytes received from backend before giving up.

cli_limit string#

varnish:
  params:
    cli_limit:: 128k

Default: 128k

Maximum size of CLI response.

cli_timeout number#

varnish:
  params:
    cli_timeout:: 60

Default: 60

Timeout for child replies to CLI requests from management.

clock_skew integer#

varnish:
  params:
    clock_skew: 10

Default: 10

How much clockskew we accept between backend and our own clock.

clock_step number#

varnish:
  params:
    clock_step:: 10

Default: 10

How much observed clock step we accept before we panic.

connect_timeout number#

varnish:
  params:
    connect_timeout:: 3.5

Default: 3.5

Default connection timeout for backend connections.

critbit_cooloff number#

varnish:
  params:
    critbit_cooloff:: 180

Default: 180

How long critbit hasher keeps deleted objheads on cooloff list.

debug string#

varnish:
  params:
    debug:: ""

Default: ""

Enable/Disable various kinds of debugging.

default_grace number#

varnish:
  params:
    default_grace:: 10

Default: 10

Default grace period for expired objects.

default_keep number#

varnish:
  params:
    default_keep:: 0

Default: 0

Default keep period for objects after grace.

default_ttl number#

varnish:
  params:
    default_ttl:: 120

Default: 120

TTL assigned to objects if neither backend nor VCL assigns one.

epitaphs integer#

varnish:
  params:
    epitaphs:: 3

Default: 3

Maximum messages child can add to its gravestone.

esi_iovs integer#

varnish:
  params:
    esi_iovs:: 10

Default: 10

Number of io vectors to allocate on thread workspace for ESI requests.

esi_limit integer#

varnish:
  params:
    esi_limit:: 10

Default: 10

Limit for ESI fragments processed in parallel at each ESI level.

experimental string#

varnish:
  params:
    experimental:: ""

Default: ""

Enable/Disable experimental features.

feature string#

varnish:
  params:
    feature:: +http2

Default: +http2

Enable/Disable various minor features.

fetch_chunksize string#

varnish:
  params:
    fetch_chunksize:: 16k

Default: 16k

Default chunksize used by fetcher.

fetch_maxchunksize string#

varnish:
  params:
    fetch_maxchunksize:: 0.25G

Default: 0.25G

Maximum chunksize we attempt to allocate from storage.

first_byte_timeout number#

varnish:
  params:
    first_byte_timeout:: 60

Default: 60

Default timeout for receiving first byte from backend.

gzip_buffer string#

varnish:
  params:
    gzip_buffer:: 32k

Default: 32k

Size of malloc buffer used for gzip processing.

gzip_level integer#

varnish:
  params:
    gzip_level:: 6

Default: 6

Gzip compression level: 0=debug, 1=fast, 9=best.

gzip_memlevel integer#

varnish:
  params:
    gzip_memlevel:: 6

Default: 6

Gzip memory level 1=slow/least, 9=fast/most compression.

h2_header_table_size string#

varnish:
  params:
    h2_header_table_size:: 4k

Default: 4k

HTTP2 header table size.

h2_initial_window_size string#

varnish:
  params:
    h2_initial_window_size:: 65535b

Default: 65535b

HTTP2 initial flow control window size.

h2_max_concurrent_streams integer#

varnish:
  params:
    h2_max_concurrent_streams: 100

Default: 100

HTTP2 maximum number of concurrent streams.

h2_max_frame_size string#

varnish:
  params:
    h2_max_frame_size:: 16k

Default: 16k

HTTP2 maximum per frame payload size.

h2_max_header_list_size string#

varnish:
  params:
    h2_max_header_list_size:: 0b

Default: 0b

HTTP2 maximum size of uncompressed header list.

h2_rapid_reset number#

varnish:
  params:
    h2_rapid_reset:: 1

Default: 1

Threshold for treating RST_STREAM as suspect after HEADERS.

h2_rapid_reset_limit integer#

varnish:
  params:
    h2_rapid_reset_limit:: 100

Default: 100

Maximum allowed stream resets over time period.

h2_rapid_reset_period number#

varnish:
  params:
    h2_rapid_reset_period:: 60

Default: 60

Sliding window duration for h2_rapid_reset_limit.

h2_rx_window_increment string#

varnish:
  params:
    h2_rx_window_increment: 1M

Default: 1M

HTTP2 receive window increments.

h2_rx_window_low_water string#

varnish:
  params:
    h2_rx_window_low_water: 10M

Default: 10M

HTTP2 receive window low water mark.

h2_rxbuf_storage string#

varnish:
  params:
    h2_rxbuf_storage: Transient

Default: Transient

Storage backend for HTTP/2 receive buffers.

h2_window_timeout number#

varnish:
  params:
    h2_window_timeout: 5

Default: 5

HTTP2 time limit without window credits.

http_brotli_support boolean#

varnish:
  params:
    http_brotli_support: true

Default: true

Enable brotli support.

http_gzip_support boolean#

varnish:
  params:
    http_gzip_support: true

Default: true

Enable gzip support.

http_max_hdr integer#

varnish:
  params:
    http_max_hdr: 64

Default: 64

Maximum number of HTTP header lines.

http_range_support boolean#

varnish:
  params:
    http_range_support: true

Default: true

Enable support for HTTP Range headers.

http_req_hdr_len string#

varnish:
  params:
    http_req_hdr_len: 8k

Default: 8k

Maximum length of any HTTP client request header.

http_req_size string#

varnish:
  params:
    http_req_size: 32k

Default: 32k

Maximum bytes of HTTP client request.

http_resp_hdr_len string#

varnish:
  params:
    http_resp_hdr_len: 8k

Default: 8k

Maximum length of any HTTP backend response header.

http_resp_size string#

varnish:
  params:
    http_resp_size: 32k

Default: 32k

Maximum bytes of HTTP backend response.

idle_send_timeout number#

varnish:
  params:
    idle_send_timeout: 60

Default: 60

Send timeout for individual pieces of data on client connections.

last_byte_timeout number#

varnish:
  params:
    last_byte_timeout: 0

Default: 0

Maximum time to wait for complete backend response.

listen_depth integer#

varnish:
  params:
    listen_depth: 1024

Default: 1024

Listen queue depth.

lru_interval number#

varnish:
  params:
    lru_interval: 2

Default: 2

Grace period before object moves on LRU list.

max_esi_depth integer#

varnish:
  params:
    max_esi_depth: 5

Default: 5

Maximum depth of esi:include processing.

max_restarts integer#

varnish:
  params:
    max_restarts: 4

Default: 4

Upper limit on how many times a request can restart.

max_retries integer#

varnish:
  params:
    max_retries: 4

Default: 4

Upper limit on how many times a backend fetch can retry.

max_vcl integer#

varnish:
  params:
    max_vcl: 100

Default: 100

Threshold of loaded VCL programs.

max_vcl_handling integer#

varnish:
  params:
    max_vcl_handling: 1

Default: 1

Behaviour when attempting to exceed max_vcl loaded VCL.

memory_arenas integer#

varnish:
  params:
    memory_arenas: 0

Default: 0

Number of jemalloc arenas for object payload storage.

memory_stat_interval number#

varnish:
  params:
    memory_stat_interval: 0.1

Default: 0.1

Interval between memory usage statistics updates.

memory_target string#

varnish:
  params:
    memory_target: 80%

Default: 80%

Target RssAnon memory usage when memory governor is active.

nuke_limit integer#

varnish:
  params:
    nuke_limit: 50

Default: 50

Maximum objects we attempt to nuke to make space.

numa_aware boolean#

varnish:
  params:
    numa_aware: false

Default: false

Become NUMA aware for better CPU utilization.

object_mutex_slots integer#

varnish:
  params:
    object_mutex_slots: 4096

Default: 4096

Number of mutex and condvar slots for per object signalling.

pcre_match_limit integer#

varnish:
  params:
    pcre_match_limit: 10000

Default: 10000

Limit for calls to internal match() function in pcre_exec().

pcre_match_limit_recursion integer#

varnish:
  params:
    pcre_match_limit_recursion: 20

Default: 20

Recursion depth-limit for internal match() function.

ping_interval integer#

varnish:
  params:
    ping_interval: 3

Default: 3

Interval between pings from parent to child.

pipe_timeout number#

varnish:
  params:
    pipe_timeout: 60

Default: 60

Idle timeout for PIPE sessions.

pool_req string#

varnish:
  params:
    pool_req: 10,100,10

Default: 10,100,10

Parameters for per worker pool request memory pool.

pool_sess string#

varnish:
  params:
    pool_sess: 10,100,10

Default: 10,100,10

Parameters for per worker pool session memory pool.

pool_sslbuffer string#

varnish:
  params:
    pool_sslbuffer: 10,100,10

Default: 10,100,10

Parameters for the SSL buffer pool (min_pool, max_pool, max_age).

pool_vbo string#

varnish:
  params:
    pool_vbo: 10,100,10

Default: 10,100,10

Parameters for per worker pool VBO memory pool.

prefer_ipv6 boolean#

varnish:
  params:
    prefer_ipv6: false

Default: false

Prefer IPv6 address when connecting to backends.

rush_exponent integer#

varnish:
  params:
    rush_exponent: 3

Default: 3

How many parked requests we start for each completed request on an object.

reuseport boolean#

varnish:
  params:
    reuseport: false

Default: false

Enable SO_REUSEPORT socket option.

send_timeout number#

varnish:
  params:
    send_timeout: 600

Default: 600

Total timeout for ordinary HTTP1 responses.

shortlived number#

varnish:
  params:
    shortlived: 10

Default: 10

Objects created with TTL shorter than this are not subject to LRU.

shutdown_close boolean#

varnish:
  params:
    shutdown_close: false

Default: false

Control if listen sockets should be closed during shutdown_delay upon reception of SIGTERM.

shutdown_delay number#

varnish:
  params:
    shutdown_delay: 0

Default: 0

Delay before shutting down the management process upon reception of SIGTERM.

sigsegv_handler boolean#

varnish:
  params:
    sigsegv_handler: true

Default: true

Install a signal handler to dump debug info on segmentation faults, bus errors, and abort signals.

slicer_excess_ratio number#

varnish:
  params:
    slicer_excess_ratio: 0.5

Default: 0.5

How much larger than the configured segment size the last segment is allowed to be.

ssl_buffer string#

varnish:
  params:
    ssl_buffer: 20k

Default: 20k

Size of the SSL buffer.

startup_timeout number#

varnish:
  params:
    startup_timeout: 600

Default: 600

How long to wait for child startup.

syslog_cli_traffic boolean#

varnish:
  params:
    syslog_cli_traffic: true

Default: true

Log all CLI traffic to syslog(LOG_INFO).

tcp_fastopen boolean#

varnish:
  params:
    tcp_fastopen: false

Default: false

Enable the TCP Fast Open extension.

tcp_keepalive_intvl number#

varnish:
  params:
    tcp_keepalive_intvl: 75

Default: 75

The number of seconds between TCP keep-alive probes.

tcp_keepalive_probes integer#

varnish:
  params:
    tcp_keepalive_probes: 9

Default: ""

Maximum number of TCP keep-alive probes to send before killing the connection.

tcp_keepalive_time number#

varnish:
  params:
    tcp_keepalive_time: 7200

Default: ""

Seconds a connection must be idle before TCP sends keep-alive probes.

thread_pool_add_delay number#

varnish:
  params:
    thread_pool_add_delay: 0

Default: 0

Wait at least this long after creating a thread.

thread_pool_destroy_delay number#

varnish:
  params:
    thread_pool_destroy_delay: 1

Default: 1

Wait at least this long after destroying a thread pool.

thread_pool_fail_delay number#

varnish:
  params:
    thread_pool_fail_delay: 0.2

Default: 0.2

Wait at least this long after a failed thread creation.

thread_pool_max integer#

varnish:
  params:
    thread_pool_max: 5000

Default: 5000

Maximum number of worker threads in each pool.

thread_pool_min integer#

varnish:
  params:
    thread_pool_min: 100

Default: 100

Minimum number of worker threads in each pool.

thread_pool_reserve integer#

varnish:
  params:
    thread_pool_reserve: 0

Default: 0

The number of worker threads reserved for vital tasks.

thread_pool_stack string#

varnish:
  params:
    thread_pool_stack: 48k

Default: 48k

Worker thread stack size.

thread_pool_timeout number#

varnish:
  params:
    thread_pool_timeout: 300

Default: 300

Thread idle threshold for destroying threads.

thread_pool_track boolean#

varnish:
  params:
    thread_pool_track: false

Default: false

Keep track of running worker threads and tasks queued in the pools.

thread_pool_watchdog number#

varnish:
  params:
    thread_pool_watchdog: 60

Default: 60

If no queued work has been released for this long, the worker process panics itself.

thread_pools integer#

varnish:
  params:
    thread_pools: 2

Default: 2

Number of worker thread pools.

thread_queue_limit integer#

varnish:
  params:
    thread_queue_limit: 0

Default: 0

Permitted request queue length per thread-pool.

thread_stats_rate integer#

varnish:
  params:
    thread_stats_rate: 10

Default: 10

Worker thread statistics update rate limit.

timeout_idle number#

varnish:
  params:
    timeout_idle: 5

Default: 5

Idle timeout for client connections.

timeout_linger number#

varnish:
  params:
    timeout_linger: 0.05

Default: 0.05

How long to linger on connections when close requested.

timeout_req number#

varnish:
  params:
    timeout_req: 5

Default: 5

Max time to receive client request.

timeout_reqbody number#

varnish:
  params:
    timeout_reqbody: 0

Default: 0

Maximum time to receive a client request body.

tls_handshake_timeout number#

varnish:
  params:
    tls_handshake_timeout: 8

Default: 8

Default timeout for completion of the TLS handshake.

tls_ja3 boolean#

varnish:
  params:
    tls_ja3: false

Default: false

Enable JA3 fingerprint.

tls_ocsp_auto boolean#

varnish:
  params:
    tls_ocsp_auto: false

Default: false

Enable automatic OCSP staple configuration.

tls_ocsp_default_ttl number#

varnish:
  params:
    tls_ocsp_default_ttl: 7200

Default: 7200

How long to consider an OCSP response fresh if it lacks a nextUpdate property.

tls_ocsp_dir string#

varnish:
  params:
    tls_ocsp_dir: /var/lib/varnish-ocsp

Default: /var/lib/varnish-ocsp

Directory where Varnish keeps a cache of OCSP responses.

tls_ocsp_fetch_limit integer#

varnish:
  params:
    tls_ocsp_fetch_limit: 10

Default: 10

Upper limit for the number of OCSP responses fetched in parallel.

tls_ocsp_force_ttl number#

varnish:
  params:
    tls_ocsp_force_ttl: 0

Default: 0

Force TTL for OCSP responses.

tls_ocsp_refresh_ratio number#

varnish:
  params:
    tls_ocsp_refresh_ratio: 0.5

Default: 0.5

Specifies when to refresh an OCSP response given as a ratio of its lifetime.

transit_buffer string#

varnish:
  params:
    transit_buffer: 0

Default: 0

The default prefetch amount used during a single private transaction.

uncacheable_ttl number#

varnish:
  params:
    uncacheable_ttl: 120

Default: 120

The TTL assigned to uncacheable objects by the built-in VCL.

vcc_err_unref boolean#

varnish:
  params:
    vcc_err_unref: false

Default: false

Unreferenced VCL objects are errors, not warnings.

vcl_cooldown number#

varnish:
  params:
    vcl_cooldown: 600

Default: 600

How long a VCL is kept warm after being replaced as the active VCL.

vsl_buffer string#

varnish:
  params:
    vsl_buffer: 4k

Default: 4k

VSL buffer size.

vsl_mask string#

varnish:
  params:
    vsl_mask: -Debug,-ObjProtocol,-ObjStatus,-ObjReason,-ObjHeader,-VCL_trace,-ExpKill,-WorkThread,-Hash,-VfpAcct,-H2RxHdr,-H2RxBody,-H2TxHdr,-H2TxBody

Default: -Debug,-ObjProtocol,-ObjStatus,-ObjReason,-ObjHeader,-VCL_trace,-ExpKill,-WorkThread,-Hash,-VfpAcct,-H2RxHdr,-H2RxBody,-H2TxHdr,-H2TxBody

VSL tag mask.

vsl_reclen integer#

varnish:
  params:
    vsl_reclen: 4084b

Default: 4084b

Maximum number of bytes in SHM log record.

vsl_space string#

varnish:
  params:
    vsl_space: 80M

Default: 80M

The amount of space to allocate for the VSL fifo buffer.

vsm_free_cooldown number#

varnish:
  params:
    vsm_free_cooldown: 60

Default: 60

How long VSM memory is kept warm after a deallocation.

vsm_publish_interval number#

varnish:
  params:
    vsm_publish_interval: 1

Default: 1

The minimum interval that new VSM segment indexes are published.

vst_space string#

varnish:
  params:
    vst_space: 10M

Default: 10M

The amount of space to allocate for a VST memory segment.

workspace_backend string#

varnish:
  params:
    workspace_backend: 64k

Default: 64k

Bytes of HTTP protocol workspace for backend HTTP req/resp.

workspace_client string#

varnish:
  params:
    workspace_client: 64k

Default: 64k

Bytes of HTTP protocol workspace for clients HTTP req/resp.

workspace_session string#

varnish:
  params:
    workspace_session: 0.75k

Default: 0.75k

Bytes of session workspace.

workspace_thread string#

varnish:
  params:
    workspace_thread: 2k

Default: 2k

Bytes of auxiliary workspace per thread.

ykey_mem_digest_split_bits integer#

varnish:
  params:
    ykey_mem_digest_split_bits: 4

Default: 4

Number of bits used to select a tree set based on the ykey hash for non-persisted objects.

ykey_mem_tree_split integer#

varnish:
  params:
    ykey_mem_tree_split: 7

Default: 7

Number of trees to spread ephemeral objects with the same hash across.