Podman: "open /etc/subuid: no such file or directory" error message

[Nuc1eoN]

I'm a new podman user using ArchLinux; I was a docker user before.

I have tried running podman unprivileged but I am getting an error message with no explanation:
ERRO[0000] cannot find mappings for user <username>: open /etc/subuid: no such file or directory

Appears there already was a bug report about improving the guidance and documentation for this case in #1755

However no such documentation or guidance seems to be in place? Just throwing our an error message without any explanation is definitely not the best user experience, esp. if you migrate from docker to give podman a try.

[TomSweeneyRedHat]

@Nuc1eoN thanks for the feedback, that message could most definitely have a better resolution text. I believe the /etc/subuid & /etc/subgid files were not setup appropriately. The best doc available at the moment that I know is: https://github.com/containers/libpod/blob/master/docs/tutorials/rootless_tutorial.md

hth, and we'll see if we can make that message a bit more intuitive.

[rhatdan]

Well it is in the man page.

man podman
...
Rootless mode
       Podman can also be used as non-root user.  When podman runs in rootless mode, a user namespace is automatically created for the user, defined in /etc/sub‐
       uid and /etc/subgid.

       Containers created by a non-root user are not visible to other users and are not seen or managed by Podman running as root.

       It is required to have multiple uids/gids set for an user.  Be sure the user is present in the files /etc/subuid and /etc/subgid.

       If you have a recent version of usermod, you can execute the following commands to add the ranges to the files

              $ sudo usermod --add-subuids 10000-75535 USERNAME
              $ sudo usermod --add-subgids 10000-75535 USERNAME

       Or just add the content manually.

              $ echo USERNAME:10000:65536 >> /etc/subuid
              $ echo USERNAME:10000:65536 >> /etc/subgid

       See the subuid(5) and subgid(5) man pages for more information.

       Images are pulled under XDG_DATA_HOME when specified, otherwise in the home directory of the user under .local/share/containers/storage.

       Currently the slirp4netns package is required to be installed to create a network device, otherwise rootless containers need to run in the network  names‐
       pace of the host.

   NOTE: Unsupported file systems in rootless mode
       The  Overlay file system (OverlayFS) is not supported in rootless mode.  The fuse-overlayfs package is a tool that provides the functionality of OverlayFS
       in user namespace that allows mounting file systems in rootless environments.  It is recommended to install the fuse-overlayfs package and to enable it by
       adding mount_program = "/usr/bin/fuse-overlayfs" under [storage.options] in the $HOME/.config/containers/storage.conf file.

       The  Network  File  System (NFS) and other distributed file systems (for example: Lustre, Spectrum Scale, the General Parallel File System (GPFS)) are not
       supported when running in rootless mode as these file systems do not understand user namespace.  However, rootless Podman can make use of an  NFS  Homedir
       by modifying the $HOME/.config/containers/storage.conf to have the graphroot option point to a directory stored on local (Non NFS) storage.

       For more information, please refer to the Podman Troubleshooting Page ⟨https://github.com/containers/libpod/blob/master/troubleshooting.md⟩.

[Nuc1eoN]

Maybe then at least, it should mention that you can find this in the man pages and where exactly.

Or give a brief description of the problem. Because cannot find mappings for user bob: open /etc/subuid: no such file or directory does not help a first time user without googling.

[rhatdan]

@giuseppe @vrothberg WDYT
Currently we don't have any errors to tell users to examine man pages. We could change this error to say "Examine Rootless mode in man podman.
I think this would be ok since this will only happen on Linux, and we can figure the man pages will exists on a linux distribution.

[vrothberg]

Sounds good to me :+1: Some error messages are hard to decrypt and sometimes even harder to find a potential solution. Pointing to the man page directly could be really helpful.

[vrothberg]

@Nuc1eoN, are you interested in opening a pull request to change the error message?

[Nuc1eoN]

Haha thanks for asking, but currently I am pretty occupied with other tasks :D

[rhatdan]

@ryanchpowell PTAL