Add more documentation for chroot, including an example and a manpage link - #163180
Open
joshtriplett wants to merge 1 commit into
Open
joshtriplett wants to merge 1 commit into
joshtriplett wants to merge 1 commit into
Conversation
rustbot
added
O-unix
Collaborator
|
r? @JohnTitor rustbot has assigned @JohnTitor. Use Why was this reviewer chosen?The reviewer was selected based on:
|
Collaborator
|
The job Click to see the possible cause of the failure (guessed by this bot) |
tgross35
reviewed
Sep 22, 2026
Comment on lines
207
to
+239
| /// Set the root of the child process. This calls `chroot` in the child process before executing | ||
| /// the command. | ||
| /// | ||
| /// This happens before changing to the directory specified with | ||
| /// [`process::Command::current_dir`], and that directory will be relative to the new root. | ||
| /// | ||
| /// If no directory has been specified with [`process::Command::current_dir`], this will set the | ||
| /// directory to `/`, to avoid leaving the current directory outside the chroot. (This is an | ||
| /// intentional difference from the underlying `chroot` system call.) | ||
| /// | ||
| /// This typically requires privileges, such as root or a specific capability. | ||
| /// | ||
| /// Note that according to the POSIX standard, `chroot` is not required to be async-signal-safe, | ||
| /// and functions called between `fork` and `exec` must be async-signal-safe. However, in | ||
| /// practice, the ability to `fork` then `chroot` then `exec` is a capability widely provided by | ||
| /// Rust targets and relied upon by numerous programs. | ||
| /// | ||
| /// See the [`chroot`] manual page for more details. | ||
| /// | ||
| /// [`chroot`]: https://man7.org/linux/man-pages/man2/chroot.2.html | ||
| /// | ||
| /// # Examples | ||
| /// | ||
| #[cfg_attr(target_family = "unix", doc = "```no_run")] | ||
| #[cfg_attr(not(target_family = "unix"), doc = "```ignore (needs unix)")] | ||
| /// use std::process::Command; | ||
| /// use std::os::unix::process::CommandExt; | ||
| /// | ||
| /// Command::new("contained") | ||
| /// .chroot("/sandbox") | ||
| /// .spawn()? | ||
| /// .wait()?; | ||
| #[doc = "```"] |
Member
There was a problem hiding this comment.
We should probably also document this important bit of the manpage:
In particular, it is not intended to be used for any kind of security purpose, neither to fully sandbox a process nor to restrict filesystem system calls.
So maybe also "other_root" rather than "sandbox" in the example
| /// Command::new("contained") | ||
| /// .chroot("/sandbox") | ||
| /// .spawn()? | ||
| /// .wait()?; |
Member
There was a problem hiding this comment.
Needs # Ok::<_, Box<dyn std::error::Error>>(()) at the end like the others
Comment on lines
+219
to
+222
| /// Note that according to the POSIX standard, `chroot` is not required to be async-signal-safe, | ||
| /// and functions called between `fork` and `exec` must be async-signal-safe. However, in | ||
| /// practice, the ability to `fork` then `chroot` then `exec` is a capability widely provided by | ||
| /// Rust targets and relied upon by numerous programs. |
Member
There was a problem hiding this comment.
Maybe not worth mentioning posix specifically? Since chroot hasn't been defined there since 2001
Member
|
r? me |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
As requested in #163067 .
This 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.