Stabilize std::os::unix::process::CommandExt::chroot (process_chroot)

[joshtriplett]

View all comments

Tracking issue: #141298

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ChrisDenton, libs
• @ChrisDenton, libs expanded to 13 candidates
• Random selection from 6 candidates

[joshtriplett]

This has been around since May 2025, without issue. I think it's more than ready to stabilize. Shall we stabilize it?

@rfcbot merge libs

[rust-rfcbot]

@joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @ChrisDenton
• @Mark-Simulacrum
• @cuviper
• @dtolnay
• @joshtriplett
• @nia-e
• @the8472
• @thomcc

Concerns:

• tests, examples and improved documentation (Stabilize std::os::unix::process::CommandExt::chroot (process_chroot) #163067 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/libs-ping: FCP proposed for libs, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

[Mark-Simulacrum]

Are there any test cases for this? I don't think I see any in the original PR (#137759) or in grep for chroot in our code.

I guess we'd need to condition such a test case on being able to run privileged, but I think in CI we can, so it seems valuable. Absent those, have we confirmed this actually works at least manually?

The os::unix::fs::chroot API is documented as:

This typically requires privileges, such as root or a specific capability.

I assume the same applies here? Can we amend the documentation to note that?

That API is also cfg'd away on fuchsia, instead of returning Unsupported like the process one. I assume we want to go with Unsupported as implemented here (and on slightly more targets - fuchsia, vxworks, wasi)?

[ds84182]

If you use the unshare syscall you can use chroot without needing to run as root (on Linux).

[tgross35]

In addition to the missing tests, there are no examples. They'll have to be no-run but a demo of how you might want to use this would be helpful.

[joboet]

I want to point out that chroot is not specified to be async-signal-safe by POSIX, so we are relying on undocumented platform behaviour here by assuming that it is safe to call after fork.

[nia-e]

fwiw, the docs should probably also mention that - strictly speaking - this function is not documented to be async-signal-safe, and we should link to the docs of chroot. otherwise seems good per today's meeting ^^

[rust-rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[tgross35]

We have requests for tests (if possible), examples, and improved documentation. I think that's all worth a blocking concern, if anybody is willing to raise one on my behalf.

[ChrisDenton]

@rfcbot concern tests, examples and improved documentation

[joshtriplett]

I've posted #163180 to update the documentation. That PR adds an example, adds a manpage link, adds a mention that it requires privileges, and adds an explanation that POSIX doesn't require it to be async-signal-safe but it's safe in practice on our targets.

I don't think a runnable test is feasible; our testsuite shouldn't be run as root. On Linux specifically, we could theoretically provide a test that runs via unshare, but we couldn't run that test on any other target that provides chroot.

[Mark-Simulacrum]

I don't think a runnable test is feasible; our testsuite shouldn't be run as root.

I think if we're going to add root-only APIs to std, we should have a test suite that does require root and runs as such. It seems easy to do that in CI. Infra work for that should be pretty trivial.

[ChrisDenton]

At the end of the day it is a fairly trivial wrapper around libc::chroot so I don't think it's too critical to test libc::chroot behaves as libc::chroot should? That's ultimately up to the platform. I guess it may be useful to test we haven't messed up the wrapper but we're just using the common method to convert paths to CStr.

[tgross35]

I want to point out that chroot is not specified to be async-signal-safe by POSIX, so we are relying on undocumented platform behaviour here by assuming that it is safe to call after fork.

Note that this is an issue 8 doc, but chroot was removed in issue 3. I don't see it mentioned at https://pubs.opengroup.org/onlinepubs/7908799/xsh/chroot.html or the list at https://pubs.opengroup.org/onlinepubs/7908799/xsh/sigaction.html so it still wasn't AS-safe, though I wonder if they would have bothered documenting it at that point.

However, as far as I can tell, no popular platform's manpages say this is safe to do, e.g. https://man7.org/linux/man-pages/man2/chroot.2.html makes no mention and https://man7.org/linux/man-pages/man7/signal-safety.7.html only describes POSIX. Are we actually comfortable enabling this code unconditionally if it might be completely broken? I'm hesitant to take pervasiveness of a pattern in C on some platforms as truth that this will be sound on all platforms that have a chroot.

It seems safer to start with Linux and a few other popular platforms that we can confirm are sound, error on spawn otherwise. And leave it up to target maintainers to enable other platforms if they can confirm soundness. Ideally by updating their documentation...

At the end of the day it is a fairly trivial wrapper around libc::chroot so I don't think it's too critical to test libc::chroot behaves as libc::chroot should? That's ultimately up to the platform. I guess it may be useful to test we haven't messed up the wrapper but we're just using the common method to convert paths to CStr.

We could also totally forget to actually call libc::chroot :) or cfg it out by accident, do_exec is a bit of a gnarly function.

[tgross35]

Started a thread https://inbox.sourceware.org/libc-alpha/44aca4d502f6891df1587ed1c4c9b6a1@trevorgross.com/T/#u

[ChrisDenton]

To be clear, I see no reason why we can't sudo in CI specifically (though probably best not to do that locally) but if we just want to make sure that chroot is called then maybe something like miri can help without needing to actually do a real chroot.

[clarfonthey]

There is also the fakechroot utility used by both Debian and Arch Linux, which intercepts libc calls and provides a fake chroot environment: https://linux.die.net/man/1/fakechroot

I would advise using that, at least on targets where we do definitely call out to libc for all relevant file operations.

[nia-e]

Also for docs, I think this was brought up in the meeting but worth restating publicly here that the docs should specify that it's not actually a security boundary and it's possible to e.g. access directories outside of the chroot ^^

[tgross35]

^ agreed, requested at #163180 (comment)