feat: add support for userns #3941

Shubhranshu153 · 2025-02-26T23:18:30Z

Adds support for running containers with custom user namespace mappings through
the --userns flag in 'run' and 'create' commands.

Key Features:

Parse and utilize UID/GID mappings from /etc/subuid and /etc/subgid
Support multi-entry mappings for user namespace configurations
Integrate with containerd's remapping capabilities

Technical Details:

Depends containerd.WithUserNSRemapperLabels for namespace configuration. So containerd mainline is required to compile. It can be run on containerd 1.7 if snapshotter support remap-ids.
For native snapshotter overlay snapshotter with remapping support is added in containerd 2.x (>2.0.x)

Dependencies:

Requires containerd with UserNSRemapperLabels support
Compatible with overlay snapshotter in containerd mainline

Testing:

Added unit tests for mapping configurations
Added integration tests for container isolation

This enhancement improves container isolation by providing
flexible user namespace mapping capabilities.

Size: XL

Shubhranshu153 · 2025-02-26T23:19:04Z

cmd/nerdctl/container/container_create_linux_test.go

+				Setup: func(data test.Data, helpers test.Helpers) {
+					data.Set("validUserns", "nerdctltestuser")
+					data.Set("expectedHostUID", "123456789")
+					// need to be compiled with containerd version >2.0.2 to support multi uidmap and gidmap.


change comment to 2.1.x

AkihiroSuda · 2025-02-27T00:09:30Z

cmd/nerdctl/container/container_create_linux_test.go

+	return nil
+}
+
+func addUser(username string, hostId string) error {


This is scary to run by default. Needs to have an opt-in flag like -test.allow-modify-user

Similar:

nerdctl/pkg/testutil/testutil.go

Line 557 in c12aaa3

flag.BoolVar(&flagTestKillDaemon, "test.allow-kill-daemon", false, "enable tests that kill the daemon")

AkihiroSuda · 2025-02-27T00:11:53Z

cmd/nerdctl/container/container_create_linux_test.go

+		}
+
+		newContent := strings.ReplaceAll(string(content), entry, "")
+		if err := os.WriteFile(file, []byte(newContent), 0644); err != nil {


This is scary too. Needs to be opt-in.

Also, the content of /etc/subuid and /etc/subgid has to be backed up and has to be restored with defer()

AkihiroSuda · 2025-02-27T00:12:16Z

cmd/nerdctl/container/container_create_linux_test.go

+}
+
+func delUser(username string) error {
+	cmd := exec.Command("sudo", "userdel", username)


sudo shouldn't be needed when the test is running as the root

AkihiroSuda · 2025-02-27T00:13:35Z

go.mod

 	github.com/containerd/cgroups/v3 v3.0.5
 	github.com/containerd/console v1.0.4
 	github.com/containerd/containerd/api v1.8.0
-	github.com/containerd/containerd/v2 v2.0.2
+	github.com/containerd/containerd/v2 v2.0.1-0.20250211161307-525332b29211


Would it be possible to cherry-pick the relevant commit to v2.0?

may not be the commit entirely but only the relevant functions as it is client side.

AkihiroSuda · 2025-02-27T00:14:02Z

pkg/api/types/container_types.go

@@ -264,6 +264,9 @@ type ContainerCreateOptions struct {

 	// ImagePullOpt specifies image pull options which holds the ImageVerifyOptions for verifying the image.
 	ImagePullOpt ImagePullOptions
+
+	// Userns name for user namespace mapping of container
+	Userns string


Suggested change

Userns string

UserNS string

Because Userns looks like Users

AkihiroSuda · 2025-02-27T00:14:30Z

pkg/cmd/container/create.go

@@ -185,6 +185,27 @@ func Create(ctx context.Context, client *containerd.Client, args []string, netMa
 	opts = append(opts, rootfsOpts...)
 	cOpts = append(cOpts, rootfsCOpts...)

+	if options.Userns != "" {
+		if runtime.GOOS != "linux" || rootlessutil.IsRootless() {
+			return nil, generateRemoveStateDirFunc(ctx, id, internalLabels), errors.New("userns is only supported on linux")


The error is confusing when running in rootless mode on linux

AkihiroSuda · 2025-02-27T00:17:24Z

cmd/nerdctl/container/container_run.go

@@ -279,6 +279,7 @@ func setCreateFlags(cmd *cobra.Command) {
 	cmd.Flags().String("ipfs-address", "", "multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs)")

 	cmd.Flags().String("isolation", "default", "Specify isolation technology for container. On Linux the only valid value is default. Windows options are host, process and hyperv with process isolation as the default")
+	cmd.Flags().String("userns", "", "Support idmapping of containers. This options is only supported on linux. If `host` is passed, no idmapping is done. if a user name is passed, it does idmapping based on the uidmap and gidmap ranges specified in /etc/subuid and /etc/subgid respectively")


Please add docs/command-reference.md.

Also, the command line seems incompatible with Docker?
Docker doesn't accept a username here, and the name is hardcoded to "dockremap".
Maybe we should have its equivalent as "nerdremap"?

Podman accepts --subuidname string --subgidname string to specify a custom user name

Also, the command line seems incompatible with Docker?
if they add host it will behave as docker as we check for that string and create the default snapshot.

For other names it behaves as docker daemon but at a container level rather than at daemon level. Will you suggest we configure it in nerdctl config instead?

For other names it behaves as docker daemon but at a container level rather than at daemon level. Will you suggest we configure it in nerdctl config instead?

Eventually, the both level should be supported, as in Podman: https://github.com/containers/podman/blob/v5.4.1/docs/source/markdown/options/userns.container.md?plain=1

podman run --userns=auto allocates subuids from the "containers" entry in /etc/subuid.

When userns=... is specified in containers.conf, Podman enables UserNS globally, unless --userns=host is specified.

nerdctl should probably follow the same convention, but s/containers.conf/nerdctl.toml/

Not all the features need to be implemented at once. Can just begin with the easiest one.

Signed-off-by: Shubharanshu Mahapatra <[email protected]>

AkihiroSuda · 2025-03-20T17:58:49Z

pkg/testutil/testutil.go

@@ -555,6 +556,7 @@ var (
 func M(m *testing.M) {
 	flag.StringVar(&flagTestTarget, "test.target", Nerdctl, "target to test")
 	flag.BoolVar(&flagTestKillDaemon, "test.allow-kill-daemon", false, "enable tests that kill the daemon")
+	flag.BoolVar(&flagTestUserNS, "test.allow-modify-user", false, "enable tests on userns")


Suggested change

flag.BoolVar(&flagTestUserNS, "test.allow-modify-user", false, "enable tests on userns")

flag.BoolVar(&flagTestModifyUsser, "test.allow-modify-user", false, "enable tests that creates/deletes user accounts on the host")

The intent is to clarify that the tests modifies the host system (and potentially breaks it, in the worst case)

AkihiroSuda · 2025-03-20T18:02:02Z

pkg/testutil/nerdtest/requirements.go

@@ -360,3 +363,33 @@ var Private = &test.Requirement{
 		}
 	},
 }
+
+var ContainerdV1 = &test.Requirement{


Better to use the introspection API to check the existence of the relevant plugin (which one?)

nerdctl/pkg/cmd/container/run_restart.go

Line 36 in 39058fb

res, err := client.IntrospectionService().Plugins(ctx, "id==restart")

AkihiroSuda · 2025-03-20T18:02:50Z

go.mod

 	github.com/compose-spec/compose-go/v2 v2.4.9
 	github.com/containerd/accelerated-container-image v1.3.0
 	github.com/containerd/cgroups/v3 v3.0.5
 	github.com/containerd/console v1.0.4
 	github.com/containerd/containerd/api v1.8.0
-	github.com/containerd/containerd/v2 v2.0.4
+	github.com/containerd/containerd/v2 v2.0.1-0.20250211161307-525332b29211


Suggested change

github.com/containerd/containerd/v2 v2.0.1-0.20250211161307-525332b29211

github.com/containerd/containerd/v2 v2.1.0-beta.0

Shubhranshu153 commented Feb 26, 2025

View reviewed changes

AkihiroSuda added impact/major kind/feature labels Feb 27, 2025

AkihiroSuda reviewed Feb 27, 2025

View reviewed changes

AkihiroSuda mentioned this pull request Feb 26, 2025

Update the list of the unimplemented Docker features (and implement them) #3867

Open

7 tasks

feat: add support for userns

068faa5

Signed-off-by: Shubharanshu Mahapatra <[email protected]>

Shubhranshu153 force-pushed the feat-nerdctl-userns branch from e094328 to 068faa5 Compare March 20, 2025 17:54

AkihiroSuda reviewed Mar 20, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add support for userns #3941

feat: add support for userns #3941

Shubhranshu153 commented Feb 26, 2025

Shubhranshu153 Feb 26, 2025

AkihiroSuda Feb 27, 2025 •

edited

Loading

AkihiroSuda Feb 27, 2025

AkihiroSuda Feb 27, 2025

Shubhranshu153 Mar 14, 2025

AkihiroSuda Feb 27, 2025

Shubhranshu153 Mar 14, 2025

AkihiroSuda Feb 27, 2025

Shubhranshu153 Mar 14, 2025

AkihiroSuda Feb 27, 2025

Shubhranshu153 Mar 14, 2025

AkihiroSuda Feb 27, 2025

AkihiroSuda Feb 27, 2025

Shubhranshu153 Mar 14, 2025

AkihiroSuda Mar 15, 2025

AkihiroSuda Mar 20, 2025 •

edited

Loading

AkihiroSuda Mar 20, 2025

AkihiroSuda Mar 20, 2025

	flag.BoolVar(&flagTestUserNS, "test.allow-modify-user", false, "enable tests on userns")
	flag.BoolVar(&flagTestModifyUsser, "test.allow-modify-user", false, "enable tests that creates/deletes user accounts on the host")

	github.com/containerd/containerd/v2 v2.0.1-0.20250211161307-525332b29211
	github.com/containerd/containerd/v2 v2.1.0-beta.0

feat: add support for userns #3941

Are you sure you want to change the base?

feat: add support for userns #3941

Conversation

Shubhranshu153 commented Feb 26, 2025

Choose a reason for hiding this comment

AkihiroSuda Feb 27, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AkihiroSuda Mar 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AkihiroSuda Feb 27, 2025 •

edited

Loading

AkihiroSuda Mar 20, 2025 •

edited

Loading