getting-started.md needs revision for cgroup preperation by fully unprivileged users

[emojifreak]

In https://github.com/lxc/linuxcontainers.org/blob/master/content/lxc/getting-started.md it is said that

Now, everything below assumes a recent Ubuntu system or another Linux distribution which offers a similar experience (recent kernel, recent version of shadow, cgmanager and default uid/gid allocation).

Just before you create your first container, you probably should logout and login again, or even reboot your machine to make sure that your user is placed in the right cgroups. (This is only required if cgmanager wasn't installed on your machine prior to you installing LXC.)

As cgmanager is considered retired, it should be updated to libpam-cgfs at least for hybrid cgroup hierarchy. In addition, it is instructed at https://github.com/lxc/lxc/issues/3242#issuecomment-568936099 to use

systemd-run --unit=myshell --user --scope -p "Delegate=yes" lxc-start

This trick for pure cgroup2 hierarchy should also be included in getting-started.md

[eunosm3]

Does resolving this consist of re-writing the above-quoted paragraph with a reference to the new command? If so, I could do that.

[stgraber]

Yep, references to cgmanager should be removed from that page and replaced with libpam-cgfs if not already covered in there.

On top of that, the systemd trick for cgroup2-only systems should be added.

[eunosm3]

Will this suffice? I wasn't sure if the systemd-run command should come before or after the NOTE section.

========================================================================== References to "cgmanager" can be found in three places: once in the Requirements section and twice in the Creating unprivileged containers as a user section.

Requirements Section Update The reference to "cgmanager" in the text should be changed. Current Text Extra dependencies for unprivileged containers:

• libpam-cgfs, cgmanager or another CGroup manager configuring your system for unprivileged CGroups operation
• A recent version of shadow including newuidmap and newgidmap
• Linux kernel >= 3.12

Suggested Update Extra dependencies for unprivileged containers:

• libpam-cgfs or another CGroup manager configuring your system for unprivileged CGroups operation
• A recent version of shadow including newuidmap and newgidmap
• Linux kernel >= 3.12

Creating unprivileged containers as a user Update Current Text Now, everything below assumes a recent Ubuntu system or another Linux distribution which offers a similar experience (recent kernel, recent version of shadow, cgmanager and default uid/gid allocation). ... Just before you create your first container, you probably should logout and login again, or even reboot your machine to make sure that your user is placed in the right cgroups. (This is only required if cgmanager wasn't installed on your machine prior to you installing LXC.)

Suggested Update The following instructions assume the use of a recent Ubuntu system or an alternate Linux distribution offering a similar experience, i.e., a recent kernel and a recent version of shadow, as well as libpam-cgfs and default uid/gid allocation. ... Running unprivileged containers as an unprivileged user only works if you delegate a cgroup in advance (the cgroup2 delegation model enforces this restriction, not liblxc). Use the following systemd command to delegate the cgroup:

systemd-run --unit=myshell --user --scope -p "Delegate=yes" lxc-start <container-name>

NOTE: If libpam-cgfs was not installed on the host machine prior to installing LXC, you need to ensure your user belongs to the right cgroups before creating your first container. You can accomplish this by logging out and logging back in, or by rebooting the host machine.

[stgraber]

Should just be libpam-cgfs as the or another CGroup... part was linked to the cgmanager part that's now gone.

Ordering of systemd-run looks good the way you have it I think.

[Dmole]

systemd-run --unit=myshell --user --scope -p "Delegate=yes" lxc-start < container-name >

Is out of place here on the getting-started page because the user has no idea what "myshell" or "< container-name >" should be.

https://github.com/lxc/linuxcontainers.org/blob/master/content/lxc/getting-started.md?plain=1#L85

also should it should be sudo? Otherwise;

Failed to create bus connection: Permission denied

[x-yuri]

I also came here because of this part:

Running unprivileged containers as an unprivileged user only works if you delegate a cgroup in advance (the cgroup2 delegation model enforces this restriction, not liblxc). Use the following systemd command to delegate the cgroup:

systemd-run --unit=myshell --user --scope -p "Delegate=yes" lxc-start <container-name>

I'm not sure if it's out of place, but:

1. It's confusing. Originally I thought that I have to first execute this command. And only after that I can create/start containers. But it appears that this is a command to start a container. From what I can see after some googling, it creates a transient user scope unit named myshell, allowing it to manage cgroups (a private subhierarchy), and launches lxc-start ... there.
2. It works w/o it (e.g. Debian 8, lxc-2.0.7).

So I'd suggest e.g. the following wording:

Running unprivileged containers as an unprivileged user only works if you delegate a cgroup (the cgroup2 delegation model enforces this restriction, not liblxc). Use the following command to start a container delegating it the cgroup:

After the command it can be added that:

It creates a transient user scope unit named myshell, allowing it to manage cgroups (a private subhierarchy), and launches lxc-start ... there.

By the way, lxc-start <container-name> -> lxc-start -n <container-name>. And double quotes are not needed.