Inspect and Safely Change containerd 2.3 Configuration

You will finish with a reviewed containerd configuration, a saved backup, and evidence that the daemon accepted it. The examples target containerd 2.3.5 from the Debian package containerd.io version 2.3.5-1~ubuntu.24.04~noble. Allow about 20 minutes, plus time to test any workload that depends on the daemon.

You need a shell and access to the host running containerd. Reading configuration is ordinarily unprivileged. Writing /etc/containerd/config.toml and restarting the service normally require sudo. This guide changes a service configuration, so keep a maintenance window and a rollback copy. Do not paste credentials, registry tokens or private keys into a configuration file while experimenting.

1. Confirm the installed command

Check the binary and version before copying examples. This is a read-only step:

$ command -v containerd
/usr/bin/containerd
$ containerd --version
containerd containerd v2.3.5 1294c24a7da8e5a793ed378161673abe94118892

The command in the local containerd(8) manpage starts the daemon when no subcommand is given. It also provides the config, publish and oci-hook subcommands. Do not run plain containerd from a terminal merely to test it: that starts another foreground daemon and can conflict with the service already listening on the socket.

2. Inspect the generated defaults

Ask the installed program for its complete default TOML. Redirecting output to standard output is read-only:

$ containerd config default | sed -n '1,24p'
version = 4
root = '/var/lib/containerd'
state = '/run/containerd'
temp = ''
disabled_plugins = []
required_plugins = []
oom_score = 0
imports = ['/etc/containerd/conf.d/*.toml']

Do not treat this output as a universal configuration for every containerd release. It is generated by the binary on this host. In this installation the root directory holds persistent containerd metadata and the state directory is runtime state. The generated file also imports TOML fragments under /etc/containerd/conf.d/, so a single-file review may miss an effective setting.

The --config option defaults to /etc/containerd/config.toml. If that file is absent, containerd uses its built-in defaults. If it exists, the daemon reads it and any configured imports. The command does not create the file for you.

3. Compare the file with the effective configuration

First inspect the main file and its imported directory without editing anything:

$ sudo sed -n '1,160p' /etc/containerd/config.toml
$ sudo find /etc/containerd/conf.d -maxdepth 1 -type f -name '*.toml' -print 2>/dev/null

Now ask containerd to merge the main configuration with imported subconfigurations:

$ sudo containerd config dump | sed -n '1,24p'
version = 4
root = '/var/lib/containerd'
state = '/run/containerd'
temp = ''
disabled_plugins = ['io.containerd.grpc.v1.cri']

config dump is the useful comparison when an import or an old configuration makes the result unclear. It shows the final main configuration with imported subconfiguration files. It does not prove that a future service start will succeed after you edit a file, and it does not replace a workload test.

On the inspected host, the existing file disables CRI using the older disabled_plugins = ["cri"] spelling, while the dumped result displays the fully qualified plugin name. That is an operational clue, not a reason to edit it. If Kubernetes or another CRI client uses this host, removing that setting can change availability.

4. Make a reversible configuration change

Choose one setting that you have a clear reason to change. For a harmless demonstration, create a separate review copy of the generated defaults, rather than overwriting the live file:

$ containerd config default > /tmp/containerd-config.toml
$ sed -n '1,24p' /tmp/containerd-config.toml

That temporary file is not used by the service. To change the live configuration, take a root-owned backup and edit the existing file deliberately:

$ sudo cp -p /etc/containerd/config.toml /etc/containerd/config.toml.before-change
$ sudoedit /etc/containerd/config.toml

For an old configuration, containerd config migrate writes the current configuration in the latest format to standard output. The manpage explicitly says that subconfig files are not migrated. Capture and review the result before replacing anything:

$ sudo containerd config migrate > /tmp/containerd-config-migrated.toml
$ sed -n '1,24p' /tmp/containerd-config-migrated.toml

Do not redirect that output directly over /etc/containerd/config.toml. A typo, an interrupted command or an unexpected migration result is easier to recover from when the original is intact.

5. Restart only after review

Check the proposed effective configuration first:

$ sudo containerd config dump > /tmp/containerd-config-effective.toml
$ sed -n '1,24p' /tmp/containerd-config-effective.toml

If the output matches the intended change, restart the system service. This is an elevated, service-disrupting action:

$ sudo systemctl restart containerd
$ systemctl is-active containerd
active

Immediately inspect recent service messages if the restart fails:

$ sudo systemctl status --no-pager containerd
$ sudo journalctl -u containerd -n 60 --no-pager

A failed restart can take the container runtime offline. Do not repeatedly restart while guessing. Restore the known-good file, then retry once:

$ sudo cp -p /etc/containerd/config.toml.before-change /etc/containerd/config.toml
$ sudo systemctl restart containerd
$ systemctl is-active containerd

If the backup is not present or the service still fails, stop and preserve the diagnostics for the host's normal incident process. Do not delete state directories to make a configuration error disappear.

6. Verify the result at the socket and workload

First confirm that the daemon is active and that its configured socket exists:

$ systemctl is-active containerd
active
$ sudo test -S /run/containerd/containerd.sock && echo 'containerd socket present'
containerd socket present

The exact socket path can differ if you changed the gRPC address, so use the effective configuration and service logs as the authority. A running process alone does not prove that clients can use the intended endpoint.

Finally, exercise the client or workload that motivated the change. For example, a Kubernetes host should be checked with its normal CRI health and node checks; a host used directly by another client should use that client's read-only status command. Record the result and the configuration backup location. Do not call the change complete because systemctl alone reports success.