Skip to content

Configuring The Server

The server will accept configuration on the command line, or via a configuration yaml file. Most of the configuration file settings map directly to the command line. The exceptions are the pruneConfig, registries, and serverTlsConfig entries which are only accepted in the configuration file at this time, being too complex to easily represent as command line args.

Note

As of server version 2.0.0, strict parsing of the config yaml is implemented. A parse error will prevent the server from running.

As one would expect the following values provide configuration with the lowest priority on the bottom and the highest priority on the top:

block
  columns 1
  a["Command line"]
  b["Config file"]
  c["Hard-coded defaults in the Go code"]

To provide full configuration in a file, run the server this way:

bin/ociregistry --config-file <some file> serve

But this is also valid:

bin/ociregistry --config-file <some file> serve --port 9999

Defaults

The yaml document below shows a config.yaml file specifying the defaults that are implemented in the Go code. In other words, running the server with this exact configuration file is the same as running with no configuration file:

imagePath: /var/lib/ociregistry
logLevel: error
logFile:
preloadImages:
imageFile:
resolveRef:
port: 8080
#os: omit to use the server OS
#arch: omit to use the server architecture
pullTimeout: 60000
alwaysPullLatest: false
noCache: []
airGapped: false
helloWorld: false
defaultNs:
host: 0.0.0.0
health:
metrics:
registries: []
pruneConfig:
  enabled: false
serverTlsConfig: {}

Config file keys and values

Key Type Default Command line arg Description
imagePath Path spec /var/lib/ociregistry --image-path The base path for the image cache. The server will create sub-directories under this for blobs and manifests.
logLevel keyword error --log-level Error level logging. See help for valid values.
logFile Path spec - --log-file Empty means log to stderr. If you specify a file, the logging is directed to the file.
preloadImages Path spec - --preload-images Used by the serve subcommand to pre-load images before starting the server. See "Loading Images" below.
imageFile Path spec - --image-file Used by the load subcommand to load images while the server is not running (expects exclusive access to the image cache.) See "Loading Images" below.
resolveRef string n/a --resolve-ref Don't use this field in the configuration yaml file. This is a very narrow use case for single-image tarballs. See the load sub-command, e.g. ociregistry load --help
port Integer 8080 --port The port to serve on
os keyword runtime.GOOS --os If loading or preloading, the OS and arch. If empty, then defaults to the host running the server. So usually comment these out.
arch keyword runtime.GOARCH --arch "
pullTimeout Integer 60000 --pull-timeout Number of milliseconds before a pull from an upstream will time out.
alwaysPullLatest Boolean false --always-pull-latest As of version 2.0.0, this is internally implemented as --no-cache ':latest$'. See the No Cache section below.
noCache String list [] --no-cache pattern [--no-cache pattern] See the No Cache section below.
airGapped Boolean false --air-gapped If true, will not attempt to pull from an upstream when an image is requested that is not cached.
helloWorld Boolean false --hello-world For testing. Only serves 'docker.io/hello-world:latest' from embedded blobs and manifests
defaultNs String Empty --default-ns Allows pulling without an explicit namespace. Otherise, a namespace is required either in-path (docker pull ociregistry:8080/docker.io/hello-world) or as a query param the way containerd does it when registry mirroring is configured in the containerd config.toml. E.g. if --default-ns=docker.io then docker pull ociregistry:8080/hello-world will pull from docker.io, otherwise it is an error.
host String 0.0.0.0 --host E.g. "127.0.0.1".
health Integer - --health A port number to run a /health endpoint on for Kubernetes liveness and readiness. By default, the server doesn't listen on a health port. The Helm chart enables this by default when running the server as a cluster workload.
metrics Integer - --metrics A port number to run a /metrics endpoint on for Prometheus. By default, the server doesn't enable or expose metrics.
registries List of dictionary [] n/a Upstream registries configuration. See further down for registry configuration.
pruneConfig Dictionary see below n/a Prune configuration. Pruning is disabled by default. See further down for prune configuration.
serverTlsConfig Dictionary {} n/a Configures TLS with downstream (client) pullers, e.g. containerd. By default, serves over HTTP. See server tls configuration further down.

No Cache

The noCache config entry (or --no-cache arg) works as follows:

  • The value is a Go regex. In the config yaml it's a list, and on the command line it's a repeatable arg, e.g. --no-cache foo --no-cache bar
  • It's only available in the serve sub-command
  • Each arg value is matched against the canonical URLs cached in the server or some subset, including digest URLs. The server canonicalizes urls on intake. Meaning you can pull by alias but pruning requires the --no-cache arg to use the canonical url. E.g. if you pull docker.io/hello-world:latest, to always re-pull requires --no-cache docker.io/library/hello-world:latest or some matching subset.
  • The patterns provided on the command line replace those in the config file rather than being merged
  • An invalid regex is a startup error
  • The cached copy is served if the upstream pull fails

Loading Images

The following methods are supported to load the server with images.

  1. By specifying a plain text file containing a list of image urls. The server reads the file and pulls each image from the upstream.
  2. By specifying an image tarball created by docker save, ctr images export, etc. The server extracts all images from the tarball into cache.

The --preload-images and --image-file arg values are as follows:

  1. A single filename like foo.txt or bar.tar
  2. A glob expression enclosed in single quotes to prevent shell expansion, e.g. '*.tar', or 'image-list-*.txt'
  3. A comma-separated expression containing all of the above. E.g.: 'foo.txt,bar.tar,image-list*.txt',multi*.tar

The load command also supports --resolve-ref which is an edge-case arg. If you are loading a single-image tarball and you know that the image ref is not correct you can override the image ref like --resolve-ref docker.io/theright/repo:v1.2.3.

Here is an example of an image list file:

cat <<EOF >| imagelist
quay.io/jetstack/cert-manager-cainjector:v1.11.2
quay.io/jetstack/cert-manager-controller:v1.11.2
quay.io/jetstack/cert-manager-webhook:v1.11.2
registry.k8s.io/metrics-server/metrics-server:v0.6.2
registry.k8s.io/ingress-nginx/controller:v1.8.1
registry.k8s.io/pause:3.8
docker.io/kubernetesui/dashboard-api:v1.0.0
docker.io/kubernetesui/metrics-scraper:v1.0.9
docker.io/kubernetesui/dashboard-web:v1.0.0
EOF

Registry Configuration

The OCI Distribution server may need configuration to connect to upstream registries. If run with no configuration for a given registry, the server will default to anonymous insecure HTTPS access. You specify registry configuration using the registries list:

registries:
- name: upstream one
  description: foo
  scheme: https
  auth: {}
  tls: {}
- name: upstream two
  description: bar
  scheme: http
  auth: {}
  tls: {}
- etc...

Each entry supports the following configuration structure overall. Not all values are required. More detail is presented on that below. This shows the full structure:

- name: my-upstream # or my-upstream:PORT, e.g. index.docker.io
  description: Something that makes sense to you (or omit it - it is optional)
  scheme: https # (the default), also accepts http
  auth:
    user: theuser
    password: thepass
    passwordFromEnv: THEPASS_ENV_VAR
    token: {}
  tls:
    ca: /my/ca.crt
    cert: /my/client.cert
    key: /my/client.key
    insecureSkipVerify: true/false # defaults to false

Since scheme defaults to https you can omit that entirely. The tls key is optional. If omitted and scheme is https then the Ociregistry server attempts insecure 1-way TLS. The default for tls.insecureSkipVerify is false if omitted (and tls is specified.) Similarly, description is ignored by the server and can be omitted.

The auth section implements basic auth, just like your ~/.docker/config.json file.

Note

The auth.token configuration element supports token-based authentication using an external service and is documented in the Authentication section.

The name value is the upstream host name that you will pull from. For example say you're running the server on your desktop in test mode on localhost:8080. Let's also say that you have an in-house corporate registry that serves proprietary images on my-corp-registry.myco.org:8888. You run this command to pull through the Ociregistry server from your corporate registry server this way:

docker pull localhost:8080/my-corp-registry.myco.org:8888/my-proprietary-app:v1.0.0
Say your corp registry server requires user and password. Then you would configure a registries entry in the Ociregistry server config file like this:
- name: my-corp-registry.myco.org:8888
  auth:
    user: theuser
    password: thepass

To read the password from an environment variable, use the passwordFromEnv key:

- name: my-corp-registry.myco.org:8888
  auth:
    user: theuser
    passwordFromEnv: THEPASS_ENV_VAR

Here's another scenario. Let's say your corp DNS resolves index.docker.io to an in-house registry mirror that requires an NPE cert. Then your registry entry might look like:

- name: index.docker.io
  tls:
    cert: npe.crt
    key: npe.key

The tls section can implement multiple scenarios:

  1. One-way insecure TLS, in which client certs are not provided to the remote, and the remote server cert is not validated:
    tls:
      insecureSkipVerify: true
    
  2. One-way secure TLS, in which client certs are not provided to the remote, and the remote server cert is validated using the OS trust store:
    tls:
      insecureSkipVerify: false # (or omit, since it defaults to false)
    
  3. One-way secure TLS, in which client certs are not provided to the remote, and the remote server cert is validate using a provided CA cert:
    tls:
      ca: /my/ca.crt
    
  4. mTLS (client certs are provided to the remote):
    tls:
      cert: /my/client.cert
      key: /my/client.key
    
    mTLS can be implemented with and without remote server cert validation as described above in the various one-way TLS scenarios. Examples:
    - name: foo.bar.1.io
      description: mTLS, don't verify server cert
      tls:
        cert: /my/client.cert
        key: /my/client.key
        insecureSkipVerify: true
    - name: foo.bar.2.io
      description: mTLS, verify server cert from OS trust store
      tls:
        cert: /my/client.cert
        key: /my/client.key
        insecureSkipVerify: false
    - name: foo.bar.3.io
      description: mTLS, verify server cert from provided CA
      tls:
        cert: /my/client.cert
        key: /my/client.key
        ca: /remote/ca.crt
        insecureSkipVerify: false
    

Server TLS configuration

By default, the server serves over HTTP. The serverTlsConfig section in the config file configures the Ociregistry server to serve over TLS.

The cert, key, and ca are expected to be PEM encoded files. Example:

serverTlsConfig:
  cert: /path/to/pem/encoded/server.crt
  key: /path/to/pem/encoded/server.private.key
  ca: /path/to/pem/encoded/ca.crt
  clientAuth: none # or verify

Server TLS permutations

The following permutations are supported or serving over HTTPS:

Configuration Description
cert and key populated The server will provide the cert to the client to establish 1-way TLS.
clientAuth: none Client cert is not requested and will be ignored if provided.
clientAuth: verify mTLS: Client cert is required and verified. See the ca key below.
ca populated Client cert is validated against the provided CA.
ca omitted Client cert is validated against the OS trust store.

Prune Configuration

Pruning configures the server to remove images as a background process based on create date or recency of a pull. (Each time an image is pulled the server updates the pull date/time for the image.) Pruning is disabled by default. An example full prune configuration is as follows:

pruneConfig:
  enabled: true
  duration: 30d
  type: accessed
  expr:
  frequency: 1d
  count: -1
  dryRun: true

Prune configuration keys and values

Key Type Description
enabled Boolean If true, enables background pruning.
duration Duration expression E.g.: 30d. The value is interpreted based on the prune type below. Valid time units are ns (nanoseconds), us or µs (microseconds), ms (milliseconds), s (seconds), m (minutes), h (hours), and d (days).
type Keyword Valid values are pattern, accessed and created. If accessed, then the server prunes images that have not been pulled in duration amount of time. If created, then the server prunes images whose create date is older than duration time ago. If pattern, then expr has the pattern value.
expr URL regex E.g. calico. Only used if type is pattern.
frequency Duration expression E.g.: 1d. Run the background pruner with this frequency. The time units are the same as for duration.
count Integer The number of images to prune on each run of the background pruner. A value of -1 means no limit to the number of images pruned. If 0, then the server interprets this as undefined and defaults to 5.
dryRun Boolean Defaults to true: just logs messages but doesn't actually prune. For testing and troubleshooting. Set dryRun: false to actually prune.

Important about prune

  • A prune blocks new upstream pulls while it runs. Cached pulls aren’t affected.
  • If upstream pulls are still running after 10 seconds, the prune is skipped until the next run.