Resolución de problemas

Consejos específicos de la distribución

Limitaciones conocidas

• Solo se admiten los siguientes controladores de almacenamiento:
  • overlay2 (solo si se ejecuta con el kernel 5.11 o posterior)
  • fuse-overlayfs (solo si se ejecuta con el kernel 4.18 o posterior, y fuse-overlayfs está instalado)
  • btrfs (solo si se ejecuta con el kernel 4.18 o posterior, o si ~/.local/share/docker está montado con la opción de montaje user_subvol_rm_allowed)
  • vfs
• cgroup solo se admite cuando se ejecuta con cgroup v2 y systemd. Consulta Limitar recursos.
• Las siguientes características no son compatibles:
  • AppArmor
  • Puntos de control (Checkpoint)
  • Red superpuesta (Overlay network)
  • Exponer puertos SCTP
• Para usar el comando ping, consulta Enrutar paquetes ping.
• Para exponer puertos TCP/UDP privilegiados (< 1024), consulta Exponer puertos privilegiados.
• No se admiten los montajes NFS como "data-root" de docker. Esta limitación no es específica del modo rootless.

Limitaciones históricas

Hasta Docker Engine v29.5

• La dirección IPAddress mostrada en docker inspect tiene espacio de nombres dentro del espacio de nombres de red de RootlessKit. Esto significa que la dirección IP no es accesible desde el anfitrión sin usar nsenter en el espacio de nombres de red.
• La red del anfitrión (docker run --net=host) también tiene espacio de nombres dentro de RootlessKit.

Resolución de problemas

No se puede instalar con systemd cuando systemd está presente en el sistema

$ dockerd-rootless-setuptool.sh install
[INFO] systemd not detected, dockerd-rootless.sh needs to be started manually:
...

rootlesskit no puede detectar systemd correctamente si cambias a tu usuario a través de sudo su. Para los usuarios que no pueden iniciar sesión, debes utilizar el comando machinectl, que forma parte del paquete systemd-container. Después de instalar systemd-container, cambia a myuser con el siguiente comando:

$ sudo machinectl shell myuser@

Donde myuser@ es tu nombre de usuario deseado y @ representa esta máquina.

Errores al iniciar el demonio de Docker

[rootlesskit:parent] error: failed to start the child: fork/exec /proc/self/exe: operation not permitted

Este error ocurre principalmente cuando el valor de /proc/sys/kernel/unprivileged_userns_clone se establece en 0:

$ cat /proc/sys/kernel/unprivileged_userns_clone
0

Para solucionar este problema, añade kernel.unprivileged_userns_clone=1 a /etc/sysctl.conf (o a /etc/sysctl.d) y ejecuta sudo sysctl --system.

[rootlesskit:parent] error: failed to start the child: fork/exec /proc/self/exe: no space left on device

Este error ocurre principalmente cuando el valor de /proc/sys/user/max_user_namespaces es demasiado pequeño:

$ cat /proc/sys/user/max_user_namespaces
0

Para solucionar este problema, añade user.max_user_namespaces=28633 a /etc/sysctl.conf (o a /etc/sysctl.d) y ejecuta sudo sysctl --system.

[rootlesskit:parent] error: failed to setup UID/GID map: failed to compute uid/gid map: No subuid ranges found for user 1001 ("testuser")

Este error ocurre cuando /etc/subuid y /etc/subgid no están configurados. Consulta los Requisitos previos.

could not get XDG_RUNTIME_DIR

Este error ocurre cuando $XDG_RUNTIME_DIR no está configurada.

En un anfitrión sin systemd, necesitas crear un directorio y luego establecer la ruta:

$ export XDG_RUNTIME_DIR=$HOME/.docker/xrd
$ rm -rf $XDG_RUNTIME_DIR
$ mkdir -p $XDG_RUNTIME_DIR
$ dockerd-rootless.sh

Note

Debes eliminar el directorio cada vez que cierres la sesión.

En un anfitrión con systemd, inicia sesión en el anfitrión utilizando pam_systemd (ver a continuación). El valor se establece automáticamente en /run/user/$UID y se limpia en cada cierre de sesión.

systemctl --user falla con "Failed to connect to bus: No such file or directory"

Este error ocurre principalmente cuando cambias del usuario root a un usuario no root con sudo:

# sudo -iu testuser
$ systemctl --user start docker
Failed to connect to bus: No such file or directory

En lugar de sudo -iu <USERNAME>, debes iniciar sesión utilizando pam_systemd. Por ejemplo:

• Inicia sesión a través de la consola gráfica
• ssh <USERNAME>@localhost
• machinectl shell <USERNAME>@

El demonio no se inicia automáticamente

Necesitas ejecutar sudo loginctl enable-linger $(whoami) para habilitar que el demonio se inicie automáticamente. Consulta el Uso avanzado.

Errores de docker pull

docker: failed to register layer: Error processing tar file(exit status 1): lchown <FILE>: invalid argument

Este error ocurre cuando el número de entradas disponibles en /etc/subuid o /etc/subgid no es suficiente. El número de entradas requeridas varía según las imágenes. Sin embargo, 65,536 entradas son suficientes para la mayoría de las imágenes. Consulta los Requisitos previos.

docker: failed to register layer: ApplyLayer exit status 1 stdout: stderr: lchown <FILE>: operation not permitted

Este error ocurre principalmente cuando ~/.local/share/docker se encuentra en un volumen NFS.

Una solución alternativa es especificar un directorio data-root que no sea NFS en ~/.config/docker/daemon.json de la siguiente manera:

{"data-root":"/somewhere-out-of-nfs"}

Errores de docker run

docker: Error response from daemon: OCI runtime create failed: ...: read unix @->/run/systemd/private: read: connection reset by peer: unknown.

Este error ocurre en anfitriones con cgroup v2 principalmente cuando el demonio dbus no se está ejecutando para el usuario.

$ systemctl --user is-active dbus
inactive

$ docker run hello-world
docker: Error response from daemon: OCI runtime create failed: container_linux.go:380: starting container process caused: process_linux.go:385: applying cgroup configuration for process caused: error while starting unit "docker
-931c15729b5a968ce803784d04c7421f791d87e5ca1891f34387bb9f694c488e.scope" with properties [{Name:Description Value:"libcontainer container 931c15729b5a968ce803784d04c7421f791d87e5ca1891f34387bb9f694c488e"} {Name:Slice Value:"use
r.slice"} {Name:PIDs Value:@au [4529]} {Name:Delegate Value:true} {Name:MemoryAccounting Value:true} {Name:CPUAccounting Value:true} {Name:IOAccounting Value:true} {Name:TasksAccounting Value:true} {Name:DefaultDependencies Val
ue:false}]: read unix @->/run/systemd/private: read: connection reset by peer: unknown.

Para solucionar el problema, ejecuta sudo apt-get install -y dbus-user-session o sudo dnf install -y dbus-daemon, y luego vuelve a iniciar sesión.

Si el error persiste, intenta ejecutar systemctl --user enable --now dbus (sin sudo).

--cpus, --memory y --pids-limit son ignorados

Este es un comportamiento esperado en el modo cgroup v1. Para utilizar estas banderas, el anfitrión debe estar configurado para habilitar cgroup v2. Para obtener más información, consulta Limitar recursos.

Errores de red

Esta sección proporciona consejos de resolución de problemas para la red en modo rootless.

La red en modo rootless es compatible a través de controladores de red y de puerto en RootlessKit. El rendimiento y las características de la red dependen de la combinación de controladores de red y de puerto que utilices. Si experimentas un comportamiento inesperado o problemas de rendimiento relacionados con la red, revisa la siguiente tabla que muestra las configuraciones admitidas por RootlessKit y cómo se comparan:

(*) Aplicable desde RootlessKit v3.0. También requiere que userland-proxy esté deshabilitado.

Para obtener información sobre la resolución de problemas de red específicos, consulta:

• docker run -p falla con cannot expose privileged port
• Ping no funciona
• IPAddress mostrado en docker inspect no es accesible
• --net=host no escucha puertos en el espacio de nombres de red del anfitrión
• La red es lenta
• docker run -p no propaga direcciones IP de origen

docker run -p falla con cannot expose privileged port

docker run -p falla con este error cuando se especifica un puerto privilegiado (< 1024) como puerto del anfitrión:

$ docker run -p 80:80 nginx:alpine
docker: Error response from daemon: driver failed programming external connectivity on endpoint focused_swanson (9e2e139a9d8fc92b37c36edfa6214a6e986fa2028c0cc359812f685173fa6df7): Error starting userland proxy: error while calling PortManager.AddPort(): cannot expose privileged port 80, you might need to add "net.ipv4.ip_unprivileged_port_start=0" (currently 1024) to /etc/sysctl.conf, or set CAP_NET_BIND_SERVICE on rootlesskit binary, or choose a larger port number (>= 1024): listen tcp 0.0.0.0:80: bind: permission denied.

Cuando experimentes este error, considera usar un puerto sin privilegios en su lugar. Por ejemplo, 8080 en lugar de 80.

$ docker run -p 8080:80 nginx:alpine

Para permitir la exposición de puertos privilegiados, consulta Exponer puertos privilegiados.

Ping no funciona

Ping no funciona cuando /proc/sys/net/ipv4/ping_group_range está configurado como 1 0:

$ cat /proc/sys/net/ipv4/ping_group_range
1       0

Para más detalles, consulta Enrutar paquetes ping.

IPAddress mostrado en docker inspect no es accesible

Este era un comportamiento esperado hasta Docker Engine v29.5, ya que el demonio tenía espacio de nombres dentro del espacio de nombres de red de RootlessKit. Utiliza docker run -p en su lugar, o actualiza a Docker Engine v29.5 o posterior.

--net=host no escucha puertos en el espacio de nombres de red del anfitrión

Este era un comportamiento esperado hasta Docker Engine v29.5, ya que el demonio tenía espacio de nombres dentro del espacio de nombres de red de RootlessKit. Utiliza docker run -p en su lugar, o actualiza a Docker Engine v29.5 o posterior.

La red es lenta

Docker con modo rootless utiliza slirp4netns como la pila de red predeterminada si slirp4netns v0.4.0 o posterior está instalado. Si slirp4netns no está instalado, Docker recurre a VPNKit. Instalar slirp4netns puede mejorar el rendimiento de la red.

Para obtener más información sobre los controladores de red para RootlessKit, consulta la documentación de RootlessKit.

Asimismo, cambiar el valor de la MTU puede mejorar el rendimiento. El valor de la MTU se puede especificar creando ~/.config/systemd/user/docker.service.d/override.conf con el siguiente contenido:

[Service]
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_MTU=<INTEGER>"

Y luego reinicia el demonio:

$ systemctl --user daemon-reload
$ systemctl --user restart docker

docker run -p no propaga direcciones IP de origen

{"userland-proxy": false}

systemctl --user restart docker

sudo tee /etc/modules-load.d/docker.conf <<EOF >/dev/null
br_netfilter
EOF

sudo systemctl restart systemd-modules-load.service

Para obtener más información sobre las opciones de red para RootlessKit, consulta:

• Controladores de red
• Controladores de puerto

Consejos para la depuración

Entrar en los espacios de nombres de dockerd

El script dockerd-rootless.sh ejecuta dockerd en sus propios espacios de nombres de usuario, montaje y red.

Para depurar, puedes entrar en los espacios de nombres ejecutando nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid).

Desinstalar

Para eliminar el servicio de systemd del demonio de Docker, ejecuta dockerd-rootless-setuptool.sh uninstall:

$ dockerd-rootless-setuptool.sh uninstall
+ systemctl --user stop docker.service
+ systemctl --user disable docker.service
Removed /home/testuser/.config/systemd/user/default.target.wants/docker.service.
[INFO] Uninstalled docker.service
[INFO] This uninstallation tool does NOT remove Docker binaries and data.
[INFO] To remove data, run: `/usr/bin/rootlesskit rm -rf /home/testuser/.local/share/docker`

Elimina las variables de entorno PATH y DOCKER_HOST si las has añadido a tu ~/.bashrc.

Para eliminar el directorio de datos, ejecuta rootlesskit rm -rf ~/.local/share/docker.

Para eliminar los binarios, desinstala el paquete docker-ce-rootless-extras si instalaste Docker con gestores de paquetes. Si instalaste Docker con https://get.docker.com/rootless (Instalar sin paquetes), elimina los archivos binarios bajo ~/bin:

$ cd ~/bin
$ rm -f containerd containerd-shim containerd-shim-runc-v2 ctr docker docker-init docker-proxy dockerd dockerd-rootless-setuptool.sh dockerd-rootless.sh rootlesskit rootlesskit-docker-proxy runc vpnkit