[ACTION REQUIRED] Adopting /run merged filesystem layout

Synopsis: Chainguard is adopting a merged /var/run and /run filesystem layout.

On Mar 2, 2026, Chainguard is merging the contents of the /var/run directory into the /run directory (runmerge). The empty /var/run directly will then be replaced by a symlink to /run. Currently, both of these directories contain variable state information about the current system.

This communication includes the following topics: 

What is changing?

The /var/run directory will no longer be a separate directory, but instead will be a symlink to /run.

Packages which have files in /var/run will be updated to move these files to /run on Mar 2, 2026, and files in /run will also appear in /var/run due to the symlink. 

Images will be rebuilt to include the changes above beginning on Mar 2, 2026.

Why is Chainguard making this change?

This move improves standardization and compatibility. It aligns Chainguard with other Linux distributions and common application expectations, improving overall reliability. We are continuing to refine our filesystem layout to follow the best practices of the Filesystem Hierarchy Standard.

How will this affect me?

You may be affected by these changes in the following situations:

1. You add specific versions of affected packages (listed below) to your Chainguard container images using apk add <package>=<version> 
2. You use apk upgrade to upgrade packages in your Chainguard container images.
3. You move files, create symlinks, or mount volumes on /var/run, or a subdirectory of /var/run.  
4. You install affected packages into a new root folder using apk’s --initdb option, and copying the root folder into the root directory of your runtime image containing an affected package (apk add --no-cache --initdb --root /newroot $PACKAGES).

What do I need to do?

If these changes affect you, follow these steps to prevent issues:

1. If you are using apk add <package>=<version> with an affected package (listed below), continue using images built before Mar 2, 2026 to avoid issues until you can upgrade to a newer package version built after Mar 2, 2026. 
2. Chainguard discourages the use of apk upgrade. However, if you do use this command in an image with an affected package, upgrade to the latest version of the image after Mar 2, 2026 to avoid issues.
3. Ensure you are not moving binaries, libraries, creating symlinks, or mounting volumes on /var/run in your Dockerfiles, and instead use /run. These practices can sometimes lead to unexpected issues and lead to unsupported scenarios. If you have any questions, feel free to ask!
   1. We are not aware of any deployments that do this, but we don't have access to all helm charts. If this happens, please rollback to the previous version of the image and inform the support team.
   2. Keep in mind the FHS guidance for using /var/run or /run, “Programs should not access both /var/run and /run directly, except to access /var/run/utmp.”
4. If you install affected packages into a new root folder as described in the previous section, you must upgrade to the latest version of your image on Mar 2, 2026 to avoid issues. 

FAQs

What packages are being transitioned?

This list was last updated on Dec 1, 2025.

apache-apisix
apache2
atmoz-sftp
avahi
awx
cadvisor-compat
cilium-1.18-compat
cilium-fips-1.14-compat
collectd
docker-selenium-base
fixuid
juicefs-1.2-compat
juicefs-1.3-compat
knative-operator-1.16
knative-operator-1.17
knative-operator-1.18
knative-operator-1.19
knative-operator-fips-1.16
knative-operator-fips-1.17
knative-operator-fips-1.18
knative-operator-fips-1.19
kubelet-csr-approver
kubelet-csr-approver-fips
kyverno-policy-reporter-ui
kyverno-policy-reporter-ui-fips
microvm-init
nginx
openresty
pdns-5.0
pdns-5.0-nosodium
pdns-5.0-recursor-compat
pdns-5.1
pdns-5.1-nosodium
pdns-5.1-recursor-compat
pdns-5.2
pdns-5.2-nosodium
pdns-5.2-recursor-compat
pgpool2-4.2
pgpool2-4.3
pgpool2-4.4
pgpool2-4.5
pgpool2-4.6
php-8.1
php-8.2
php-8.3
php-8.4
php-8.5
qemu
rancher-shell-0.1
rancher-shell-0.2
rancher-shell-0.3
rancher-shell-0.4
rancher-shell-0.5
rancher-shell-fips-0.1
rancher-shell-fips-0.2
rancher-shell-fips-0.3
rancher-shell-fips-0.4
rancher-shell-fips-0.5
samba
squid
suricata
systemtap
tinyproxy

Need help or have questions?

We're here to help - visit our support portal at support.chainguard.dev.

- Chainguard Team