Virtual Registry

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

Example:

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

registries

Type: List

List of virtual registries.

name

virtual_registry:
  registries:
  - name: example

Type: String

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

virtual_registry:
  registries:
  - name: example
    default: true

Type: Boolean

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

virtual_registry:
  registries:
  - name: example
    load_balancer: random

Type: String

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.

retry_statuses

virtual_registry:
  registries:
  - name: example
    retry_statuses: [404, 429]

Type: List of Integers

Default: [404, 429]

Response statuses from a remote that make Orca retry the fetch against a remote it has not tried yet, so an artifact only one of several remotes holds is still served, and a remote that throttles a request is spent on one that does not. The client gets the response of the last remote asked.

Only applies to registries with more than one remote. These retries spend the same budget as the global varnish.params.max_retries, so raise that parameter for a registry with more remotes than it allows.

Valid values are 400-499, except 401 and 407, whose challenges have to reach the client instead of being retried. 5xx responses and failed connections are always retried regardless of this setting. Set to [] to keep the first remote’s response instead of retrying.

auth_ttl

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    auth_ttl: 3600

Type: Number

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.

auth_policy

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    auth_policy: ignore

Type: String

Default: preflight

Authorization handling policy for the caller’s own credential:

• preflight: Verify every request via a HEAD check before serving it, and share the cache only between requests that pass the same check. This is the existing default behavior.
• ignore: Skip the preflight check and share cache with anonymous requests, while still forwarding Authorization unchanged to the backend. Useful for backends that already permit anonymous access, to avoid the extra round-trip.
• drop: Strip Authorization before it ever reaches the backend.

Independent of remote_auth’s policy, which governs whether a separately configured shared credential gets injected. Not valid combined with drop, since Authorization is stripped before remote_auth.policy could apply.

auth_token_ttl

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    auth_token_ttl: 60

Type: Number

Default: 60

TTL in seconds for cached OCI auth tokens. Orca caches the token per credential and scope for this window and hands the same bearer token back, keeping the downstream authorization cache key stable so already-cached images keep serving while the upstream registry or its token endpoint is unreachable (the cached token and preflight are revived for up to 1 week in that case).

Set to 0 to disable and pass token requests straight through. Only meaningful when the Authentication feature is licensed.

default_ttl

virtual_registry:
  registries:
  - name: example
    default_ttl: 3600

Type: Number

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

virtual_registry:
  registries:
  - name: example
    default_grace: 3600

Type: Number

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

virtual_registry:
  registries:
  - name: example
    default_keep: 3600

Type: Number

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.

manifest_ttl

virtual_registry:
  registries:
  - name: example
    manifest_ttl: 60

Type: Number

TTL in seconds for manifest artifacts (such as an npm packument or a PyPI simple index). By default, mutable manifests are revalidated with the remote on every request; setting manifest_ttl caches them for a fixed window instead. Digest-pinned (immutable) manifests are unaffected.

package_ttl

virtual_registry:
  registries:
  - name: example
    package_ttl: 86400

Type: Number

TTL in seconds for package artifacts. Caps the built-in immutable lifetime of package downloads. Mutable packages that must revalidate are unaffected.

other_ttl

virtual_registry:
  registries:
  - name: example
    other_ttl: 300

Type: Number

TTL in seconds for artifacts that are not classified as a manifest or a package.

extra_vcl

Type: 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

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

Type: String

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.

Overrides the global virtual_registry.base_url for this registry.

disable_cache

virtual_registry:
  registries:
  - name: example
    disable_cache: true

Type: Boolean

Default: false

Disable artifact caching for this registry. When enabled, requests are still proxied to the registry’s remotes, but responses are not cached and every request is fetched fresh from the remote. Caching is enabled by default.

readonly

virtual_registry:
  registries:
  - name: example
    readonly: true

Type: Boolean

Default: false

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

enable_firewall

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    enable_firewall: true

Type: Boolean

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, and a license carrying the sup-firewall and sup-auth addons.

enable_cluster

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    enable_cluster: true

Type: Boolean

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, and a license carrying the sup-clustering and sup-auth addons.

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

preserve_manifest

virtual_registry:
  registries:
  - name: example
    preserve_manifest: true

Type: Boolean

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.

cache_req_body_limit

virtual_registry:
  registries:
  - name: example
    cache_req_body_limit: 10MB

Type: String

Default: 10MB

Maximum request body size to buffer for cacheable POST requests (e.g. git-upload-pack). The value is a byte size such as 512KB, 10MB, or 1GB.

remote_auth

Note: Orca Premium feature

virtual_registry:
  registries:
  - name: example
    auth_policy: ignore
    remote_auth:
      username: my-account
      password_env: REMOTE_AUTH_PASSWORD
      policy: if_anonymous

Type: Object

A shared credential that Orca can attach to outbound requests to the remote on the client’s behalf.

For an OCI (Docker/container) registry it targets the /token auth-token exchange, so that pulls through this registry count against the configured account’s rate limit instead of the upstream’s shared anonymous quota (for example, Docker Hub’s per-IP anonymous limit). For every other package type it is attached to the content request itself.

Inactive until policy is set below. Not scope-aware: the credential is presented on every request it applies to, including one that turns out to carry a write scope, so give it read-only permissions upstream. Requires the Authentication feature to be licensed. Not valid combined with auth_policy: drop, since Authorization would already be stripped before this policy could apply.

A request the credential was injected into gets a cache entry of its own rather than a preflight, because what reaches the remote is not the caller’s own credential. That entry is shared by every caller the credential is injected for, and it is keyed without the credential, so rotating the secret named by password_env leaves the cached objects in place instead of invalidating them.

policy: always therefore skips the check that auth_policy: preflight would otherwise make, since no caller’s credential is left to verify. The Supervisor warns about the combination at startup. if_anonymous is unaffected, as it only fills in where the caller sent nothing of its own.

When the remote’s token endpoint lives on a different host than the registry (as with Docker Hub’s auth.docker.io), Orca adds that host to the allowed upstream hosts automatically, so there is no need to list it in redirects.extra_known_hosts as well.

username

# (...)
    remote_auth:
      username: my-account

Type: String

Username to authenticate with, at the OCI token exchange or on the content request itself depending on the package type. Mandatory when remote_auth is set.

password_env

# (...)
    remote_auth:
      password_env: REMOTE_AUTH_PASSWORD

Type: String

Name of the environment variable holding the password paired with username. Read at request time, so the password itself never appears in the config file. Mandatory when remote_auth is set.

policy

# (...)
    remote_auth:
      policy: if_anonymous

Type: String

Default: disabled

When to inject the configured credential:

• disabled: Never inject. remote_auth has no effect.
• if_anonymous: Inject only when the caller sent no credential of its own, leaving an existing one untouched.
• always: Inject unconditionally, replacing whatever credential the caller sent. Skips the preflight check under auth_policy: preflight.

Not valid together with auth_policy: drop.

routes

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

Type: List

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

glob

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

Type: String

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

remotes

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

Type: List

List of remotes. See remotes configuration.

base_url

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

Type: String

Default base URL applied to every registry that does not set its own base_url. This is convenient when multiple registries share the same public hostname. A per-registry base_url takes precedence over this value. See the per-registry base_url for how the base URL is used, including scheme-only values.

redirects

virtual_registry:
  redirects:
    enabled: true
    signing:
      enabled: true
      key_env: REDIRECT_SIGNING_KEY

Configuration for the /redirectz endpoint. The Virtual Registry rewrites certain upstream URLs (for example Git LFS objects, Composer dist archives, and signed-blob redirects) so that they route back through itself via /redirectz, where the content can be cached.

enabled

virtual_registry:
  redirects:
    enabled: false

Type: Boolean

Default: true

Enable the /redirectz endpoint. When set to false, the endpoint is closed entirely and clients requesting it receive a 404 response.

signing

virtual_registry:
  redirects:
    signing:
      enabled: true
      key_env: REDIRECT_SIGNING_KEY

HMAC signing of /redirectz URLs. When enabled, the Virtual Registry appends a ;sig=... matrix parameter to the URLs it rewrites, and rejects requests to /redirectz whose signature is missing or invalid. This prevents clients from crafting arbitrary /redirectz URLs.

enabled

virtual_registry:
  redirects:
    signing:
      enabled: true

Type: Boolean

Default: false

Enable HMAC signing of /redirectz URLs.

key_env

virtual_registry:
  redirects:
    signing:
      key_env: REDIRECT_SIGNING_KEY

Type: String

Name of the environment variable that holds the HMAC signing key. Required when signing is enabled.

deny_unknown_hosts

virtual_registry:
  redirects:
    deny_unknown_hosts: true

Type: Boolean

Default: false

Restrict /redirectz upstream hosts and transparent redirect targets to each registry’s configured remotes plus any extra_known_hosts. When enabled, redirects to any other host are refused. When disabled, redirects to arbitrary hosts are followed.

extra_known_hosts

virtual_registry:
  redirects:
    extra_known_hosts:
    - cdn.example.com
    - downloads.example.org

Type: List

Additional hosts to allow /redirectz and transparent redirects to fetch from, beyond each registry’s configured remotes. Has no effect unless deny_unknown_hosts is enabled.

Does not apply to package_reroute, which only ever accepts a registry’s own remotes.

package_reroute

virtual_registry:
  package_reroute:
    enabled: true

Type: Object

The /package-reroute endpoint, a redirect target for a third-party forward proxy that intercepts outbound traffic to the public package registries, such as a Zscaler ZIA rule mirroring JFrog’s Package Traffic Controller.

Distinct from redirects, which covers /redirectz and the Virtual Registry’s own signed rewriting of URLs it handed out. A /package-reroute request carries no signature, since the redirect originates outside.

enabled

virtual_registry:
  package_reroute:
    enabled: true

Type: Boolean

Default: false

Enable the /package-reroute endpoint. The upstream host embedded in the ?url= parameter is resolved against every configured registry’s remotes, and the request re-enters that registry’s pipeline, so it is classified, cached and firewalled like any other.

The host has to be a remote of some registry already, and that allowlist has no override: extra_known_hosts does not extend it. The endpoint applies across every registry, with no per-registry opt-out. While disabled, a request to /package-reroute gets a 404.