Configuration

containerd reads its config from /etc/containerd/config.toml (path configurable with --config). The schema is defined in cmd/containerd/server/config/config.go.

Top-level fields

version = 3                  # config schema version (1 → v1, 2 → v2, 3 → v2-with-late-deprecations)
root    = "/var/lib/containerd"
state   = "/run/containerd"
plugin_dir = ""              # for non-builtin plugins (deprecated)
disabled_plugins = []        # by plugin URI (e.g. "io.containerd.snapshotter.v1.btrfs")
required_plugins = []        # daemon refuses to start without these
oom_score = 0                # set the daemon's /proc/self/oom_score_adj
imports  = []                # additional toml files to merge in

[grpc]
  address = "/run/containerd/containerd.sock"
  tcp_address = ""
  tcp_tls_ca = ""
  tcp_tls_cert = ""
  tcp_tls_key = ""
  uid = 0
  gid = 0
  max_recv_message_size = 16777216
  max_send_message_size = 16777216

[ttrpc]
  address = "/run/containerd/containerd.sock.ttrpc"
  uid = 0
  gid = 0

[debug]
  address = "/run/containerd/debug.sock"
  uid = 0
  gid = 0
  level = ""               # "" → info, otherwise debug/trace/warn/error
  format = ""              # "" → text, "json" → JSON
[debug.daemon]
  format = ""

[metrics]
  address = ""              # leave empty to disable
  grpc_histogram = false

[cgroup]
  path = ""

[timeouts]
  "io.containerd.timeout.shim.cleanup" = "5s"
  "io.containerd.timeout.shim.load" = "5s"
  "io.containerd.timeout.shim.shutdown" = "3s"
  "io.containerd.timeout.task.state" = "2s"

Per-plugin sections

Each plugin reads its config from [plugins."<URI>"]. Examples:

[plugins."io.containerd.snapshotter.v1.overlayfs"]
  root_path = ""

[plugins."io.containerd.gc.v1.scheduler"]
  pause_threshold = 0.02
  deletion_threshold = 0
  mutation_threshold = 100
  schedule_delay = "0s"
  start_delay = "100ms"

[plugins."io.containerd.cri.v1.runtime"]
  default_runtime_name = "runc"
  enable_unprivileged_ports = true
  enable_unprivileged_icmp = true

[plugins."io.containerd.cri.v1.runtime".containerd.runtimes.runc]
  runtime_type = "io.containerd.runc.v2"
  [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.runc.options]
    SystemdCgroup = true

[plugins."io.containerd.cri.v1.images"]
  snapshotter = "overlayfs"
  disable_snapshot_annotations = true

[plugins."io.containerd.tracing.processor.v1.otlp"]
  endpoint = "http://otel-collector:4317"

The full per-plugin schema lives next to each plugin's source — e.g. internal/cri/config/ for the CRI sections.

Proxy plugins

[proxy_plugins]
  [proxy_plugins.customsnap]
    type = "snapshot"     # or "content", "diff", "sandbox"
    address = "/run/customsnap.sock"
    platform = "linux/amd64"

    [proxy_plugins.customsnap.exports]
      key = "value"        # arbitrary metadata exposed via introspection

    [proxy_plugins.customsnap.capabilities]
      # capabilities specific to the proxy type

server.LoadPlugins (in cmd/containerd/server/server.go) translates each entry into a plugin.Registration whose InitFn dials the configured socket.

Stream processors

stream_processors are external binaries that the unpack pipeline pipes layer streams through (e.g. for decryption).

[stream_processors]
  [stream_processors."io.containerd.ocicrypt.decoder.v1"]
    accepts = ["application/vnd.oci.image.layer.v1.tar+gzip+encrypted"]
    returns = "application/vnd.oci.image.layer.v1.tar+gzip"
    path = "/usr/local/bin/ctd-decoder"
    args = ["--decryption-keys-path", "/etc/containerd/ocicrypt"]

See core/diff/binaryio.go for the wiring.

Dumping the effective config

containerd config default       # print compiled-in defaults
containerd config dump          # print defaults merged with the active config file
containerd config migrate       # convert v1/v2 config to v3

Where each section is parsed

Section	Parser
top-level + grpc + ttrpc + debug + metrics	cmd/containerd/server/config/
[plugins."io.containerd.cri.v1.runtime"]	internal/cri/config/
[plugins."io.containerd.snapshotter.v1.<id>"]	the corresponding snapshotter package
[plugins."io.containerd.gc.v1.scheduler"]	plugins/gc/scheduler.go
[plugins."io.containerd.tracing.processor.v1.otlp"]	plugins/server/internal/
[plugins."io.containerd.nri.v1.nri"]	plugins/nri/